tutti/docs/architecture/workspace-workflows.md

# Tutti Mode Activation And Workspace Workflows

This document describes the Tutti-owned activation and workflow models used by
Tutti Mode Plan. It covers the daemon business core, the Agent CLI boundary,
AgentGUI projection, and Issue materialization.

## Ownership Boundary

Tutti Mode is a Tutti-owned host preference, not a provider-native Agent mode
or a capability granted to the Agent. Agent sessions and turns provide
association, isolation, and provenance, but they do not own the Tutti
activation, proposal, user decision, or resulting Issue. Tutti CLI
availability is a separate runtime capability and never derives from the
activation badge.

Ownership is split as follows:

- `services/tuttid/biz/tuttimodeactivation` defines the durable activation and
  immutable revision vocabulary.
- `services/tuttid/service/tuttimodeactivation` owns activation transitions,
  submission snapshots, and post-commit publication.
- `services/tuttid/biz/workspaceworkflow` defines the durable workflow entities
  and state vocabulary.
- `services/tuttid/service/tuttimodeplan` validates Markdown revisions,
  enforces transitions, projects executable work, and coordinates downstream
  operations.
- `services/tuttid/biz/tuttimodeexecution` defines the durable Tutti execution
  aggregate and checkpoint vocabulary.
- `services/tuttid/service/tuttimodeexecution` owns Tutti execution
  materialization and later orchestration commands.
- `services/tuttid/data/workspace` stores workflow metadata in SQLite. Plan
  content is kept in immutable files under the Tutti state directory.
- `services/tuttid/service/cli/providers/tuttimodeplan` exposes Agent-callable
  propose, revise, and get commands. It deliberately exposes no decision
  command and no wait/poll command: the agent's turn ends after propose or
  revise, and the user's review decision reaches the agent as a new user
  message.
- `packages/agent/gui/workspaceWorkflow` renders the daemon snapshot and sends
  user decisions through the desktop runtime adapter. It contains no workflow
  business state machine.
- Workspace Issue Manager owns the Issue and task graph after an accepted
  task-graph revision is materialized.

Provider-native Plan mode remains independent. `/plan` may enable a provider's
planning behavior, while `/tutti` creates or advances a Tutti-owned
`TuttiModeActivation`. The badges are compatible, and removing either badge
only disables that modifier. The Tutti badge creates durable activation state,
not a workflow; a workflow begins only when the Agent invokes the Tutti CLI.
Workflow CLI capabilities remain discoverable when activation is inactive, but
their mutation paths require the user-controlled activation to be active. The
Agent has no CLI or service mutation that can change this state; it must ask the
user to turn Tutti Mode on manually. The persisted `agent_command` source is
retained only so revisions written by older builds remain readable.

## Durable And Derived Entities

| Entity                      | Persistence                                  | Purpose and relations                                                                                                                                                                                                                  |
| --------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TuttiModeActivation`       | SQLite                                       | Tutti-owned session-associated activation root. It points to the current immutable activation revision; Agent Session exposes only an independent read projection.                                                                     |
| `ActivationRevision`        | SQLite                                       | Append-only active or inactive transition. A submitted Turn uses one exact revision so later badge changes cannot rewrite running or historical work.                                                                                  |
| `WorkspaceAgentSubmitClaim` | SQLite                                       | Generic idempotency record from `clientSubmitId` to one preallocated canonical Turn ID. A prepared claim is retained when delivery is ambiguous, so a retry reconciles or reports unknown instead of dispatching again.                |
| `TuttiModeTurnSnapshot`     | SQLite                                       | First-write-wins link from one canonical Turn to the exact activation revision observed before provider dispatch. Same-Turn guidance reuses it instead of reading current state.                                                       |
| `WorkspaceWorkflow`         | SQLite                                       | Tutti-owned lifecycle root. It belongs to one workspace, records its source Agent session and any trusted turn/tool-call provenance available at creation, and points to the current revision.                                         |
| `TuttiModePlan`             | SQLite                                       | Type-specific one-to-one marker for a `WorkspaceWorkflow`. It does not contain plan text.                                                                                                                                              |
| `PlanRevision`              | SQLite metadata plus immutable Markdown file | Append-only version of the proposal. Metadata records sequence, schema, path, SHA-256, and producing turn.                                                                                                                             |
| `WorkflowCheckpoint`        | SQLite                                       | A user-owned decision gate bound to exactly one revision. The task review is the only active checkpoint kind; the configuration-review kind survives solely as legacy vocabulary on retired workflows.                                 |
| `WorkflowTurnLink`          | SQLite                                       | Optional provenance link from a workflow to source, decomposition, revision, or feedback turns.                                                                                                                                        |
| `WorkflowOperation`         | SQLite                                       | Idempotent record of a downstream side effect such as generating a task graph, creating a revision, or creating an Issue. A successful Issue operation stores the Issue ID.                                                            |
| `WorkflowMutation`          | SQLite                                       | Durable caller mutation ledger for propose/revise response-loss recovery. Its scoped request ID is the identity; the input SHA-256 detects conflicting reuse, and the row points to the committed workflow/revision/checkpoint result. |
| `ActionableItem`            | Derived only                                 | Read-only projection of a task from the accepted current task-graph revision. It is never a second task store.                                                                                                                         |
| Workspace Issue and Task    | SQLite in Issue Manager                      | Reusable Issue graph materialized from accepted `ActionableItem`s. It links back through `sourceSessionId`; the workflow operation links forward through `issueId`.                                                                    |
| Tutti execution             | SQLite                                       | Tutti-owned orchestration authority for one accepted workflow and Issue. Initial status is `awaiting_schedule` at graph revision 1.                                                                                                    |
| Execution checkpoint        | SQLite                                       | Ordered durable orchestration gate. Materialization creates one active `initial_schedule` checkpoint and no Issue Run; every terminal Run later appends one deterministic settlement checkpoint.                                       |
| Execution mutation          | SQLite                                       | Source-session-scoped mutation ledger for exact checkpoint/revision graph changes. It provides replay/conflict detection and records the incremented graph revision.                                                                   |

The relation is:

```text
clientSubmitId --- WorkspaceAgentSubmitClaim --- canonical Agent Turn
                                                     |
                                                     v
Agent Session 1 ----- 0..1 TuttiModeActivation
                              |
                              +--- * ActivationRevision
                              |          |
                              |          +--- * TuttiModeTurnSnapshot ---+

Agent Session / Turn / Tool Call (workflow provenance)
                  |
                  v
         WorkspaceWorkflow 1 --- 1 TuttiModePlan
                  |
                  +--- * PlanRevision --- 1 immutable Markdown file
                  |          |
                  |          +--- * WorkflowCheckpoint
                  |
                  +--- * WorkflowTurnLink --- Agent Turn
                  |
                  +--- * WorkflowOperation --- 0..1 Workspace Issue
                  |
                  +--- * WorkflowMutation --- committed revision/checkpoint result
                                  ^
                                  |
          accepted current task-graph revision
                  -> ActionableItem projection
                  -> Workspace Issue + Tasks
                  -> Tutti execution + initial_schedule checkpoint
```

`ActionableItem` exists only when the current revision is a `task_graph`, its
bound checkpoint is accepted, and that revision is still current. Pending,
rejected, superseded, and stale revisions project no executable work.

`TuttiModeActivation` and `WorkspaceWorkflow` are independent roots. Activating
the badge does not create a workflow, and invoking the CLI without an active
badge may still create a workflow. A workflow reaches an activation revision
only indirectly through its source Turn provenance; it never changes the
badge.

The Agent CLI runtime context supplies `AgentSessionID` as the workflow
association and isolation key. `plan revise` and `plan get`
require the same caller session as the workflow's `sourceSessionId`; a mismatch
is deliberately reported as not found. This is a local capability boundary,
not a claim that an environment variable is a malicious-client authentication
credential. The daemon host is responsible for constructing the CLI runtime
context. Agent plan proposal and revision commands require the exact active
Turn ID from that context and fail closed when it is unavailable. The plan
service resolves that Turn through the activation service and verifies the
document's explicit `execution.effect` and `execution.speed` equal its frozen
snapshot before writing an immutable revision or workflow mutation. It never
substitutes the mutable current Session preferences. `sourceToolCallId` remains
empty until a trusted tool-call seam exists; App CLI `ParentCommandID` is
nested-command context and must never be recorded as an Agent tool-call ID.

The same caller authority applies after Issue materialization. Generic Issue
Manager mutations cannot modify a `tutti_mode_plan` graph; they return
`tutti_issue_managed` with `recommendedAction = open_source_session`. The
source Agent uses `tutti plan issue mutate` and supplies the active execution
checkpoint and expected graph revision. Admission validates all operations and
the resulting dependency graph in one SQLite transaction, advances the graph
revision, rebinds the checkpoint, and cancels stale prepared/dispatched Goal
Review state and reviewer wakes. Logical supersession preserves obsolete
task/Run/output history while removing that task from the active projection;
running tasks must settle before they can be superseded.

## Activation And Turn Snapshot Flow

Before a Session exists, AgentGUI keeps the `/tutti` choice as an engine-owned
pending activation intent. Session creation carries that intent explicitly;
the daemon persists the Activation before starting the initial submission and
returns the independent read projection. Existing-session badge changes use a
revision-checked, idempotent activation command.

For every initial submission or ordinary Turn, the daemon allocates the
canonical Turn ID before provider dispatch. When a `clientSubmitId` is present,
the generic submit claim durably reserves that exact ID first. The daemon then
persists a `TuttiModeTurnSnapshot` under the same ID before calling the runtime.
A persistence failure therefore cannot start provider work. The runtime must
accept and return that exact ID; it may not replace it with a runtime-generated
one. Same-Turn guidance reads the already-bound snapshot instead of observing
the current badge. A missing snapshot for an existing Turn fails closed rather
than being reinterpreted as inactive. Removing the badge appends an inactive
revision: it cannot alter an in-flight Turn, while the next new Turn receives
the inactive snapshot. An explicit inactive revision retains its activation
identity; a Session that has never been activated uses the canonical
unconfigured inactive snapshot.

Runtime acceptance has three explicit outcomes. A definite pre-dispatch
rejection abandons the prepared snapshot and submit claim. The API maps
`clientSubmitId` into typed create/send input, and the service passes it through
typed runtime input instead of recovering it from diagnostics metadata. After
`Exec` reports provider acceptance, the Agent service explicitly invokes the
required `RuntimeController.DurablyReportSubmitProvenance` method before any
snapshot or claim promotion. The runtime adapter only maps and delegates this
typed call. Because it occurs after `Exec` releases the Session lifecycle lock,
the controller can wait on an uncoalesced FIFO durability barrier: the ordinary
submitted report must already have created the canonical Turn, then one SQLite
transaction writes the enriched Session projection and stable `clientSubmitId`
user message against that exact Turn. After the barrier succeeds, the service
accepts the bound snapshot, then reads the exact message provenance back before
accepting the submit claim; retry reconciliation repeats both promotions
idempotently. A
barrier failure, or an accepted response with a different Turn ID, retains the
claim, Session, activation, and snapshot.
A retry with the same `clientSubmitId` first reconciles the preallocated Turn
only against durable per-submit provenance and never performs a second
provider dispatch while delivery remains unknown. A live runtime Turn, an
accepted activation snapshot, or a matching Turn ID without that submit
provenance is not enough evidence—especially because multiple guidance
submissions may target the same Turn. This is an intentional at-most-once
safety boundary; ambiguity is surfaced rather than guessed away. A crash after
claim reservation but before the barrier commits leaves a prepared—not
accepted—claim conservatively unknown. A crash after the barrier commits is
deterministically reconciled from the stable message without another provider
dispatch. Same-Turn guidance uses one distinct message per `clientSubmitId`, so
multiple guidance submissions remain independently recoverable without
rewriting the active Turn lifecycle.

The runtime derives a canonical Tutti-owned Host Context only from that exact
snapshot. It does not derive instructions from `capabilityRefs`, user Prompt
text, transcript markers, or arbitrary metadata. Provider adapters use the
strongest host seam they expose. Codex uses developer instructions when its
collaboration-mode contract is available; Codex without that negotiated seam
and standard ACP use a provider-transport-only synthetic prompt block; Claude
uses a coordinator-owned synthetic message. These fallbacks are transport
details, not user-authored messages: Tutti's visible user message, prompt
preview, and activity transcript remain unchanged. The context explicitly
distinguishes Tutti activation from provider Default/Plan mode and reasoning
effort. Reusing an existing provider Session does not weaken that boundary:
each new Turn receives the current immutable activation snapshot before
dispatch. The snapshot's `state` is the sole authority for reporting Tutti Mode
status; provider Default/Plan mode and workflow existence are independent facts
that cannot override it. A clear plan request still enters the Tutti proposal
workflow instead of returning a chat-only plan. An active snapshot is a
directive, not a suggestion: the Agent must
not execute the user's request directly in that turn. It first asks focused
clarifying questions when the request is ambiguous or missing key
constraints, then submits one complete tutti-mode-plan/v1 document through a
single run of the `tutti plan propose` shell command and then ends the turn
immediately — there is no wait command, and the user's review decision
always arrives as a new user message. Because providers repeatedly misread
the bare directive as a built-in tool they lack and fall back to provider
planning surfaces (`update_plan`, TodoWrite, chat-only Markdown plans), the
active context also carries one worked example per workflow step: the
resolved CLI executable name (`tutti-dev` on development installs), the
exact `plan propose` / `plan revise` command lines, and a minimal
valid plan document showing the frontmatter task graph. The guide requires a
complete launch configuration on every task — `agentTargetId`, `model`, and
`permissionModeId` copied from `agent composer-options` output, never
invented — plus explicit `execution.effect` / `execution.speed` preference
snapshots. The existing v1 `reasoningIntensity` and
`orchestrationIntensity` fields retain their provider-reasoning and
Issue-orchestration meanings; speed is never encoded into
`orchestrationIntensity`. It routes model assignment through the injected
`$tutti-model-allocation` skill so C0-C3 task requirements, the effect floor,
speed ranking, hard capabilities, and effect-scaled validation are applied
consistently. The skill ranks joint Agent/model candidates across every
plausible target: the planning Agent, current provider/model, and provider
defaults receive no affinity bonus, while an equally qualified non-planning
target wins the tie for safely independent work so the planner remains
available for coordination and final integration. Unless the user asks for
supervised execution, the guide directs agents to the permission mode whose
semantic is `full-access` (codex `full-access`, claude-code
`bypassPermissions`): the user's approval happens once at plan review, so
accepted tasks must not stall on mid-task approval prompts. The same resolved
CLI name is used by the plan-revision feedback prompt.
Read-only investigation is allowed while writing the plan; provider-native
planning modes must not substitute for the Tutti plan workflow. Activation
still does not gate tool availability—Tutti CLI capabilities remain available
whether the state is active or inactive—but executing work the user has not
accepted through plan review goes against the user's intent.

## Markdown Revision Contract

Every proposal file uses the `tutti-mode-plan/v1` schema: YAML frontmatter
followed by a non-empty Markdown body. The flow is single-shot: every revision
is one complete document containing the plan narrative (body) plus the full
task graph (`tasks` frontmatter, at least one task, acyclic). `phase` may be
omitted and defaults to `task_graph`. `phase: configuration` remains parseable
only so legacy revision files stay readable; new configuration-phase proposals
and revisions are rejected. Rejected revisions are replaced by a new complete
immutable revision.

The frontmatter owns:

- title and workspace topic ID;
- sequential or parallel execution mode — parallel mirrors the Issue Manager's
  honest-parallelism gate at propose/revise ingress: every task must carry its
  own unique absolute execution directory, or the document is rejected while
  the agent can still fix it (never after acceptance, where the failed
  `create_issue` operation would strand an accepted workflow);
- Issue-level reasoning and orchestration intensity; Tutti Host Context
  compiles the explicit speed preference into a 1-4 upper parallel target while
  the durable scheduler still enforces dependency, isolation, budget, and
  workspace-capacity limits;
- explicit effect and speed values copied from the producing Turn's immutable
  activation snapshot; both fields are required for Agent CLI proposals and
  revisions, and either a missing snapshot or an unequal value rejects the
  mutation before revision-file persistence;
- auto or fixed token budget and quota waterline (the token limit is dormant
  and no longer surfaced in UI);
- task IDs, content, priority, assignment (agent target, model plan, model,
  permission mode, reasoning effort), execution directory, and dependencies.

Files live under:

```text
<state-dir>/tutti-mode-plans/<workflow-id>/revisions/<sha256>.md
```

The globally unique workflow ID is the opaque file scope; workspace IDs never
appear in state-directory segments. Publishing uses an atomic link. If the
same content-addressed target already contains the same digest, a retry is an
idempotent success; a mismatch fails closed. Reads verify the stored SHA-256
before parsing. Multiple intentional revisions may reference the same
content-addressed file; revision ID and per-workflow sequence remain unique,
while document path is not revision identity. The OpenAPI response includes
parsed document data for clients; renderers do not read the state directory
directly.

## State And Decision Flow

```text
Agent: tutti plan propose --file <plan.md> --request-id <stable-id>
  (plan.md = complete narrative + full task graph in one document)
  -> daemon validates effect/speed against the exact producing Turn snapshot
  -> daemon commits workflow + revision + the single pending task review
  -> daemon publishes workspace.workflow.updated
  -> AgentGUI pulls the authoritative session-scoped pending snapshot
  -> Agent's turn ends with the propose response (nextAction "stop")
  -> user accepts (optionally with per-task assignment overrides),
     rejects with feedback, or cancels through HTTP; turning Tutti mode
     off with a review still pending cancels the checkpoint the same way
  -> the decision reaches the Agent as a new user message when follow-up
     work is needed; there is no agent-side wait

review rejected ("request changes")
  -> the rejection commits durably with its create_revision operation
  -> the daemon dispatches a feedback turn to the source Agent session
     containing the feedback and revise instructions, idempotent through a
     checkpoint-scoped clientSubmitId and linked back as a feedback turn
     (best-effort; the committed rejection never depends on dispatch)
  -> Agent appends a complete replacement plan with tutti plan revise
  -> daemon validates the replacement against that revision Turn's snapshot
  -> revision append atomically completes that exact pending operation
  -> the panel refreshes onto the new pending review

review accepted
  -> the decision durably records any per-task assignment overrides
  -> daemon derives ActionableItems (document values merged with overrides)
  -> deterministic create_issue operation atomically materializes one Issue,
     its tasks, one Tutti execution, and one active initial_schedule checkpoint
  -> materialization creates no Run and invokes no task launcher
  -> operation succeeds with issueId and CLI reports issue_created
```

Legacy two-phase workflows are retired at daemon startup: a one-shot scan
cancels every non-terminal workflow whose current pending checkpoint is a
configuration review (actor `tutti`). Historical accepted configuration
checkpoints may still advance to a task-graph revision, but new
configuration-phase revisions are rejected.

The user-facing HTTP decision endpoint is the sole approval boundary. Agent
CLI commands can observe a decision but cannot approve their own proposal.
Rejection requires feedback. Repeating the same decision is idempotent;
attempting a different decision or deciding a stale checkpoint fails closed.
The decision compare-and-set includes the current workflow revision and status,
so a concurrent revision cannot be overwritten by a late decision. Revision
append likewise compares source session, current revision, workflow status,
checkpoint identity, and checkpoint status in its final SQLite transaction.
This prevents either side of a revise/decide race from reviving stale state.

Proposal and revision writes have a separate durable mutation ledger. Its
unique key is `(workspace, source session, mutation kind, workflow scope,
request ID)`: proposal scope is empty, and revision scope is the workflow ID.
The caller must reuse the request ID when retrying the same mutation after a
timeout or lost response. The same key and Markdown SHA-256 returns the
original workflow/revision/checkpoint result without another mutation; the same
key with different bytes fails as a conflict. A new request ID is an explicit
new mutation even when the Markdown bytes are identical, so content hashes are
never treated as user intent or idempotency identity. The CLI reports both
`requestId` and `replayed`.

Operations use deterministic identities derived from workflow, checkpoint,
and operation kind. The Issue ID is also deterministic for the workflow. Its
reserved namespace and identity constructor live in the daemon-owned
`workspaceworkflow` business model; the reusable workspace Issue package only
validates generic Issue semantics and does not know Tutti workflow identity.
This allows retries to converge on the existing operation or Issue
instead of duplicating a side effect. A failed `create_issue` operation is
requeued through a compare-and-set transition to the same pending operation
when `decide` is replayed. The retry clears stale error
and completion fields; the idempotent Issue materializer then converges on the
same Issue ID.

For a new decision, the checkpoint, resulting workflow status, and deterministic
operation are one SQLite transaction. If operation insertion fails, the entire
decision rolls back. Once that transaction commits, downstream materialization
failure does not turn an accepted checkpoint into an apparent approval error:
the response carries the committed checkpoint and durable failed operation.
Only failure to record the operation outcome is returned as an execution error.
If a decision response is lost, replaying the same decision finds the same
checkpoint and deterministic operation; a succeeded operation is not executed
again. During daemon composition, after the workflow and Issue services exist
but before the public daemon service graph is returned, a one-shot recovery
scan resumes accepted task graphs with pending or failed `create_issue`
operations against the same deterministic Issue identity. Successful rows
leave the recovery set, and a later `plan wait` or decision replay remains a
secondary idempotent repair path. Revision read/parse and other operation-local
failures are recorded on that operation and do not block recovery of later
workflows; startup fails only when the scan fails or a durable operation outcome
cannot be written. No background workflow worker is started.

The workflow service owns the transition policy. The single active checkpoint
kind is the task review; the configuration-review row below is legacy-only
(retired at startup, cancel remains valid):

| Checkpoint                    | Decision | Durable result                                                                    | Agent next action                                |
| ----------------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
| Task review                   | Accept   | workflow becomes accepted; overrides recorded; `create_issue` operation           | `issue_created` after successful materialization |
| Task review                   | Reject   | workflow remains in progress; feedback stored; feedback turn dispatched to source | revise the complete plan                         |
| Task review                   | Cancel   | workflow becomes canceled                                                         | stop                                             |
| Configuration review (legacy) | Cancel   | workflow becomes canceled                                                         | stop                                             |

Source Agent Session deletion is guarded at the Agent Host boundary against the
entire canonical deletion closure. Before Host closes a runtime or mutates
persistence, the daemon records one durable deletion admission for that exact
closure. Any execution whose source Session is in the closure and whose status
is not `completed` or `archived` rejects the whole request with
`tutti_execution_active` plus the complete protected Issue set. This applies
equally to single deletion, batch deletion, and workspace clear. Materialization
checks the same durable admission in its creation transaction, so a new
execution cannot race an admitted source deletion.

After admission, Host owns runtime closure and delegates canonical Session,
activation snapshot, and Turn deletion to the daemon store in one SQLite
transaction. Host reports terminal success or failure so the admission becomes
`finalized` or `superseded`; a replan must pass admission again. At daemon
startup, admissions left `admitted` by a previous process are superseded before
Host serves requests. This keeps the source deletion guard on the provider-
neutral lifecycle path instead of pre-closing runtimes in an adapter.

Stopping Tutti Mode is an archive saga, not source Session deletion. The archive
request atomically changes the execution to `archiving`, pauses Issue dispatch,
cancels pending checkpoints, wakes, reviewer work, and prepared launches, and
records a durable idempotent operation with actor and reason. The service then
cancels every running Issue Run through the exact-run coordinator and waits for
authoritative settlement. Only after no Run remains `running` may the execution
become `archived` with `archived_at`, `archived_by`, and `archive_reason`.
Cancellation failure leaves a durable failed operation and the execution fenced;
startup recovery retries each incomplete archive independently. There is no
force-archive path.

## HTTP, Events, And Recovery

The schema-first HTTP surface is:

- `GET /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/tutti-mode-activation`
  returns the independent activation projection, including null before the
  first activation;
- `PUT /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/tutti-mode-activation`
  appends an idempotent, revision-checked active or inactive revision;
- `GET /v1/workspaces/{workspaceID}/workflows?sourceSessionId=...` lists every
  workflow for one Agent Session; adding `checkpointStatus=pending` narrows the
  result to workflows with a pending checkpoint. The hand-written client
  exposes these as `listWorkspaceWorkflows` and
  `listPendingWorkspaceWorkflows` respectively;
- `GET /v1/workspaces/{workspaceID}/workflows/{workflowID}` returns one full
  authoritative snapshot;
- `POST /v1/workspaces/{workspaceID}/workflows/{workflowID}/checkpoints/{checkpointID}/decision`
  records a user decision.
- `POST /v1/workspaces/{workspaceID}/tutti-executions/{issueID}/cancel-execution`
  pauses dispatch and cancels active Runs for a proven Tutti-owned Issue
  without archiving the execution;
- `POST /v1/workspaces/{workspaceID}/tutti-executions/{issueID}/archive`
  starts or replays the durable archive saga;
- `GET /v1/workspaces/{workspaceID}/tutti-executions/{issueID}/archive?operationId=...`
  returns its authoritative operation state.

`workspace.tuttimode.updated` and `workspace.workflow.updated` are advisory
invalidation events. The former identifies the changed Session and activation
revision; the latter carries workflow, source Session, checkpoint, and change
kind. Clients re-pull their authoritative HTTP or Session projection. Event
loss is safe because committed SQLite and revision-file state remains
authoritative. Every event-stream `connected` transition, including automatic
reconnect, invalidates every currently subscribed workspace scope. AgentGUI
then lists pending workflows for the active workspace and source Session again;
the new request sequence invalidates any list result that began before the
connection transition. Activation independently comes from the Session
projection. The desktop adapter never opens a panel from transcript text or a
model-authored marker. Renderer state carries the same workspace and
source-session scope key. A scope change immediately hides the previous
snapshot and invalidates in-flight list or decision results before they can
mutate the newly selected Session.

Every daemon service response containing an Agent Session passes through one
canonical response projection seam. That seam joins persisted Protocol v2 Turn
state and the independent `TuttiModeActivation` read projection for create,
resume/get, settings, title, visibility, pin, and list paths. A mutation must
not return a hand-built partial Session, because an authoritative client upsert
would otherwise interpret an omitted activation as removal and clear the badge.

The GUI panel displays only the current revision and its single pending task
review. Before acceptance it exposes every Issue materialization input in that
revision: execution mode, reasoning and orchestration intensity, quota
waterline (the token limit is dormant and hidden), plus each task's ID,
content, priority, execution directory, and dependency IDs. Each task's
assignment (Agent target, model plan, model, permission mode, reasoning
effort) is editable in place through host-supplied option catalogs; the edits
travel with the accept decision as per-task overrides and are durably recorded
on the checkpoint. Accept, reject, and cancel post the decision to the daemon;
rejection feedback is mandatory. Closing the app does not discard the review:
the next mount reconstructs it from the daemon snapshot.

Desktop assignment catalogs load provider composer options through the same
activity-core target-scoped cache used by the main Composer. The workflow
adapter may join that canonical snapshot with the workspace Agent directory and
compatible model-plan catalog, but it does not create a second provider-options
transport path. Model and reasoning entries retain their canonical
`value`/`label` metadata end to end: task overrides persist the opaque provider
`value`, while editable and read-only review surfaces render the `label` and
fall back to the value only for an unknown historical selection.

The Tutti activation additionally carries a session-scoped orchestration
intensity (0-100, default 50). The composer's Tutti Budget popup persists it
as a new activation revision; each turn's frozen snapshot copies it, and the
Tutti Host Context exposes it so the planning Agent chooses decomposition
granularity from it.

## Issue Projection

Accepting a current task graph synchronously asks the daemon-owned Issue
materializer to create an Issue from the derived `ActionableItem`s. One SQLite
transaction creates the Issue, tasks, Tutti execution aggregate at
`awaiting_schedule`/graph revision 1, and its active `initial_schedule`
checkpoint. It maps the Markdown execution profile, budget, assignments,
model choices, directories, and dependency graph into the Issue Manager
contract and records `planningSource = tutti_mode_plan`.

Materialization is inert: it creates no Run and calls no task launcher. The
source Agent must later schedule an explicit task set through the checkpoint-
and-revision-fenced Tutti execution command surface. Existing `autoAccept`
values remain readable migration metadata but have no dispatch authority for
Tutti-owned executions. Manual and `traditional_plan` Issues keep the generic
Issue Manager dispatch behavior.

`plan issue schedule` derives source authority from the trusted invoke context.
While holding the Issue mutation lock, the daemon validates the entire
requested set, including isolation. One SQLite transaction revalidates the
durable caller, active checkpoint, graph revision, task/dependency state,
budget, and workspace capacity. Fixed-budget admission reserves one estimated
allowance for every same-Issue active Run before evaluating the requested set.
The transaction then creates every Run, task-running projection, and durable
launch intent while resolving that checkpoint. Any rejection leaves the
execution and Issue graph unchanged.

Agent launch happens after commit. The launch-intent row is the source of truth
for `clientSubmitId`; delivery workers claim it with a durable lease and pass
that stored value unchanged into Agent Host. The active worker renews the lease
throughout worktree creation and Agent delivery. Ordinary recovery never steals
a leased intent, and startup recovery requeues only an expired lease, so a
second daemon replica starting while the first launch is live cannot enter the
launcher. Response-loss recovery retries the same deterministic
`issue-run:<runID>` identity, allowing Host to converge on the existing
canonical Turn rather than creating a second one. Tutti settlement,
reconciliation, and cancellation resolve this persisted identity from the
launch intent; only generic Issue Runs derive the deterministic default.
The existing Issue Run reconciliation queue also requeues expired launch
ownership and recovers prepared intents on every pass. A daemon that restarts
before the previous owner's last lease expires therefore retries immediately
after that expiry instead of leaving the Run stranded until its hard timeout.

A definite launch failure is terminal only when the adapter can prove that no
canonical Turn exists. An empty create result alone is insufficient: the
adapter also checks Host by the exact persisted `clientSubmitId`. A found Turn,
a lookup error, `ErrSubmitDeliveryUnknown`, or a create error carrying a Turn ID
remains recoverable. Only a clean Host not-found permits terminalization. That
write is one owner-fenced SQLite transaction: the currently leased launch
intent, Run, Task, Issue projection, and deterministic `task_failed` checkpoint
either commit together or all roll back. An expired owner therefore cannot
settle a Run after another daemon has reclaimed its lease.

Every terminal Issue Run (`completed`, `failed`, or `canceled`) creates one
ordered deterministic checkpoint. Completion remains
`pending_acceptance`/`agent_claimed` until the source Agent reviews that
checkpoint. The Agent may resolve the checkpoint by scheduling an exact next
task set, or acknowledge it when another Run is active or a later settlement is
already queued. Acknowledge accepts a successful task, promotes the next
pending checkpoint, and never invokes the generic dispatch frontier. Failed
and canceled checkpoints preserve their terminal task projection. Settlement
repair runs at startup and on the periodic Issue reconciliation cadence, so a
crash after Run persistence cannot lose the review gate.

When every task is terminal and every terminal Run has its settlement
checkpoint, the execution appends one ordered `all_tasks_terminal` checkpoint
with `requiresGoalReview`. Promoting it moves the execution to
`pending_goal_review`; the generic acknowledge command deliberately cannot
resolve this boundary. If a graph mutation adds or reworks tasks while that
terminal checkpoint is still pending, the mutation supersedes the stale
terminal boundary. After the replacement work settles, the same deterministic
terminal checkpoint is rearmed at the current graph revision and moved behind
the new settlement checkpoint. This preserves one terminal identity while
ensuring the final settlement can always promote a current Goal Review. The
settlement recovery scan applies the same readiness check to persisted
executions whose replacement Run had already settled before this invariant was
enforced, so daemon recovery repairs the stranded terminal backlog without
weakening acknowledge fences.

After acceptance the source conversation embeds a live "issue panel view"
(board/list) of the materialized Issue, fed by the same workspace issue events
the Issue Manager consumes. The embed surfaces the durable task structure and
execution state; Tutti-owned scheduling, mutation, and completion authority
comes from the source conversation rather than generic Issue mutation or
automatic dispatch.

The embedded panel's task-level accept and rework controls are source-Agent
prompt actions. They append a localized instruction with the exact Task mention
to the source conversation draft, preserve existing draft content, and require
an explicit user send. The renderer does not translate them into generic Task
status writes. After submission, the source Agent reads canonical execution
state and uses the existing checkpoint/revision-fenced command path. Direct
daemon-owned commands such as execution cancellation remain commands rather
than prompts.

The workflow remains the review and provenance record; the Issue remains the
task/run evidence graph; and the Tutti execution is the orchestration
authority. No renderer or Agent turn recreates the graph, and no Agent is
instructed to issue a second create call. If materialization fails, the
`create_issue` operation records a durable failure code and message, and the
authoritative workflow snapshot remains inspectable through `tutti plan get`
and the HTTP detail endpoint. Startup recovery, replaying the accepted decision,
or observing it through `tutti plan wait` retries the same durable operation;
it never asks the Agent to create the Issue separately.

The Agent-facing `issue create-from-plan` command accepts only
`traditional_plan` provenance. It rejects `tutti_mode_plan`; that provenance
can be written only by the daemon workflow materializer after the matching
checkpoint is durably accepted.

## Validation Boundaries

- Change the OpenAPI source before generated HTTP clients.
- Change the event protocol definition before generated event types.
- Keep workflow transitions and Issue materialization decisions in `tuttid`.
- Keep AgentGUI as a snapshot projector and decision client.
- Do not infer workflow state from provider Plan cards, transcript ordering,
  Markdown markers in messages, or the `/tutti` badge.
- Do not infer activation state from historical `capabilityRefs`; they are
  submission provenance only.
- Do not persist `ActionableItem` separately from the accepted revision.
- Do not expose Agent-callable accept or reject CLI commands.