tutti/docs/architecture/agent-gui-node.md

# Agent GUI Node Architecture

Status: current implemented architecture

This document defines the durable architecture of the Agent GUI system: ownership, dependency direction, core entities, critical flows, and change-routing rules. It is not an implementation plan, feature inventory, or troubleshooting log.

Scope:

- `packages/agent/host`: provider-neutral Agent application core
- `packages/agent/store-sqlite` and `store-sqlite/canonical`: canonical contracts and transactional local storage
- `packages/agent/daemon`: provider runtimes, adapters, and registry
- `services/tuttid`: HTTP, queries, product policy, and Host adapters
- `packages/agent/activity-core`: frontend workspace engine
- `packages/agent/gui`: Agent GUI, Message Center, and conversation presentation
- `apps/desktop`: Electron, Workbench, transport, and concrete host capabilities
- `apps/mobile`: React Native presentation, DeviceLink transport adapter, and
  mobile lifecycle integration

Implementation progress belongs in Git history or an active spec. Debugging procedures belong in [Agent Runtime Troubleshooting](../conventions/troubleshooting/agent-runtime.md).

## 1. Architectural taste

### 1.1 One fact, one owner

- durable lifecycle: `packages/agent/host`
- canonical vocabulary: `packages/agent/store-sqlite/canonical`
- canonical frontend state: workspace `AgentSessionEngine`
- DOM, focus, scroll, menus, and temporary disclosure: UI only

Do not solve cross-layer coordination by copying state. Consumers read projections/selectors and write semantic commands.

Device-global quick prompts are not Session or Turn state. AgentGUI consumes
the optional `AgentHostApi.quickPrompts` capability, preserves the host's
canonical list order, and delegates create/update/delete/move effects to the
host adapter. Reordering is presentation plus intent only: AgentGUI emits a
moved prompt, nullable `beforePromptId` anchor, and moved version; Desktop may
show an optimistic projection, while `tuttid` remains the durable order owner.
Hosts that omit the capability must hide the entire entry rather than expose a
partial or disabled library.

Desktop AgentGUI reports quick-prompt engagement through the typed panel
engagement sink. Opening the picker from the Composer emits
`agent.quick_prompt_engagement` with `action=panel_opened` and
`source=composer_input`; successfully inserting a saved prompt or a saved
recommended template into the Composer emits the same event with
`action=prompt_used` and the corresponding `prompt_type`. Engagement is
buffered until the containing panel satisfies its exposure gate. The
action-discriminated contract forbids `prompt_type` on panel-open events.
Events carry only stable AgentGUI context and never prompt titles or prompt
bodies, while the action keeps picker exposure distinct from successful use.

The native Mobile composer consumes the same device-global list through its
authenticated Desktop connection rather than creating Mobile-owned prompt
state. Its authenticated-device service reads the canonical quick-prompt list
through the generated tuttid client. The Mobile `+` menu
offers a searchable, read-only selector; choosing a prompt adds its text at the
current plain-text input position without replacing the existing draft,
restores input focus, and never sends automatically. Create, edit, delete, and
reorder remain Desktop management actions. DeviceLink permits only exact
`GET /v1/agent-quick-prompts` reads for this flow; mutation and per-prompt
routes remain blocked.

The native Mobile new-conversation Composer presents Agent Target and working
directory as peer context selectors directly above the input. The Agent Target
catalog remains the launch authority. The working-directory selector reads the
daemon-owned registered project catalog through the exact read-only
`GET /v1/user-projects` DeviceLink route and also offers an explicit no-project
choice; Mobile does not browse the Desktop filesystem, accept arbitrary paths,
or mutate the registered project catalog. The authenticated-device scope keeps
the last loaded project metadata across workspace activity replacement, while
the selected path remains process-only draft state and disappears after
activation. Changing either selector reloads Composer options for the exact
Target and optional cwd; creation waits while those exact options are loading
and submits only sparse user-selected settings rather than cached effective
defaults. An outcome-unknown activation locks both context selectors so an
idempotent retry cannot change its launch identity. Activation with a
registered project carries both its path as `cwd` and its versioned canonical
project `railPlacement`; no-project activation omits `cwd` so the daemon
allocates an isolated Session directory and carries the canonical
`conversations` placement. Existing Sessions never expose these selectors as
mutable settings.

Use the closed-surface test when assigning ownership: if state must survive or continue progressing after every Agent GUI surface closes, it belongs to Host/store or the workspace engine. State that should disappear with the surface belongs to UI.

### 1.2 Semantics before screens

Session, Turn, Interaction, Goal, and operation are domain facts. Rail, timeline, dock, toast, and Message Center are projections of those facts; they do not define lifecycle.

Transcript is historical presentation. It is not authoritative for approvals, questions, Turn state, or submit availability.

### 1.3 Ports and adapters

Core layers declare narrow contracts and ports. HTTP, Electron, filesystem, provider wire, authorization, VM, and process details stay in adapters.

A reusable boundary needs a real responsibility and consumer. Do not create vague `common`, `utils`, or `shared core` modules merely to look reusable.

### 1.4 Provider-neutral does not mean provider-blind

A provider adapter may understand its own wire protocol. Shared business code reads descriptors, strategies, capabilities, and canonical payloads.

AgentGUI, Message Center, composer, and shared services must not choose behavior by names such as Codex, Claude Code, Cursor, or OpenCode.

### 1.5 Events are hints; canonical reads reconcile

Realtime events reduce latency but are not automatically complete truth:

- normalized provider text/reasoning streams and explicitly appendable textual
  tool output arrive as optimistic `message_delta` payloads on the
  `/v1/events/ws` business-event WebSocket
- canonical tool `output`/`error` bodies bound each `text`, `stdout`, and
  `stderr` field to 1 MiB, then fit formal output streams into a 768 KiB
  aggregate durable payload budget, including nested tool steps, by retaining
  a valid UTF-8 prefix and the fixed `[Output truncated]` marker
- terminal command snapshots may omit `text` only when it exactly equals the
  trimmed `stdout` or `stderr`; Reporter resolves the alias before independent
  field truncation and clears an earlier running `text`, while the raw stream
  remains canonical and explicit non-command tools retain provider-neutral
  `text`
- continuous, version-complete `message_update` events may merge inline
- terminal `message_update` is the durable confirmation; message version gaps,
  invalid/unanchored deltas, nonterminal deltas after known terminal message
  truth, reconnects, Turn, Interaction, and state changes trigger authoritative
  reconciliation
- a focused conversation holds a synchronization lease. A terminal initial
  reconcile failure is observable through that lease and receives one bounded
  retry; releasing the lease prevents further focus-owned recovery work
- event publication or observer failure cannot roll back a committed canonical transaction
- message projections preserve the original textual content, including leading
  and trailing whitespace; trimmed or whitespace-collapsed copies may decide
  emptiness, synthetic-control suppression, or duplicate identity, but must not
  replace the body passed to renderers. Markdown renderers continue to own
  soft-break presentation.

### 1.6 Identity and correlation are explicit

Cross-boundary work uses stable identifiers:

- workspace: `workspaceId`
- session: `agentSessionId`
- Turn: `turnId`
- Interaction: `requestId`
- submit: `clientSubmitId`
- UI Agent: `agentTargetId`

Never infer identity from titles, timestamps, array positions, provider names, the latest transcript row, or runtime instance IDs.

### 1.7 Fail closed

When authoritative identity, Turn, or Interaction is missing, return unsupported/loading/error. Capability presence is explicit: a null session capability snapshot means no authoritative session snapshot is available (not yet reported or legacy-ambiguous), while a non-null snapshot is complete and may explicitly contain no supported capabilities. Presentation may fall back from a null session snapshot to the authoritative provider composer descriptor, but an explicit session `false` always wins. Do not choose the first provider, manufacture a Turn, treat an ambiguous legacy empty array as loaded, or hide contract drift behind an ad hoc UI fallback.

Compatibility paths require evidence of existing data or a release window. Keep them isolated from canonical writes.

### 1.8 Contract first

Change OpenAPI before HTTP contracts, then generate Go and TypeScript types. Internal domain types cross layers through explicit projections; do not maintain handwritten transport mirrors.

Identity, time, and state use canonical representations. Unknown enum values produce an explicit unsupported/error path; widening them to arbitrary strings is not compatibility.

## 2. System shape

### 2.1 Command path

```text
AgentGUI / Message Center / host surface
  -> semantic AgentSessionEngine operation or typed intent
  -> workspace AgentSessionEngine
  -> shared typed lifecycle effect projection
  -> Desktop or Mobile AgentSessionEffectPort
     (host-only commands use the narrow EngineExtensionCommand adapter)
  -> tuttid HTTP and product adapter
  -> packages/agent/host
  -> canonical store transaction + provider runtime port
```

### 2.2 Observation path

```text
provider runtime observation
  -> packages/agent/host + store-sqlite canonical transaction
  -> CommittedDelta / CommitObserver
  -> tuttid ActivityProjection and event publication
  -> Desktop business-event bridge or Mobile DeviceLink live lane
  -> workspace AgentSessionEngine reducer
  -> memoized AgentActivitySnapshot
  -> selectors / pure projections
  -> AgentGUI / Message Center / host chrome
```

### 2.3 Session capability snapshots

Provider adapters report canonical session capabilities through a typed,
complete snapshot. They do not place capability ids in provider-private
`RuntimeContext`. A missing snapshot means no authoritative session snapshot
is available because it has not been reported yet or legacy data is ambiguous;
an empty reported snapshot means no canonical session capabilities are
supported. Partial state reports omit the snapshot and preserve the last
reported value.

Persistence uses a private JSON compatibility carrier for capability ids plus
explicit report presence, then exposes only the typed optional snapshot at the
store boundary. Legacy non-empty lists are reported snapshots; legacy empty
lists without presence evidence remain unknown. The daemon API projects
unknown as `null` and reported snapshots as a closed boolean record.
This does not require a database schema migration: the presence marker lives
inside the existing metadata JSON column, and decoding normalizes old rows.

`activity-core` owns the presentation resolution rule: a reported session
value overrides composer options, while a null session snapshot falls back to
the authoritative provider composer descriptor. AgentGUI consumes that result
and does not add provider-specific or control-specific fallback logic. Host and
runtime operation handlers remain authoritative when an action is submitted.

Runtime context transport also distinguishes a complete snapshot from an
explicit top-level `set`/`unset` patch. Omission preserves existing context;
patches may update only provider-private keys and must never replace unrelated
session metadata.

### New-session launch settings

Remembered composer defaults are target-scoped preferences, not active Session
state. AgentGUI reads them only while composing a new Session and sends the
resolved sparse settings through the normal activation command. A host-owned
entry capability may additionally hide or disable an experimental control; the
activation boundary must fail closed as well, so a remembered `true` value
cannot outlive a disabled host entry. Provider support comes from the resolved
composer descriptor rather than provider-name checks in shared UI code.
Provider and extension model catalogs can change independently of target-scoped
remembered defaults. On Create, the daemon treats such a default as a fallback
preference and resolves an obsolete value to the current catalog default from
the same target. Because AgentGUI also sends its presented effective value, the
activation request carries explicit provenance bits for model and reasoning;
Engine and the tuttid adapter must preserve them through the HTTP boundary.
Legacy direct Create callers that omit provenance retain the compatibility rule
that a supplied non-empty value is explicit. Non-explicit model-dependent settings, such as reasoning
effort, resolve against that effective model rather than remaining bound to the
obsolete preference. A strict per-model catalog never forwards an inherited
value that the target model did not advertise. A model or dependent setting
explicitly supplied by the caller remains strict. If the runtime rejects an
explicit model selection, startup fails rather than continuing with an
undisclosed provider default.

Create resolves and freezes the effective launch cwd before the first
cwd-sensitive model-catalog lookup. A no-project session therefore queries the
catalog from its allocated session directory, which is also passed to runtime;
it must not inherit the tuttid process cwd. Worktree creation intentionally
queries from the selected source checkout before creating the isolated checkout.
The no-project directory remains a provisional allocation until Host creates
the Session (or delivery becomes uncertain); any earlier catalog, plan,
reasoning, preparation, or runtime failure releases it so failed requests cannot
consume the allocator's daily name space.

Composer model catalogs are daemon-owned snapshots. A provider auth/config
change invalidates the snapshot and closes its provider app-server session, but
the daemon may return the last known list as stale while refreshing it in the
background. AgentGUI may render that stale projection with its loading state;
model validation must wait for an authoritative snapshot. The daemon shares
concurrent catalog loads, reuses a warm app-server session, and publishes the
existing catalog invalidation hint after a successful refresh so open composers
can converge without owning provider or cache policy.

Connector capability catalogs follow the same projection boundary. Each host
reads its authoritative local Connector Market snapshot, then uses
`packages/agent/daemon/composercatalog` to map manifest identity, icon,
installation, compatibility, and authorization state into the closed Composer
capability contract. Host transports only serialize that projection and route
semantic open intents; they must not duplicate Connector readiness rules or
derive Composer entries from renderer-local market state. The snapshot uses the
host's current account scope so Composer status and prompt admission include the
same authorization overlay as Connector Market management. Connector Market
change events invalidate retained Composer options, while a menu open may still
force an authoritative reread as a recovery path.

Hosts may project a Connector catalog as inspectable but read-only. In that
mode AgentGUI keeps the menu and host-provided readiness descriptions visible,
but suppresses selection, setup or authorization opens, selected chips, and
the optional management footer. Read-only presentation never becomes execution
authority; the Host remains responsible for Connector admission at submit or
runtime preparation.

Settings that affect provider preparation are immutable after launch. The
daemon validates them against current product policy and resolved provider
capability before runtime preparation; an active Session cannot reinterpret
them through an in-place settings update.

RTK saver mode follows this launch-only path for every resolved Agent provider.
The remembered composer value is only an opt-in; provider-neutral runtime
preparation resolves the pinned Tutti-bundled or managed-runtime `rtk`
executable, copies it and the canonical `RTK.md` into the exact Session runtime,
places an absolute reference to that file first in session-private `AGENTS.md`
providers, retains the inline RTK rule as a compatibility fallback through the
provider's existing instruction channel, installs provider-native rewrite hooks
or plugins where available, and prepends only the private binary directory to
the Session environment. Tutti never runs an RTK package manager or global
installer. RTK usage data, tee output, and telemetry policy are also
Session-scoped, so enabling the mode cannot change another Agent's instructions,
executable search path, or tracking state. The independent
`rtkSaverMode` property carries this provider-neutral setting, while the
existing `codexSaverMode` property remains Codex-only and continues to control
the Luna subagent workflow. Tutti terminals receive the bundled
RTK directory in their child PATH for explicit use, while the user-global PATH
and external Agent processes remain unchanged.

### 2.4 Ownership map

| Layer                           | Owns                                                                                          | Must not own                                      |
| ------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `store-sqlite/canonical`        | canonical phase, outcome, origin, Interaction, capability vocabulary, and pure projections    | HTTP, provider processes, React                   |
| `store-sqlite`                  | canonical transactions, SQLite repositories, durable tombstones/outbox participation          | product UI, transport policy                      |
| `packages/agent/host`           | create/resume/send/cancel/fork, lineage, Interaction, Goal, operation, and recovery lifecycle | HTTP DTOs, Electron, concrete provider wire       |
| `packages/agent/daemon`         | provider registry, runtime mechanics, wire normalization                                      | AgentGUI policy, cross-provider UI branches       |
| `services/tuttid/service/agent` | Host adapters, HTTP/query/composer/product policy, provider preparation                       | reimplementation of Host lifecycle                |
| tuttid `ActivityProjection`     | canonical read projection, commit observation, event publication/repair                       | lifecycle decisions, React state                  |
| `agent-activity-core`           | workspace engine, canonical frontend entities, pending intents, queue, selectors              | HTTP, Electron, React                             |
| `agent-gui`                     | runtime contract, projections, controllers, views, UI-local state                             | daemon truth, a second session store              |
| `apps/desktop`                  | tuttid client, business-event WebSocket, preload, Workbench, windows, file/OS capabilities    | a second Agent business core                      |
| `apps/mobile`                   | DeviceLink adapter, Native renderer, app lifecycle, navigation and drafts                     | a second Agent business core or Session DTO cache |

`services/tuttid/api/openapi/tuttid.v1.yaml` is authoritative for HTTP request/response contracts. It projects the canonical domain; it does not replace `store-sqlite/canonical`.

### 2.5 Ephemeral observation gaps

A Host may expose an ephemeral observation gap for one exact Session and Turn
when its caller-side projection may be stale. The gap is presentation-only:
AgentGUI pauses the processing animation, keeps recovery chrome visible, and
blocks commands that require current state until the Host removes the gap. A
Host may additionally classify the gap as peer-offline or synchronizing; while
that classification is present, AgentGUI replaces the numeric live duration
with the matching status copy. An older Host that omits the classification
retains the frozen-duration fallback.

An observation gap does not settle, interrupt, or otherwise rewrite the
canonical Turn. The Host owns reconnect and catch-up fencing and must remove
the gap only after the same Turn is authoritative again. When the capability
is absent, AgentGUI preserves its existing lifecycle presentation.

### 2.5.1 Live Side transient lane

Side is a provider-neutral, surface-owned live conversation fork. It is
intentionally separate from the durable command and observation paths:

```text
AgentGUI Side pane
  -> AgentSideConversationRuntime port
  -> Desktop generated tuttid client adapter
  -> tuttid Side HTTP handlers
  -> packages/agent/host Side lifecycle
  -> packages/agent/daemon provider Side adapter

provider Side runtime observation
  -> SideStreamObserver
  -> tuttid agent.side.updated publisher
  -> Desktop business-event adapter
  -> AgentGUI Side event normalizer
  -> activity-core ephemeral conversation projector
  -> shared AgentConversationVM projection
  -> Side timeline + composer instances
```

The runtime `SideStreamObserver` seam includes both event observation and
explicit ephemeral-identity cleanup. Host calls the cleanup operation when a
Side closes, is removed, or expires, so bridge-local ordering state cannot
outlive the Side identity.

The provider adapter owns provider-specific context snapshot mechanics. Host
owns Side identity, idempotent open, exact-Turn commands, scope isolation, and
cleanup. tuttid projects those commands through generated OpenAPI contracts and
publishes only the transient `agent.side.updated` envelope. Desktop is a thin
transport adapter. AgentGUI owns capability gating, the transient event
projection, and presentation; it contains no provider-name branches.

Side has no persistent button in the main composer. Desktop exposes Side and
the transcript text-selection action toolbar only after the user enables the
default-off `lab.agentSideConversation` developer preference. The host passes
that preference as an explicit AgentGUI capability and omits the Side runtime
while it is disabled; AgentGUI therefore does not resolve provider support,
show the toolbar or slash entry, or intercept typed `/side` input. After the
host opt-in, AgentGUI injects the provider-neutral `/side` entry into the slash
command palette with a local `submitImmediate` selection effect only when the
exact source Session reports every required Side capability. Selecting the
entry immediately submits the local `/side` intent, ensures the source runtime
is available, and opens Side; typed `/side <prompt>` opens it and sends the
prompt in one action.
After capability discovery has enabled `/side`, submission creates the local
`opening` projection immediately and renders the Side shell plus its empty
temporary-conversation explanation before the provider fork finishes. It does
not perform another renderer capability request on the open path; Host and
Runtime remain the authoritative live-source validators.
Capability resolution is fail-closed: pending, unavailable, and unsupported
providers do not show `/side`, including when a provider advertises a command
with that name. A typed `/side` invocation remains a Side-only intent in those
states: AgentGUI reports the unavailable operation and never forwards its text
through the main conversation submit path.
A released canonical provider connection may be resumed from
the source Session before capability resolution; the runtime remains the final
authority for whether the operation can open.

Desktop supplies a Side runtime factory rather than a workspace singleton.
Each mounted embedded or detached AgentGUI surface creates and disposes its
own runtime instance, so transient identity and cleanup ownership cannot race
between windows.

The Side controller is not an `AgentSessionEngine` and must never dispatch Side
events into the durable workspace engine. AgentGUI normalizes the transient
envelope into the React-free `activity-core` ephemeral conversation projector,
which emits the same `AgentActivitySnapshot`/Turn vocabulary consumed by the
shared conversation projection. This reuse is projection-only: it does not
load, retain, reconcile, or persist a workspace Session.

The controller retains only the selected surface's active Side identity,
ephemeral projection, pending Interaction, sequence, and error. Embedded
AgentGUI keeps Side attached to its source identity when the selected source
changes and shows it again when that source is reselected. A host that injects
the optional external Side presentation bridge opts into fail-closed source
switching: changing the selected canonical Session closes the old Side. The
owning AgentGUI surface otherwise closes it only through the explicit Side
close action or when the surface-owned runtime is destroyed. Its external-store
subscription owns the transient event and connection subscriptions. Once the
last surface subscriber is gone, those subscriptions are released. Disconnect,
source-identity mismatch, or a sequence gap expires local state and prevents
further rendering; no canonical reconciliation fallback exists for this
ephemeral lane.

The shared Side surface creates a second instance of the conversation timeline
and composer. Embedded AgentGUI wraps it as a docked sibling of the main detail
surface, not an overlay or nested durable Session route. Standalone AgentGUI
publishes the exact surface projection through an optional presentation-only
external store; Desktop maps that projection to a contextual `side` tab in the
shared right tool sidebar and suppresses the inline wrapper. The bridge carries
only exact source/Side identity, surface props, and the close intent. It owns no
Side lifecycle or durable state. Each surface instance owns its own draft,
scroll-follow state, focus/shortcut scope, Turn gate, and interrupt action. The
Side composer inherits the provider/model/cwd boundary captured at open time
and presents those settings read-only. A normal main-composer submission always
stays on the main Session; only the explicit `/side` command opens or targets
the Side lane.

The transcript selection toolbar stages selected text as a removable quote in
the target composer. **Add to conversation** updates only the main draft.
**Ask in Side** opens an empty Side when needed and updates only its draft; it
never creates a Turn until the user explicitly submits that composer. Quote
blocks are UI-local draft state and materialize as Markdown blockquote text at
the existing submit boundary, so the Side transport remains text-only. When a
typed question accompanies those quotes, Side keeps the blockquotes in provider
content but projects only the typed question as the visible user message; a
legacy quote-only submission keeps the existing blockquote display fallback;
only a future explicit selected-text content kind can make that ambiguous shape
safe to render as a chip. Focus
ownership follows the currently visible Side pane: an unmounted or
source-mismatched Side cannot keep the main composer inactive, and pane cleanup
must release its focus scope.

Side capability is enabled only when the exact selected source runtime, after
any required canonical-session resume, reports all mandatory facts: native
support, active-source-Turn snapshot support, ephemeral lifetime, hidden
inherited history, and an injected model boundary. The Side may be opened after
the source has started and may continue after the source Turn settles; the
source Turn only determines whether the provider has live context to snapshot,
not the lifetime of an already-open Side. Attachments
are rejected at the AgentGUI controller and Desktop adapter until the
transport contract can preserve them without degradation. Approval and
question state remains Side-local and is answered through the exact
`(workspaceId, sideAgentSessionId, turnId, requestId)` command.

### 2.5.2 Interaction admission and execution presentation

An exact pending Interaction is a separate admission scope. When its Host
supplies interaction readiness, that exact result owns transport presentation
and early write admission for the pending card. An observation gap may still
govern the active Turn before or after that Interaction, but it cannot override
the exact ready or blocked readiness result while the card is presented.

When an exact Interaction is blocked, AgentGUI keeps the pending action visible
but disables its controls. The disabled action group remains focusable and
hoverable so the same readiness reason is discoverable in the conversation
chrome and Message Center; this is presentation only and does not change the
Host-owned admission decision.

Message Center and attention-card consumers preserve this separation in their
presentation contract: `isSubmitting` describes an in-flight response, while
an independently supplied interaction-disabled state blocks the nested prompt
controls without hiding the pending card or its conversation navigation. A
host-provided blocked reason is exposed through a focusable, hoverable
description so a blocked card remains understandable without making Tooltip
the command authority. If the Host omits the reason, the disabled wrapper stays
out of the tab order and does not create an empty Tooltip. The final semantic
command admission check remains in the consumer/controller path.

### Submission and execution presentation

Submission acknowledgment and execution are separate presentation signals:

- `isSubmitting`, an unconfirmed submit, and a viable initial launch that
  expects a Turn drive an `isAwaitingTurnStart` Composer spinner immediately
  because they prove local submission intent or expected launch work
- a reconnect-only `activating` state belongs to connection chrome and command
  admission; without submission intent it must not create a sending spinner,
  `working` status, Stop target, or queue eligibility
- Conversation `working` status and queue eligibility require canonical
  execution evidence: the fenced Engine display status or a non-settled active
  Turn; pending activation or submission alone must remain `ready`, both before
  and after canonical Session confirmation
- canonical completed, failed, or canceled activity stops the execution
  indicator even if a lower-level runtime signal has not caught up yet
- transport recovery chrome, such as connecting or unavailable, takes priority
  over normal working copy
- Stop is available before Turn identity only when the Engine exposes an exact
  pending-submit stop target; reconnect and other connection state never invent
  one

This keeps feedback optimistic for responsiveness while keeping claims about
Agent work grounded in the canonical Turn/runtime projection.

The Composer also hands the exact draft used to build a submission to the
AgentGUI controller. The controller snapshots that handoff for conditional
post-submit clearing; it must clear only when the current draft still matches
the submitted snapshot, so a queue admission or accepted send cannot erase a
newer edit made while the request is in flight. For image blocks, provider
locators and preview/upload-progress metadata may settle asynchronously and do
not count as user edits; upload errors and unknown fields remain part of the
comparison.

### 2.6 On-demand status

AgentGUI owns one provider-neutral `AgentStatusController` for `/status`, Agent
Info, and Agent Config. These surfaces are explicit bounded reads; mounting an
AgentGUI node must not start background status polling.

The host injects an `AgentStatusSource`. AgentGUI treats `scopeKey` as opaque
and never resolves provider, account, local-vs-remote transport, or owner
identity. The controller owns only loading/ready/error presentation,
30-second request cancellation, a one-hour retained UI snapshot, 5-second
manual-refresh debounce, and fencing callbacks from closed or replaced
requests. Opening any status surface uses the same controller snapshot so the
three views cannot drift into separate state machines.

Every production host, including Tutti Desktop, injects this controller. A
host adapter resolves the exact Agent Target to its provider, verifies an
optional Session belongs to the same workspace/target/provider, and performs
the bounded status read. AgentGUI has no legacy probe-backed status state or
provider-derived fallback. The active conversation id is the request Session
identity because it exists before detail hydration; raw Session chrome remains
presentation data.

Tutti Desktop creates one status source per workspace renderer and injects it
into every AgentGUI surface in that workspace. The source shares the one-hour
Agent Target snapshot, five-second refresh debounce, and in-flight status probe
by exact `agentTargetId`, while each surface keeps its own controller and therefore its own
query, loading, close, and stale-response state. Sharing the controller itself
is invalid because one surface could replace or close another surface's active
request. Standalone renderer processes have their own source; the Electron main
process remains the cross-window short-lived exact-target cache.

Account-usage probing for an Agent Extension is an optional, versioned,
target-scoped capability declared by the signed Extension. The provider-owned
Helper owns provider config, credentials, trusted origins, private endpoints,
and response parsing; `tuttid` runs only the exact companion script installed
and fingerprinted in that Target's independent companion runtime through a
separately verified Node interpreter. Companion availability never changes ACP
readiness. A daemon-owned reconciler installs the companion outside setup
actions, wakes after runtime or Extension activation, retries failures with
bounded backoff, and rechecks persisted activation on restart. Account-usage
requests are joined and cached for a short TTL by exact `agentTargetId`; the TTL
starts when execution completes, and Node identity derivation is reused while
the executable file identity is unchanged. The daemon accepts existing v1
helper output and returns the normalized provider-neutral
`tutti.agent.account-usage.v2` discriminated result. Desktop validates the
schema and echoed Target/provider identity, then projects billing identity,
quota completeness, and optional exact Provider-neutral amounts without
changing ACP readiness. A complete quota set is distinct from a known account
whose quota is unavailable and from API billing where quota is not applicable;
only the complete state may carry rows. Presentation maps API `not_applicable`
to a resolved empty limits row (`—`), while `unavailable` uses localized
account-quota-unavailable copy; neither becomes a refresh failure. Missing
profiles and older Extensions are `unsupported`; unknown schemas, enums,
shapes, partial exact amounts, or a claimed complete result without quotas fail
closed as `parse_failed`. No provider message, path, endpoint, response body,
credential, account ID, or raw account record crosses the port or enters logs.

A source emits at most one cached `snapshot` followed by at most one
`refreshed` value, then completes. Backend probing may continue independently
to fill a host-owned cache after the presentation request is canceled; late
frames from the canceled request must not mutate AgentGUI. Errors crossing the
port are structured codes, never provider stderr, account material, endpoints,
or transport diagnostics. The limits projection preserves stable codes such as
`auth_required`, `session_expired`, and `subscription_required` through
`AgentStatusValue.limitsErrorCode`; AgentGUI owns their localized presentation
and maps unknown codes to one generic failure label.

A provider quota may carry an optional exact provider-neutral amount and unit
when a percentage alone would hide useful account information. The host owns
the provider request, credential handling, package aggregation, and percentage
normalization; AgentGUI only renders the projected amount and uses the optional
percentage for progress presentation. Raw account and package records never
cross this boundary.

An explicit unsupported usage probe is a successful bounded read with no
quotas and `limitsState: unavailable`; it must not become a refresh failure.
Only real authentication, transport, parsing, timeout, or execution failures
project `limitsState: error`.

A Custom Agent bound to a Model Plan does not use the Agent Runtime provider's
native account for model access, so provider-native account usage is not
applicable to that exact target. Desktop projects
`providerAccountUsageApplicable: false` from the Workspace Agent binding;
AgentGUI preserves the optional capability through its target projection. The
Desktop status source then completes the bounded read with unavailable limits
without calling the provider usage probe, and AgentGUI disables manual usage
refresh for that target. An absent capability keeps the existing provider
account behavior for other hosts and ordinary Runtime targets.

Account-config refresh placement is also host-scoped presentation. Tutti
Desktop opts into `accountUsageRefreshInline` so the refresh control shares the
limits header row. The capability defaults to false; TSH/VN and other hosts that
omit it retain the established standalone menu row.

Closing `/status`, Agent Info, or Agent Config cancels only the request owned
by that surface. Replaced requests remain fenced. A stream that completes
without a frame is a failed refresh: a retained value may remain visible, but
the UI must show the refresh failure rather than treating the old value as a
new success.

Desktop availability analytics reads the renderer's loaded managed-provider
snapshot and must not turn a pageview or focus event into a daemon request. A
stale visibility snapshot may reconcile through a non-forced tuttid status
read; tuttid owns cache validity, credential-fingerprint checks, and
single-flight probing. Forced detection is reserved for explicit provider
refresh and the provider-scoped confirmation after an install, login, or
update action. A confirmed new-conversation creation failure is the only
analytics exception: Desktop force-refreshes only the exact target's provider,
then reports the fresh availability snapshot with a failure-specific trigger.

Cold workspace initialization may request all managed providers together so the
first useful snapshot arrives quickly. tuttid may detect different providers in
parallel, but it applies one process-wide limit to auth, version, and adapter
probe subprocesses because a single provider can otherwise fan out into several
CLI processes. Later visible-window stale reconciliation is best-effort
background work and checks providers serially; another focus cannot overlap the
same reconciliation run.

Provider detection separates volatile readiness from stable executable facts.
An ordinary read may reuse the full provider snapshot. A forced read bypasses
that snapshot and rechecks current authentication/readiness, including the
provider credential marker, but may reuse a successful CLI version or adapter
launch result while the resolved executable fingerprint is unchanged. Failed
version reads and failed adapter launches are never cached. OpenCode and
Tutti Agent use their validated local credential files as the primary auth
signal; malformed files may fall back to one CLI check. Cursor's single
`about --format json` result supplies both auth and version when available.

Authentication status is evidence-based and provider-neutral. A local status
command, marker, token, or API key proves only `configured`. A provider-backed
account probe or successful agent request proves `authenticated`. An explicit
remote authentication failure proves `required` and outranks stale local
credentials until credentials change or a later provider request succeeds.
Conversation failures may update this provider-global state only for a
provider-native runtime and only from the typed completed root-provider Turn:
`auth_required` records required, while a completed outcome records success.
Model Plan and Agent Extension failures are connection-scoped and never mutate
the provider-global login state. Shared layers do not infer authentication from
provider prose, HTTP 403, gateway timeouts, billing, quota, or model errors.
`packages/agent/daemon/providerstatus` owns evidence reduction; `tuttid` owns
the live outcome store, cache invalidation, and public status projection. Tutti
Desktop management surfaces and AgentGUI consume that same status. They may
keep a `configured` provider launchable when availability is `ready`, but must
not relabel it as connected or authenticated.

For subscription OAuth, provider descriptors select the remote-auth strategy.
Claude Code uses `GET https://api.anthropic.com/api/oauth/usage`; Codex uses the
provider runtime's `account/rateLimits/read`. These checks are attempted on
ordinary status detection and become stale after 15 minutes. Visible, focused
Desktop windows reconcile stale providers on focus/visibility activation and
on the 15-minute poll. API-key configuration skips subscription OAuth checks.
Explicit authentication rejection is authoritative; rate limits, server
errors, and network failures leave the weaker `configured` state intact.
Conversation error adapters preserve typed provider code, HTTP status,
retryability, origin, and sanitized upstream detail. AgentGUI shows sanitized
provider-origin detail directly; Tutti-owned transport and lifecycle failures
continue to use localized product copy. Secrets are redacted before logging,
persistence, or presentation.
These checks validate current access but do not rotate refresh tokens; refresh
ownership requires a separate serialized credential lifecycle that can gate on
live provider processes.

### 2.6 Developer cassette replay

The developer-only `agent.sessionRecording` desktop preference defaults off.
When enabled, Desktop injects its recording and replay controls through generic
AgentGUI render slots. AgentGUI contains no recording/replay API, controller,
state, provider branch, component, or copy.

The provider-neutral renderer contract is published separately as
`@tutti-os/agent-session-replay`. It owns the portable activity event type and
interaction contract shared by Desktop and TSH; product adapters still own
scope mapping, persistence, HTTP/Electron integration, replay runners, and
provider/runtime setup.

`packages/agent/session-replay` owns the provider-neutral Recording/Cassette
workflow, status transitions, portable contracts, and validation policy.
`services/tuttid/service/agentsessionreplay` is Tutti's HTTP/product adapter and
composition surface; Desktop is the Electron/renderer adapter and composition
surface. Desktop reads the authoritative recording list after mounting and
projects commands; React state is never the source of an active Recording.
`packages/agent/daemon/runtime` retains only concrete recording and scripted
replay transport mechanics.

The default-off preference is a startup composition gate, not only a UI gate.
The renderer awaits initial persisted preference hydration before it constructs
the Workspace service container, so composition never reads transient in-memory
defaults. The preferences module owns this readiness seam; Replay remains a
consumer of the hydrated feature flag and does not add a parallel event center.
The main-process Replay composition module owns manager/access/control creation
and all Replay IPC bindings; general runtime IPC supplies only Electron and
daemon adapters. When disabled, Desktop main does not create the Replay process
manager, access adapters, control writer, or Replay IPC handlers, and the
renderer keeps the replay activity bridge inert: it creates no recording
binding, recorder map, or Engine observer. When enabled, the
`agent-session-replay` feature-local activity bridge owns the recording binding,
recorder map, and Engine observer fan-out; `WorkspaceAgentActivityService`
remains the Activity Engine/reconcile facade and delegates that replay boundary
to the bridge. The renderer creates recorder state only for the lifetime of an
active Recording and mounts isolated Replay observers only inside the Replay
runtime. Changing the preference does not claim to recompose a running daemon
or renderer; the next process composition applies the new value.

A Recording captures a time window over the root SessionGraph. Root Turn
settlement, child creation, and Goal continuation do not complete it. Explicit
stop waits for a stable boundary, detaches every graph connection, and exports
expected graph state. Daemon restart recovery marks an interrupted capture
`incomplete` and exposes it through the same recording list.

The cassette runner drives these controls through a real Electron AgentGUI.
Replay mode keeps the current provider adapter but replaces only its Agent
SessionGraph `ProcessConnection` set; current adapter outbound bytes must match
the recorded Session/provider/launch-ordinal connection before inbound frames
are released.
The Desktop feature
`apps/desktop/src/renderer/src/features/agent-session-replay` owns the recording
toolbar, recording list, replay-window controls, feature gating, product copy,
and daemon client adapter. Recording names default to their UTC creation
timestamp. A completed row supports inline rename; the daemon writes the name
into `cassette.json`, recalculates the manifest hash, and commits matching
Recording and Cassette metadata. The list header can import one or more portable
Cassette directories through a native Desktop file selection. `tuttid`
validates every manifest, file inventory, hash, portable state, identity, and
size limit before copying the batch into daemon-owned storage and projecting
each valid Cassette as a completed Recording in the current Workspace. Invalid
or conflicting members report per-Cassette failures without rolling back other
successful imports; source directories are never mutated. The Desktop Replay
feature service owns the native import adapter call, loading and error state,
and the authoritative Recording refresh after any successful member. React
dispatches that semantic command and renders its localized outcome toast; it
does not compose preload and refresh operations. A completed recording exposes
Play directly in its list row. When at
least two distinct root Sessions are available, the
list may enter temporary batch-selection mode and submit their exact Cassette
IDs in one Replay Workspace launch. Selecting one Recording disables other
Recordings for the same root Session; this selection disappears when the list
closes and is never Recording or Cassette domain state. The primary workspace
recording list exposes Delete for inactive rows and requires a
portaled destructive confirmation dialog before removing the Recording and its
Cassette. Active rows remain protected by the daemon workflow. The primary
workspace window never renders Replay pause or checkpoint controls. Those
controls belong only to the isolated Replay Electron surface and become enabled
only when the daemon core exposes the corresponding stable commands; the UI
must not simulate them by dropping chunks or changing a local cursor.

While a Recording is active, Desktop observes the workspace
`AgentSessionEngine` boundary rather than AgentGUI. Public replayable intents
enter a synchronous renderer buffer; matching external command settlements
become `effect` events linked to the intent that caused them. Reducer-generated
follow-up intents are not recorded a second time, and effects without a
recorded cause are discarded. Desktop flushes this ordered stream through the
recording API before asking the daemon to complete the Recording, and drops the
buffer after a successful cancellation. AgentGUI remains unaware of recording
and replay contracts.
The isolated Replay Workspace reuses the Workspace window composition and
mounts one AgentGUI Workbench Node per Replay Cassette. Desktop installs one
Workspace replay binding, not one binding per Node. The binding maps generated
Engine `commandId` values to the exact Cassette; command results never fall back to
recorded correlation IDs across Cassettes.

Desktop mounts Cassette-scoped status observation and playback controls through
each AgentGUI Node's composer footer slot, while Replay runtime state keeps
them empty in normal windows. AgentGUI lays this accessory slot out as a
full-width wrapping row below the primary composer controls so Replay transport
does not compete with handoff, model, or reasoning controls in narrow Nodes.
Replay speed is a daemon-owned command. The
isolated Node resolves its Cassette from exact Node identity before reading or
updating playback through Desktop IPC.
Replay status remains visible independently of provider transport readiness:
the footer renders with disabled transport controls until playback becomes
active, and terminal completion produces a success toast in the isolated
Electron window.
The primary recording list asks for automatic or manual playback when Play is
selected. Automatic mode preserves continuous playback. Manual mode enters the
isolated runtime paused at the first inspectable checkpoint, so no initial
Activity interval can race a later renderer Pause command.
Pause, resume, and checkpoint movement use a versioned
`replay-control.json` handoff at
`TUTTI_AGENT_SESSION_REPLAY_CONTROL_PATH`, because pausing only the provider
transport would still allow the runner to dispatch later business stimuli.
The runner publishes daemon-confirmed semantic checkpoint state and playback
mode beside phase in `replay-status.json`; Desktop observes that file but does
not manufacture playback state in React. A checkpoint becomes inspectable only
after the exact Node is mounted, its logical Session is selected, current
detail is hydrated, and the renderer has observed the satisfying canonical
version. Controls remain forward-only;
Desktop does not expose previous-checkpoint or restart.
The primary window owns only Replay launch feedback. Main supervises the
runner by `(launchId, cassetteId)` and keeps Cassette milestones in memory plus
the temporary Surface-status handoff. It does not persist playback execution,
checkpoint, completion, failure, or cancellation into the primary daemon. The
cassette runner writes Cassette-scoped replay, verification, success, or failure
events, and a failure in one Surface keeps the Replay Workspace open while
other Cassettes continue.

The runner uses isolated daemon state and Electron `userData`. CDP opens
AgentGUI, selects the provider and exact Session, and verifies the rendered
result. Recorded business stimuli are sent through the isolated daemon HTTP
contract; they are not reconstructed from composer clicks. Cassette transport
selection is daemon composition and does not change Session, Turn, Interaction,
Goal, or runtime-operation lifecycle ownership in Host. The semantic Replay
runtime creates the isolated Workbench snapshot with onboarding already
auto-opened and no restored nodes, so the runner can open only AgentGUI.
Create-session stimuli persist the
effective launch settings returned by the recorded Session; Replay must not
recompute model, reasoning, permission, or speed defaults from the current
machine. The runner preserves lifecycle ordering by waiting for the canonical
Session to become idle before dispatching each recorded `session.send`; HTTP
status retries are not lifecycle authority.

Managed Replay launch has two Cassette-scoped milestones. `surface-ready` requires
the exact Node to be mounted, its root Session selected, and that Session's
detail hydrated; it closes launch feedback but does not complete the Cassette.
`replay-complete` is emitted only after that Cassette's stimuli, transport check,
and expected-state check succeed, and only that milestone resolves the
Cassette's local completion as `complete`. A create-session Replay restores its
recorded rail Project, waits
for the create command, and selects the exact canonical Session without
reloading the page.

## 3. Domain model

### 3.1 Session

A Session holds identity, target, provider metadata, cwd, title, settings, resume information, a Goal reference, and the current active Turn reference.

Session title has an explicit ownership rule in the runtime. A user title
(explicit rename) is immutable from the turn-execution path: a running turn may
fold provider/event titles as candidates, but the controller's current Session
is the only accepted state, and the turn-completion commit merges only the
turn-owned lifecycle/status fields back. A title the user set is never
overwritten by a late provider title or by a stale turn-completion snapshot,
and neither the stream projection nor the durable report may carry a stale
provider title over an established user title. On resume the runtime fails
closed and treats a persisted title as user-established.
Metadata commands issued while a new Session is still activating wait for the
canonical Session; an activation failure or bounded wait timeout is an
explicit user-visible error and never a silent no-op.

A Session does not copy Turn phase/outcome, own pending Interactions, or persist lifecycle inferred from transcript.

If provider-native compaction fails because the current context is already over
its hard limit, the provider adapter projects one typed
`context-handoff-required` system notice with error severity. AgentGUI localizes
the failure and tells the user to start a new conversation and mention the
exhausted Session there. Tutti does not replace the provider session or
automatically redispatch the user's next message: the fresh root Session and
its canonical `agent-session` mention make the handoff explicit and preserve
the user's control over what continues.

Provider-native subagents use child Sessions:

- `rootAgentSessionId` / `rootTurnId`: root execution
- `parentAgentSessionId` / `parentTurnId`: direct parent
- `parentToolCallId`: delegation card correlation
- child messages, Turns, and Interactions retain the child owner

A provider adapter must normalize explicit spawn evidence into both the parent
delegation call and the canonical child Session/Turn. AgentGUI attaches the
child lane only through the immutable `parentToolCallId`; it must not parse
provider-native spawn events, invent a missing parent card, or create a
presentation-only child lane.

The parent-side child lane preserves the latest canonical assistant message as
complete Markdown both while it streams and after the child settles. The same
safe streaming Markdown/link boundary used by ordinary assistant messages owns
that presentation. Bounded plain-text activity is only a fallback before the
child emits assistant content; character-level activity truncation must never
corrupt a generated-file link or drop earlier assistant context.

User-initiated Fork creates a new root Session rather than a provider-native
subagent. The child records durable lineage to the source Session and inclusive
boundary Turn, but receives a caller-reserved canonical Session id and a
provider-created Session id. Canonical Session, Turn, Message, and Interaction
identities are session-scoped and are remapped during the atomic clone. Fork
titles are allocated across the complete lineage family, so a source titled
`Session` produces `Session (2)`, `Session (3)`, and so on even when a later
Fork starts from an earlier child.

### 3.1.1 Session Fork

`throughTurn` means the boundary Turn and all earlier canonical history are
included. AgentGUI emits only the canonical Turn id. Host resolves its durable
provider root Turn id and invokes the exact provider adapter selected by the
runtime registry; shared UI and Host code never branch on provider names.

The projected Session capability is provider/runtime-level:

```text
provider registry declares native Session Fork
  AND the exact adapter/version attests throughTurn support
  AND provider state has an explicit host-copy or provider-owned binding mode
```

Only that conjunction projects `lifecycleCapabilities.forkThroughTurn=true`.
Projection consumes a live observation or persisted driver attestation only;
it does not prepare or launch a runtime. The full preparation and exact driver
revalidation happen after the user requests Fork.
Turn-level eligibility is the single
`providerForkBindingAvailable` fact projected from a non-empty canonical
`rootProviderTurnId`, plus the canonical Turn being `settled`. Host eligibility
remains optimistic and verifies only those selected-Turn facts. AgentGUI
exposes Fork only for settled, provider-bound Turns. This per-Turn presentation
rule is shared by every Agent provider. Source activity, pending Interactions,
descendants, and historical prefix provenance do not hide Fork actions for
earlier settled Turns. Only an in-flight Fork for that exact canonical Turn
disables its button.

Session Fork is available whenever the exact provider/runtime and selected Turn
project the capabilities described above. Desktop exposes that capability
directly, and tuttid verifies the same provider and Turn facts when executing a
new Fork write; no separate feature preference gates the action.

Execution accepts a worktree-isolated source. A provider-native Fork retains
the provider cwd, and Tutti freezes the same cwd and isolation coordinates into
the target snapshot without creating or transferring worktree ownership.
Other runtime facts are frozen into the target snapshot as well.
Only attachments referenced by that snapshot are staged into the target
namespace; the source attachment directory is never copied wholesale.

Fork is a durable Host-owned saga:

```text
prepared -> dispatching -> provider_accepted -> committed
                  \-> unknown
           \-------------------------> failed
```

`requestId` is the caller-stable replay identity and
`targetAgentSessionId` is reserved at prepare. Prepare freezes the complete
canonical snapshot through the selected Turn, the selected provider binding,
driver kind/version, runtime context, settings, and a deterministic attachment
manifest. Referenced attachments are staged into the target namespace before
provider dispatch. The source remains writable; only physical deletion retains
the frozen resources. A second explicit Fork from the same boundary is valid.
The provider call begins only after the `dispatching` marker commits.

The provider adapter verifies only that the selected provider Turn exists in
the provider source. Tutti deliberately trusts earlier provider and canonical
history to represent the same conversation. Provider acceptance and the child
provider Session id are persisted before host-copy binding and canonical
materialization. A binding or materialization failure therefore leaves
`provider_accepted`; retry continues only local work and never reissues the
provider mutation.

`prepared` recovery safely continues dispatch because the durable marker proves
the provider call has not begun. A crash in `dispatching` becomes `unknown` and
is never automatically redispatched. `provider_accepted` recovery retries only
local binding and materialization. The canonical commit consumes the frozen
snapshot without re-proving the live prefix, remaps all session-scoped ids,
normalizes a live boundary to `settled/interrupted`, supersedes copied pending
Interactions, persists lineage, and emits the complete committed delta.

### 3.2 Turn

One user submission or provider continuation belongs to one canonical Turn.

```text
submitted -> running -> waiting -> running -> settling -> settled
```

Terminal outcome is independent from phase:

```text
completed | failed | canceled | interrupted
```

Cancellation targets an exact Turn. `cancel_requested`, provider confirmation, and canonical settlement are distinct facts; UI must not manufacture an early terminal outcome.

### 3.3 Interaction

An Interaction represents an approval, question, or plan confirmation that requires user handling:

```text
pending -> answered | superseded
```

Actionable UI reads canonical pending Interactions only. A transcript tool row showing `waiting_input` does not create answerable state.

A provider adapter must publish `interaction.requested` with the complete
immutable input required by the action surface. When a provider splits one
request across ordered wire frames—for example permission identity and options
first, then the matching question body in a tool update—the adapter correlates
them by exact Turn and tool-call identity and delays Interaction publication
until the input is complete. A later transcript tool update cannot repair an
already-persisted incomplete Interaction. The adapter must also validate that
the provider wire can represent every answer allowed by the published surface;
an unsupported shape fails before publication instead of exposing a lossy
Interaction. This publication gate applies equally to emitted events and
`SessionState.PendingInteractive`; a snapshot must not leak the incomplete
request while the adapter waits for the later frame.

Approval detail presentation is provider-neutral. The daemon carries generic
`url`/`uri` and `prompt`/`instruction` display fields into the canonical
`toolCall.input` when a provider reports them only at the tool-call root, and
AgentGUI renders those fields from either canonical nested input or compatible
root input. Shared and local surfaces use this same projection; they must not
branch on a provider or tool name to recover web-action details.

A child Interaction may appear in the root conversation, but submission carries the exact `(agentSessionId, turnId, requestId)` tuple.
Every AgentGUI, Message Center, Desktop notification, and Mobile action submits
that tuple plus the user's current answer through
`engine.submitInteractionResponse`. The Engine allocates command identity,
applies the shared 30-second timeout, rejects non-pending or in-flight targets,
and recognizes an explicit exact repeat after a confirmed failure. It does not
silently reuse the previous answer when a caller omits fields, and it does not
retry delivery-unknown responses. Plan-implementation actions remain their
specialized plan-decision workflow rather than masquerading as ordinary
Interaction responses.

Free-text approval feedback is a non-terminal rejection. When an approval
offers both `deny` and a terminal `deny_and_stop`/abort option, the feedback
surface submits the non-terminal deny option and preserves the full feedback
payload; abort remains a separate stop action. A provider adapter first
acknowledges that exact approval response, then carries the feedback through
the provider's active-turn guidance protocol using the exact provider thread
and Turn identities. Waiting for that guidance acknowledgement must not turn a
successfully answered Interaction into a failed runtime operation.

### 3.4 Goal and operations

Goal is a Session-level durable entity, not a Turn command. It owns desired/observed state, revision, and an independent operation.

A Goal operation may produce zero or more provider Turns, but it cannot reserve or fabricate Turn IDs. Goal control bypasses the prompt pipeline and does not create a user transcript Turn message. AgentGUI dispatches `goal/controlRequested`; the workspace Engine owns the provider-neutral `goal/control` command, typed effect execution, and exact Session-scoped result reconciliation. AgentGUI may project its durable session audit as a dedicated `goal-control` timeline row; that row has no Turn ID and does not participate in Turn counts, processing ownership, cancellation, or settlement. When the audit carries a user-visible command body, the dedicated row also uses the shared user-message action surface, including copy.

When a session-level timeline row occurs chronologically between two rows from
the same Turn, transcript presentation keeps one Turn group and renders the
session-level row as an interstitial item. This presentation grouping does not
assign the row a Turn ID or make it lifecycle-owned by that Turn.

Host owns recovery for runtime operations, Goal operations, and the reconcile inbox. An adapter must not start a second worker or state machine.

On daemon restart, Host recovery first restores durable operations, then settles unrecoverable active Turns as `settled/interrupted` and supersedes pending Interactions.

Codex's restored Full access warning is presentation-only, device-local safety chrome. Show it only when an empty home composer restores an unacknowledged Full access target default; do not show it for another provider or permission mode, an active or historical Session, or while defaults are loading. Explicit Full access confirmation and “Don't show again” persist the same browser-local acknowledgement, while the close action affects only the current mount. This acknowledgement must not enter Session lifecycle, target defaults, Workbench node data, or `AgentGUIRuntime` state.

### 3.5 Edit retry and effective history

Edit retry is a Host-owned lifecycle operation, not a transcript mutation and
not a GUI-orchestrated pair of provider calls. It is available only for the
latest settled root user Turn when the provider exposes authoritative effective
history and the Session has no active or child work. The command carries the
exact Turn id, expected history revision, edited text, and a caller-stable
operation id.

```text
AgentGUI edit intent
  -> agent-activity-core typed command + stable client operation id
  -> Desktop transport adapter
  -> tuttid HTTP adapter
  -> Host durable edit-retry operation
  -> provider rollback/read/start capability
  -> SQLite effective-history transaction
  -> committed activity invalidation
  -> Desktop semantic event normalization
  -> agent-activity-core state-and-message reconcile
  -> AgentGUI canonical projection
```

Host checkpoints before provider mutation and treats provider `thread/read` as
the authority after an unknown result. Confirmed rollback retracts one complete
Turn from effective history but retains its audit row and file-change record.
The replacement reuses the persisted structured submission and changes only
its first text block, preserving attachments and other non-text input. Rollback
is never represented as natural-language model input.

AgentGUI projects only three presentation states: ready, processing, and
needs-action. It may expose edit controls only on the exact eligible Turn.
The workspace `AgentSessionEngine` owns command identity, pending/failure
state, recovery-action dispatch, and command-result reconciliation; React keeps
only the unsent editor draft and awaits the engine-owned command settlement.
An accepted transport result enters an engine-owned `reconciling` state and
does not overwrite canonical availability. Editing stays blocked until a
session-detail read confirms the returned history revision and recovery state;
Desktop must not manufacture recovery actions from the command response.
`resend_pending` and `recovery_required` are explicit recovery states rather
than indefinite loading. GUI recovery commands delegate to Host and never
choose whether rollback or replacement should be repeated. Completion and
terminal Turn events request both state and message reconciliation because
events are latency hints; the authoritative detail and message reads repair
missed WebSocket delivery without requiring a Session switch.

### 3.6 Messages and ordering

A durable message has two independent ordering values:

- `sequence`: presentation order assigned at creation; streaming updates do not change it
- `version`: per-session mutable change cursor used for incremental updates and gap detection

Lifecycle timestamps describe occurrence time; they do not replace durable sequence. A live message with unknown Turn ownership must be completed or rejected at the boundary, never assigned an owner in GUI.
Optimistic prompt and Goal-control echoes occupy a separate overlay ordering
domain. They remain after all currently durable messages until canonical
confirmation replaces them; their earlier submission timestamps must not move
them back through durable transcript history during message projection or
timeline merging.

Neither value is a history-coverage signal. A newest-to-oldest message read
projects an explicit Session message window into the frontend engine:
`oldestLoadedVersion` is the next paging cursor and the response's `hasMore`
becomes `hasOlderMessages`. AgentGUI may request an older page only from that
authoritative window. It must not infer older history from a non-one minimum
version, a version gap, `sequence`, timestamps, or transcript shape; streaming
updates can raise a message version without creating any older row.

The same rule applies to imported transcripts. When the provider transcript
contains trustworthy user-message boundaries, the import adapter persists
stable settled Turn identities before the data reaches AgentGUI. A page that
starts midway through a long imported Turn must therefore retain that Turn id;
AgentGUI must not depend on the leading user message being present in the
currently loaded window. Imported content before the first trustworthy
boundary remains explicitly session-scoped.

## 4. Workspace frontend engine

One `(workspaceId, runtime origin)` maps to one `AgentSessionEngine`. Panel unmount, Workbench node reconstruction, and standalone window switching must not change its lifecycle.

The engine owns:

- canonical Session, Turn, Interaction, and Message indexes
- pending activation/submit intents and optimistic projections
- prompt queue, send-now, and cancel-then-send coordination
- session mutation, Goal Control, settings, composer options, and operation
  state
- workspace/session reconciliation state
- ephemeral per-Session runtime command availability projected by the host
- attention/read state and cross-surface selectors

The engine does not own daemon persistence, provider transport, DOM, or permanent UI layout.

When a model change invalidates canonical context-window usage, AgentGUI keeps
the last rendered usage for that exact Session visible until a fresh canonical
usage value arrives. This retained value is presentation-only: it is keyed by
Session, never crosses into another conversation, and is never written back to
the workspace engine.

Runtime command availability is session-scoped whenever one workspace engine
can contain Sessions backed by different transports or access policies. The
host projects `available`, transport/capability blocking, or the explicit
`agent_sharing_revoked` state with the owner display label. The engine uses that
single fact to gate sends, cancellation, settings, and Interaction or plan
responses. AgentGUI preserves the composer draft content but disables editing
and runtime-dependent actions. A revoked shared Session keeps its history and
renders the package-owned owner-specific notice; it becomes available again
only when the host projects the sharing relationship as active. It must not
reuse the engine-wide connection state for this case, because one remote
Session losing its owner or access must not disable Local Agent or another
remote Session.

Mobile projects pending Interactions from the root conversation plus its child
Sessions and reads each exact Engine response record for submitting/failure
state. Native cards call `engine.submitInteractionResponse`; they do not
construct response intents, recover previous answer payloads, or keep a
parallel Promise lifecycle. After a confirmed failure, Mobile keeps the
canonical prompt and its explicit answer controls visible instead of replacing
them with a payload-free retry button. Missing provider-authored Plan options
fail closed, and runtime unavailability disables the exact response without
discarding composer drafts or Interaction identity.

Device connection presentation is target-scoped rather than Session-scoped.
The host exposes a target connection source keyed by `agentTargetId` with the
current status and retry attempt, and AgentGUI reads the active conversation
target or the selected Home target. This lets a new-conversation composer show
and enforce connection state before any Session exists. Session runtime
availability remains the independent command safety gate for existing
Sessions; it is not the source of device connection presentation.

Sharing eligibility is a parent gate for device connection. When an owner has
revoked a Session's shared Agent relationship, the host projects
`agent_sharing_revoked` and does not manufacture a target transport state for
that relationship. Device reconnect and automatic retry presentation begins
only while the sharing relationship is active.

Outside an exact pending Interaction, AgentGUI projects a blocked target
connection through the chrome above the composer and gives it precedence over
other non-interaction recovery notices because ordinary Composer writes cannot
complete while the target is blocked. An explicitly terminal `unavailable`
state appears immediately. Initial `connecting` appears only after a
300-millisecond controller delay so short background connections do not flash.
A recoverable host retry, including a dormant low-frequency retry, remains a
neutral `connecting` presentation and updates the visible retry attempt without
restarting the delay. During the initial delay, the raw target state already
blocks commands, but AgentGUI keeps the existing non-interaction recovery
chrome visible until the connection notice replaces it. Recovery removes the
notice without a success banner. The notice does not offer a manual retry
because transport recovery is host-owned.

When the Host supplies readiness for the exact approval or interactive prompt
being presented, that readiness result is the sole transport-chrome and early
write-admission authority for the card. Target connection and exact-Turn
observation gaps continue to gate ordinary Composer commands, but neither may
hide the card or override an exact ready or blocked interaction result.

Session presentation derives one canonical Composer gate from target
connection, Session runtime availability, provider readiness, ownership,
activation, Interaction, and busy/queue facts. The gate is one atomic
projection with separate editor, submission, and runtime-command decisions;
AgentGUI must not place `canSubmit`, target-connection blocking, or
Session-runtime blocking in independent memoized view slices and recombine them
later. The editor, send action, keyboard submit paths, Stop availability, and
Interaction submission consume that same gate snapshot. Busy work may project
queue submission while keeping the editor editable. Draft emptiness, upload
progress/failure, project existence, and other draft-local conditions may
disable submission, but must not change editor editability.

Engine submitting and unconfirmed-submit selectors remain Turn-admission facts
after a canonical Session first appears. Session existence or an `available`
runtime must not create an idle frame in the Composer spinner before the exact
Turn claims the submission, but these facts do not create execution busy,
Conversation `working`, or queue eligibility. A viable new-Session activation
with `initialTurnExpected` remains the same Turn-start bridge while no canonical
latest Turn exists. Goal-only activation deliberately does not set
`initialTurnExpected`, because Goal Control does not synchronously create a
Turn. A viable initial Goal `set` whose projected Goal is still active remains a
Turn-start bridge only while the Goal is optimistic or the host supplies an
exact pending/applying/unknown `goalSyncState` with a pending operation identity.
A synced Goal proves only that the Goal mutation converged; it does not prove
that a future Turn will exist. The first canonical Turn, a synced or non-active
Goal, `failed`/`diverged` synchronization,
`pending`/`applying`/`unknown` without an operation identity, or a
canceled/failed activation releases the bridge; initial Goal `clear` never
creates it. A host that omits `goalSyncState` cannot prove post-create execution
and therefore fails closed to the canonical availability projection instead of
keeping the Composer spinner active indefinitely. When a provider exposes an exact
session-level `running`/`idle` observation before Turn identity, the daemon
projects that
typed, non-persistent runtime activity through `agent.activity.updated` after
the associated state report wins canonical ordering. Desktop and Mobile Live
consume the same event variant. The workspace Engine uses its occurrence time
to reject reordering and prevents an older `running` observation from
overriding a settled Turn. A disconnect clears the ephemeral observation,
while canonical Turn state remains authoritative once it exists. AgentGUI
consumes the Engine's fenced Session display status after the canonical
Session exists; it must not recompute Composer busy state from the raw runtime
activity flag, because that would let an older `running` observation outlive a
completed or failed latest Turn. Raw runtime activity may bridge presentation
only before that canonical Session projection exists.

### 4.1 Read/write rules

- reads use exported selectors or memoized `AgentActivitySnapshot`
- an engine subscriber notification is an invalidation signal, not a render
  command. Concurrent AgentGUI surfaces subscribe through exact
  Session-family or target selectors; a selector preserves its selected
  reference when another root Session changes
- AgentGUI transcript presentation subscribes to projected messages for only
  the selected root Session and its current child Sessions. This projection
  includes optimistic `message_delta` text before durable confirmation, while
  preserving message-array references for every unrelated Session
- whole-workspace `AgentActivitySnapshot` projections remain valid for bounded
  aggregate reads, but do not belong in high-frequency AgentGUI render paths.
  Event callbacks that need current canonical data read the engine snapshot at
  event time instead of retaining a whole-workspace render snapshot
- optimistic `message_delta` invalidations are coalesced on the host-injected
  scheduler; the Desktop bridge queues matching session-message events and
  flushes them at the same boundary so the rendered snapshot and event fan-out
  cannot observe different prefixes. The external-store `subscribe` and
  `getSnapshot` callbacks must remain referentially stable across renders
- lifecycle writes use semantic Engine operations or typed intents/commands
- composer-option reads use `engine.loadComposerOptions`; the Engine owns
  request identity, signature-aware cache reuse, identical in-flight joining,
  supersession, exact settlement, caller abort, and disposal. Desktop and
  Mobile retain transport execution in their `EngineExtensionCommand`
  adapters and delegate pure generated-DTO projection to
  `@tutti-os/agent-activity-tuttid-adapter`
- A composer-option failure with no signature-matching cached value remains an
  explicit Engine `error` state. AgentGUI renders a compact failure and retry
  action in the existing options slot instead of presenting an empty list or a
  stale/default selection; a last valid cached value remains renderable while
  its load status is reconciled. The retry is the same semantic
  `engine.loadComposerOptions` operation with `force` left false, so request
  identity, cache reuse, and identical in-flight joining remain Engine-owned;
  a view must not call the transport adapter directly.
- an acknowledged home Composer default remains an optimistic draft until a
  later authoritative Composer-options response reports the same effective
  field value. A successful read alone must not retire the draft because a
  slow or overlapping provider discovery may still return an older default.
  When a settled response omits that field, AgentGUI keeps the optimistic
  intent but releases its confirmation marker so providers that cannot project
  the field do not remain on permanent forced, uncached discovery. Concrete
  conflicting authority is retried only for a bounded number of confirmation
  reads; if a provider keeps normalizing, rejecting, or overriding the default,
  AgentGUI protects the optimistic intent from generic option sanitization only
  while that confirmation marker remains active. Releasing the marker lets later
  settled options apply normal sanitization and return to the Engine's
  signature-aware cache
- the Engine alone translates shared activation, prompt send, settings update,
  Goal Control, turn cancel, Interaction response, rename, pin, and
  batch-delete commands into `AgentSessionEffectPort` calls. Desktop and Mobile
  effect ports retain transport, product integration, and host-specific DTO
  mapping. Their create/send request and Turn response projections delegate to
  `@tutti-os/agent-activity-tuttid-adapter`; they must not duplicate a
  command-type switch for these shared effects. Host activity facades call
  `engine.activateSession`, `engine.submitPrompt`, `engine.controlGoal`,
  `engine.stopSession`, `engine.updateSessionSettings`, `engine.renameSession`,
  `engine.setSessionPinned`, and `engine.deleteSessions`; these deep methods own
  the applicable workspace projection, protocol or mutation identity, timeout,
  cancellation, settlement, and canonical result projection. Settings
  update is fire-and-observe intent admission rather than a settlement Promise:
  the existing settings-operation selector remains the source of pending,
  failed, and unknown state. Hosts must not reconstruct mutation protocol with
  reducer intents and snapshot reads or construct raw
  `session/settingsUpdateRequested` fields for an existing Session.
  Session stop is also fire-and-observe admission: the Engine owns its command
  identity, 30-second cancellation timeout, duplicate fence, and 30-second
  first-Turn waiting window. Desktop AgentGUI and Native Mobile call
  `engine.stopSession` and never construct raw `session/stopRequested` fields.
  Existing-Session Goal Control is also fire-and-observe admission. The caller
  proposes one stable `clientSubmitId`; the Engine admission returns the
  effective identity used for settlement. The Engine owns workspace scope,
  command identity, the 30-second transport timeout, one in-flight operation
  per Session, optimistic Goal projection, typed result validation, and
  delivery-unknown reconciliation. AgentGUI reads
  `selectSessionGoalControlPresentation` and never stores a parallel optimistic
  Goal or settles the transport Promise itself. Desktop and Mobile effects send
  the request and map the authoritative Session/Goal/operation evidence only.
  Session activation enters through `engine.activateSession`. Desktop AgentGUI
  and Native Mobile keep product-specific target selection, placement, initial
  content/settings, and stable request identities, while the Engine owns
  workspace scope, timestamps, construction of `activation/requested`, the
  accepted result, and one 120-second confirmation window. The confirmation
  deadline is later than the 90-second new-Session command timeout so a valid
  slow runtime startup cannot expire while the command may still succeed.
  The typed activation effect returns either the created authoritative Session
  or the resumed Session's authoritative detail aggregate. The Engine validates
  the versioned `activation-v1` result contract, result scope, mode, and every
  nested Session/Turn/Interaction entity, then projects the aggregate in its
  own drain. Desktop and Mobile effects retain transport, DTO mapping, and
  product-local integration/observability concerns, but must not pre-dispatch
  those projections.
  Canonical monotonicity guards prevent a late activation response from
  regressing newer realtime state.
  A failed new-Session activation is a rollback signal only when the Engine's
  canonical Session selector confirms that no Session entity exists. If the
  Session exists but runtime startup or the initial Goal failed, the Session
  remains selectable and the failure is rendered as Session detail state.
  An explicit historical-row selection has higher priority than stale
  activation failure metadata; it first requests detail reconciliation and
  only returns home after an authoritative not-found result.
  Surfaces clear a new-Session draft only after activation admission succeeds.
  If an admitted new-Session activation is canceled before canonical Session
  confirmation, the surface restores the submitted draft only while the
  current draft is still empty, releases the pending `clientSubmitId`, and
  allocates a fresh identity for the next explicit submission.
  Existing-Session Prompt submission enters through `engine.submitPrompt`.
  The surface keeps the stable `clientSubmitId` used by its draft-recovery and
  idempotent-retry bookkeeping; the Engine owns workspace scope, timestamps,
  routing protocol, the shared 120-second confirmation window, and the
  accepted/queued admission result. Desktop AgentGUI and Native Mobile clear a
  submitted draft only after that result confirms admission, and never
  construct raw `submit/requested` fields or rebuild admission from selectors.
  New-Session initial content continues to travel with activation.
  Provider acceptance protects provider-turn identity and fork safety, but it
  is not the prompt's durability boundary. If runtime delivery is explicitly
  rejected or times out with an unknown outcome, Host persists the submitted
  content and `clientSubmitId` independently of the canceled request. Existing
  sessions then receive a terminal failed Turn or an uncertain-delivery claim;
  only an unobserved provisional activation may be compensated away.
  Platform-only commands remain in each host's `EngineExtensionCommand`
  adapter. Every effect propagates its typed Engine origin and Engine-owned AbortSignal to its
  transport. Rename, pin, and delete settle through the shared Session-mutation
  state. Rename and pin may update canonical Session state only from a validated
  authoritative Session result. Delete may remove canonical Sessions only from
  a validated `SessionDeleteMutationResult`, projected as `session/removed`
  tombstone intents. Caller cancellation aborts the host effect, but an already
  accepted write remains delivery-unknown until later canonical reconciliation;
  it is never converted into a confirmed failure. Direct settings changes,
  post-activation persistence, and
  prompt-required settings share one per-Session Engine lane. Owner boundaries
  are serialization barriers rather than coalescing opportunities. A validated
  precondition updates canonical Session state before the Engine starts send,
  while a failed or timed-out precondition prevents delivery. A timed-out
  settings write remains delivery-unknown and does not release queued writes
  automatically. A fresh explicit settings selection is the user's retry:
  `engine.updateSessionSettings` recognizes the exact Engine
  settings-operation state, so Desktop AgentGUI and Native Mobile do not derive
  retry flags independently. Ordinary approval and question answers similarly
  enter through `engine.submitInteractionResponse`; the Engine owns exact
  Interaction identity, command identity, timeout, deduplication, and
  confirmed-failure retry admission. Surfaces submit the current explicit
  answer and never dispatch `interaction/responseRequested` or reconstruct a
  previous answer themselves
- consumers do not read reducer maps directly
- consumers do not create canonical session/message mirrors
- optimistic records define confirmation, rejection, timeout, and uncertain-delivery paths
- business command completion returns to the engine as a result intent; controllers do not rebuild lifecycle with Promise/effect chains

Edit-and-retry availability is an exact SessionEngine projection, not a fact
inferred from transcript order. AgentGUI edits only the authoritative eligible
latest Turn, preserves attachment and non-text blocks through the Host-owned
submission envelope, and never optimistically splices the transcript. After
the command is accepted, Desktop applies effective history through the
composite authoritative snapshot; AgentGUI only renders that canonical result.
An authoritatively retracted initial optimistic prompt is marked on its pending
activation so it cannot be materialized again while activation metadata and
turnless controls remain intact.

### 4.2 Historical pull and realtime push

- list/history reads use `session/snapshotReceived` and do not create unread completion
- newest-to-oldest reads attach their authoritative message-window coverage to
  the same snapshot intent; incremental/realtime updates preserve that coverage
- realtime authoritative entities use upsert intents
- optimistic `message_delta` updates invalidate the exact Session projection;
  they do not write an unconfirmed message into canonical Engine state.
  Terminal `message_update` reconciliation replaces that optimistic projection
- an authoritative Session detail result enters through
  `session/detailSnapshotReceived`; `agent-activity-core` expands the root
  Session, Turns, child Sessions, and optional message coverage in one engine
  drain and one subscriber notification. Desktop and Mobile use the same
  `@tutti-os/agent-activity-tuttid-adapter` aggregate mapper and must not
  dispatch each entity independently
- Desktop and Mobile execute Engine-owned `session/reconcile` commands through
  the same activity-core Session reconcile executor. The executor owns scope,
  cursor/window, pagination, double-detail race closure, cancellation/deletion
  fences, and atomic application; hosts own transport, DTO mapping, diagnostics,
  polling, and presentation side effects. A shared-agent detail open also
  re-materializes a durable binding into the local Engine when its cached
  binding exists but the local runtime projection is absent; this repairs local
  state and does not mutate historical data.
- every daemon Session response carries the required `messageVersion`
  high-water cursor. Daemon and renderer ship as one protocol unit, so the
  shared adapter rejects a missing or invalid cursor instead of fabricating
  zero or entering a compatibility read path
- Desktop and Mobile use the same host-neutral event-observation helper to
  decide whether normalized entities can apply inline and whether the exact
  Session needs an authoritative state or message reconcile; partial parsing,
  identity mismatch, count mismatch, or cursor disagreement always reconciles
- message updates fold inline only when unseen versions are continuous
- version gaps and reconnects trigger incremental message reconciliation for hydrated Sessions
- Turn, Interaction, and legacy state invalidation trigger authoritative Session reconciliation
- realtime provenance survives until the authoritative result reaches the engine; fetch failure must not downgrade it to historical

### 4.3 Root and child hydration

Workspace lists show root Sessions only. A root detail read also returns nested child Sessions; the engine stores every entity, Rail selects roots, and timeline/Message Center selectors aggregate descendants.

Child Session discovery does not require every host to prefetch child transcript
pages. A surface that does not render child conversations keeps the hierarchy
and pending Interaction state canonical without paying for unused child message
history.

The shared reconcile executor exposes an explicit message-hydration policy.
Desktop selects Session-hierarchy hydration for its aggregate projections;
Mobile selects requested-Session hydration while it does not render child
transcripts. The first read remains a bounded newest-first page. Later detail
reconciliation compares each hydrated Session's required `messageVersion` with
the largest locally cached durable message version; an unchanged child performs
no message request. Newly discovered children use the bounded newest-first
read, while already hydrated children that advanced use incremental reads. A
known empty child window is an authoritative durable cursor at zero, so its
first later messages are drained incrementally from `afterVersion=0`; it is not
treated as an unknown window. The second detail read catches a root or child
that advances while the first message pass is in flight. Transient optimistic
rows never advance this cursor. This child policy is separate from the root
conversation's user-boundary repair policy, which may intentionally restart an
incremental read at zero.

The discovery detail request uses the daemon's `messageHydration` projection.
That projection retains the hierarchy and `messageVersion` cursors needed by
the shared executor but does not resolve provider-backed lifecycle
capabilities. The final detail request uses the full projection and is the only
read in one combined reconcile that may perform a historical provider
capability probe. Desktop and Mobile derive this choice from the same
activity-core request purpose; host adapters must not infer it from timing or
add a TTL cache for capability results. The detail response echoes the selected
projection and an explicit lifecycle-capability projection flag. The shared
tuttid client rejects mismatched responses, and consumers must not treat
false-valued capabilities from an unresolved hydration projection as
authoritative.

A `waiting` Turn does not imply user action. Only a pending Interaction produces approval/question attention.

### 4.4 Prompt queue

The busy-session prompt queue is ephemeral durable-intent coordination in the workspace engine. It is neither a daemon queue nor component state.

- a normal prompt waits for canonical availability
- a queued-prompt `Send next` action uses native guidance when the provider
  supports it, even when the provider also supports interruption; guidance
  stays on the same canonical Turn and follows the provider's native semantics
- when an active-turn `Send now` arrives before the Session has an authoritative
  capability snapshot, the workspace Engine retains the exact prompt and
  send-now decision without dispatching guidance or cancellation. A later
  authoritative snapshot resolves that same intent to native guidance or
  cancel-then-send. An explicit complete snapshot that supports neither keeps
  the prompt in the ordinary queue until canonical availability returns; a
  missing snapshot must never discard the prompt or be treated as unsupported.
  Each queued prompt owns its deferred decision and exact target Turn; a later
  Turn must not inherit guidance or cancellation intended for its predecessor
- Claude SDK guidance acknowledges delivery only after its SDK interrupt has
  succeeded and the guidance prompt has been enqueued; a failed interrupt is a
  failed guidance request and must not allow the old response to keep running.
  The confirmed interruption settles the old response's streaming projections
  while the canonical Turn remains active for the guidance response
- Codex/Tutti Agent guidance sends `turn/steer` with the exact active provider
  Turn identity. Steering inserts the guidance into the current provider Turn;
  it does not interrupt the response or start a replacement provider Turn. If
  the provider response has already ended while the canonical Turn remains
  active for child work, guidance may start a provider continuation with
  `turn/start` on that same canonical Turn
- guidance captures the canonical `activeTurnId` at the interaction boundary
  and carries it through the queue, activity adapter, daemon API, Agent Host,
  and runtime Controller; `turnId` is required for every cross-process
  guidance request and is never inferred from the latest Session snapshot
- Host and the runtime Controller compare that target with the live active
  Turn while holding the lifecycle admission lock. A mismatch is a typed
  pre-provider rejection (`NotDispatched`), and a prepared submit claim is
  removed so the failed guidance cannot strand the queue or be redirected to a
  newer Turn
- otherwise send-now performs exact cancel-then-send
- user Stop pauses the queue; cancellation must not leak the next prompt
- a durable pending-submit record does not by itself make queued backlog
  stoppable. A queued prompt without a Turn becomes a pending-submit Stop target
  only while that exact queue prompt is in flight or has uncertain delivery;
  visible or suspended backlog must not keep the Composer Stop spinner alive
- a prompt settings precondition is an explicit preparation stage, not a nested
  host effect. It serializes with direct and post-activation settings writes,
  updates the canonical Session on success, starts send before releasing later
  settings writes, and fails the logical prompt without delivery when the
  settings result is not valid
- a visible failed queue entry continues to own its submitted content for retry;
  draft settlement must not duplicate that content back into the composer
- uncertain delivery reconciles by `clientSubmitId` and exact `turnId`; it never resends merely because the Session appears idle
- editing a queued prompt restores its stable attachment references, then rehydrates missing image previews through `AgentGUIRuntime` with the exact workspace and Session identity; renderer-inaccessible paths never become image URLs, and late reads may update only the matching restored draft image
- rebuilding a Composer draft from queued canonical Markdown resolves mention labels and icons in each `AgentMentionNodeView` through the nearest workspace-scoped `RichTextMentionService`; every NodeView subscribes only to its canonical mention identity and keeps presentation out of the Tiptap document, while missing, failed, or removed services fall back to the canonical label and semantic icon. Agent target catalog presentation remains authoritative over service fallbacks
- the delivery barrier serializes new-Turn sends only; a guidance head steering the running barrier Turn is exempt and may steer it repeatedly, while in-flight, uncertain-delivery, suspension, and failed-head blockers still gate guidance sends
- drain readiness is one pure decision over the queue record and canonical availability; a new blocker joins that single decision with an explicit priority against every existing blocker, never as another independent pre-check in the drain path

### 4.5 Rail query and presentation state

The headless `AgentGUIConversationRailQueryController` is the single
cross-platform owner of Rail query scope, first-page refresh, cursor
pagination, stale-request fences, membership reconciliation, and Engine
ingestion. Desktop and Native Mobile both construct it through
`createAgentGUIConversationRailQueryController`, the canonical factory
exported by `@tutti-os/agent-gui/conversation-rail-controller`; a host must not
instantiate the internal implementation or recreate that state machine in its
app layer.

The Rail query cache stores section metadata, ordered Session IDs, cursors, and
totals only. Each first-page or pagination response passes Session DTOs
transiently through the host mapper into Engine upserts, while the Rail
snapshot retains only memberships, ordered IDs, cursors, totals, loading, and
failure state. Refreshing a bounded Rail page is not deletion evidence and
must not replace or prune canonical Engine entities.

The public headless snapshot contains query and membership state only.
Desktop-localized conversation summaries are projected from the snapshot plus
canonical Engine state outside the controller, so the Native entrypoint does
not depend on Desktop presentation or locale bundles. The public factory
accepts only the Engine, active-conversation identity getter, canonical runtime
queries, workspace identity, and small scheduling/page-size ports; cache
records, diagnostic trackers, and request-generation seams remain package
internals. Surface identity such as a Desktop AgentGUI `nodeId` is
adapter-owned diagnostic context: the Desktop runtime adapter enriches
diagnostic payloads instead of passing it into the headless controller
interface.

The full AgentGUI surface reads the optional
`AgentGUIRuntime.conversationRailQueryLimits.sectionRefreshLimitMax` backend
contract and passes it to that same controller. A host whose section endpoint
accepts less than AgentGUI's default refresh limit must declare its positive
maximum instead of relying on transport rejection or adapter-side truncation.

Resolved query results may be reused from the workspace cache. In-flight
first-page entity payloads are controller-generation scoped and must not be
shared across mounted controllers: detach, pause, or a scope change must fence
both Engine ingestion and cache writes from the obsolete request.
The canonical factory owns one resolved-query cache per workspace Engine, so
Desktop and Mobile receive the same remount semantics without exposing cache
access through `AgentGUIRuntime` or a host adapter.

Hosts own the transport adapter, DTO mapping, runtime-availability policy, and
surface lifecycle. For example, Mobile owns disconnected polling and
foreground/background pause-resume around the shared controller. Native hosts
also own their renderer, localized status projection, and interaction layout;
those host concerns must not leak back into the shared query controller.

Mobile DeviceLink recovery is application-scoped rather than screen-scoped.
`MobileApplicationService` is the single owner of the paired-device connection
phase (`idle`, `reconnecting`, `synchronizing`, `connected`, or `failed`).
Native stops Agent Live immediately on background entry while retaining the
underlying DeviceLink for its background grace interval. Every Native-to-JS
live delivery carries the caller-owned subscription generation; the bridge and
workspace live lane reject deliveries from a closed generation before they can
reach the coordinator. JavaScript records the background entry time and uses
elapsed time on foreground instead of relying on a timer that the runtime may
suspend. Foreground resume queues canonical workspace and selected-Session
reconciliation before opening the replacement live lane. An unexpected
live-lane disconnect first allows one bounded stream retry, then rebuilds
DeviceLink if the stream remains offline. Runtime commands stay blocked until
the replacement live lane reports ready.

Recovery retains the current device, workspace, navigation, and drafts behind a
global blocking presentation. A replacement workspace scope is started and
authoritatively hydrated before it atomically replaces the paused scope; a
failed candidate cannot clear the visible conversation. The App-root overlay
only projects the service phase and exposes retry or explicit return-to-device
commands. It does not own timers, transport checks, retry policy, or copied
connection state.

Cross-platform hosts may reuse the DOM-free canonical Rail summary projection
from `@tutti-os/agent-gui/conversation-rail-projection`. They must still obtain
ordered membership, project labels, totals, and cursors from the authoritative
section query and join those IDs to canonical engine Sessions. Native hosts own
their renderer and interaction layout; they must not import Desktop or Web
components, infer project membership from `cwd`, or create a second Session
lifecycle store.

AgentGUI's existing-Session project projection uses the authoritative
`railSectionKey` as its only join key: it matches that value exactly against a
registered user project's `sectionKey`. The key is immutable under runtime
reports, `cwd` changes, and user-project list updates. The `conversations` key,
a missing key, or an unknown key fails closed to no project
label even when the Session `cwd` equals or sits below a registered project
path. Conversely, a recognized project key keeps its project identity when the
runtime `cwd` is an isolated worktree or another detached execution directory.
Path matching is reserved for resolving the user's explicit project selection
before a new activation; it is not an existing-Session compatibility fallback.
The Remove project action delegates one awaited operation to the daemon. The
daemon deletes every unpinned root through the canonical Host batch path, keeps
pinned Session trees, atomically rehomes retained rows to Chats, and only then
removes the user-project row. Failure keeps the project visible for retry; the
renderer does not compose candidate-query, Session-delete, and metadata-delete
requests itself.
Native Mobile applies the same rule to Activity labels and Rail placement.
Section `sessionIds` remain query membership, page-boundary, initial-order, and
hydration data. After joining those memberships to current Engine entities,
hosts sort loaded ordinary sections by the canonical conversation sort key:
the latest Turn start time, falling back to Session creation time. Streaming
freshness, status, and completion updates do not change that key, so parallel
running Turns do not churn Rail positions. Pinned sections preserve the query's
pinned order. If a section disagrees with a Session's canonical
`railSectionKey`, the host rehomes the row by the Session key instead of
accepting the stale membership; presentation reordering must not mutate cached
memberships or pagination cursors.

Cross-platform hosts may also reuse the DOM-free canonical transcript
projection from `@tutti-os/agent-gui/conversation-projection`. It accepts the
canonical activity snapshot, selected Session id, and known Turns. The
projection derives both the Session and its messages from that one snapshot,
hides intermediate AgentGUI activity-card/timeline-item construction, then
returns the same `AgentConversationVM` that AgentGUI renders for message
merging, thinking, tool groups, processing, notices, and turn summaries. Its
portable navigation resolver covers only external URLs and Agent Session
mentions and depends on focused host-neutral parsing primitives shared with the
broader Workspace resolver; file, local-asset, app, issue, and custom-mention
actions remain host capabilities. Projection code in this entry must depend on
focused pure helpers for persisted pasted-text presentation and file-path
validation; importing the interactive Composer model or the broad Workspace
link resolver would pull Web-only editor, UI System, issue, and file-manager
types into Native consumers. Native hosts own their renderer, localized
fallback copy, scroll position, and temporary disclosure state; they do not
reinterpret raw message kinds or import the DOM transcript. Approvals, Plan
choices, and questions remain canonical pending Interactions, are projected
through the shared Interaction-to-Prompt seam, and continue to submit exact
option ids through semantic Engine commands rather than through transcript
rows.

Cross-platform hosts may reuse the DOM-free Composer policy from
`@tutti-os/agent-gui/composer-projection`. Composer-option loading remains an
`AgentSessionEngine` semantic operation keyed by the exact Agent Target. Both
Desktop and Mobile call `engine.loadComposerOptions`; the generated tuttid DTO
is mapped once by `@tutti-os/agent-activity-tuttid-adapter` into
`AgentActivityComposerOptions`, while the host extension adapter remains the
transport seam. Hosts render provider-authored options and use the shared
support projection, but keep Native/DOM menus and temporary open state local.
Existing-Session setting changes enter through
`engine.updateSessionSettings`. The Engine allocates command identity, fixes
timeout and retry policy, and translates the semantic call to its internal
`session/settingsUpdateRequested` intent. New-Session draft settings travel on
the activation intent instead; provider-independent draft projection and
Desktop-persisted defaults remain surface policy until activation. A renderer
must not call the settings endpoint from a component or invent a
provider-specific settings schema. Desktop and Mobile project the broader
Engine settings through one generated-contract allowlist before composer-option
or existing-Session settings requests. Both preserve supported fields such as
`browserUse`; neither sends `computerUse` until OpenAPI adds that request field.
Existing-Session Prompt sends similarly enter through `engine.submitPrompt`;
Desktop and Mobile provide content plus a stable client submit identity, while
the Engine owns common routing, confirmation expiry, and admission projection.
New- and existing-Session activation enters through `engine.activateSession`.
The surfaces retain target selection, placement, initial draft projection, and
stable request identity; the Engine derives workspace and timing fields,
projects the typed intent, and reports whether it was admitted. Actual Session
creation, resume, and initial Turn lifecycle remain owned by Agent Host behind
the host effect port.

An activation intent's shared Session settings are not an HTTP create-field
allowlist. Each host must construct a typed
`CreateWorkspaceAgentSessionRequest` and forward only fields present in the
generated contract. Both hosts preserve `browserUse`, which is a supported
create field. In contrast, `computerUse` is a default-on runtime setting but is
not currently a create-request field; neither host may add it as an extra
property. Supporting an explicit first-Turn opt-out requires changing OpenAPI
and the create adapters first.

Desktop and Mobile construct the headless controller through
`@tutti-os/agent-gui/conversation-rail-controller` and supply its narrow
query/diagnostic runtime port. The shared factory owns the workspace-scoped
cache lifetime while transport adapters own only protocol mapping,
authorization, and host-specific diagnostic context. Hosts that expose the
full AgentGUI mutation surface additionally install the complete query/mutation
cohort from `@tutti-os/agent-gui/conversation-rail-runtime`. Batch deletion
requires both authoritative section candidate lookup and the batch mutation.
AgentGUI fails that paired capability closed when either method is absent, so
the view cannot expose an action that will resolve to an empty optional-method
path.

Conversation deletion is transactional from the renderer's perspective. The
canonical delete command must succeed before AgentGUI clears the active
Session, changes Rail selection, unactivates runtime state, removes rows, or
discards local drafts. The same rule applies to batch deletion: a protected
Tutti execution conflict leaves the whole selection and local collection
unchanged. The conflict parser recognizes only the daemon's typed
`tutti_execution_active` payload; archive/view commands remain an optional
host capability until the generated execution adapter is present.

### Conversation Rail Activity View

`AgentGUIRuntime.conversationActivityViewEnabled` is the fail-closed host
boundary for the Conversation Rail Activity View. Desktop opts in explicitly;
external hosts that omit or disable it retain the ordinary Rail unchanged.

The view is a presentation-only activation over the current workspace Engine:
it reads visible root Session summaries, each root Session's own lifecycle
status, root-conversation attention/read state, and already-cached Session
messages. Descendant lifecycle activity remains available in the conversation
detail and interaction surfaces, but it does not change the root row's Rail
status. A pending descendant Interaction still contributes canonical
root-conversation attention so an approval or question cannot disappear with
the filtered child row; submission retains the exact child identity. Opening
Activity View must not call list pagination or transcript hydration.
Its membership input is the canonical mounted Engine summary collection, never
the ordinary Rail's transient `runtimeRailConversations` overlay; stale page
projections therefore cannot leak into Activity View.
Membership and recency are snapshotted when the view opens; subsequent Engine
pushes reconcile incrementally, while deletion removes a member immediately.
The Activity controller owns that activation and its retained row cache;
React render only consumes the controller snapshot and projects live row facts.
Existing Priority member IDs and their relative order survive ordinary Rail
refreshes that temporarily omit a summary; the controller uses the last known
row summary until the next toggle or an explicit canonical tombstone. Selecting
a historical Session that is temporarily injected into the visible summary
list does not make an idle Session a newly discovered Activity task; only its
live waiting, unread, or active facts can admit it to Priority.
The Engine preserves this distinction at the Turn boundary: `turn/upserted`
uses `live` provenance. Historical detail hydration writes canonical Turns with
`live: false` and cannot create new unread attention; realtime projections and
live reconcile writes use `live: true`. Omitted `live` remains compatible with
older hosts and is treated as live, while historical producers must pass
`false`. Existing durable read and unread markers remain authoritative during
hydration; only a read marker synthesized by the current historical observation
may be upgraded by a later live observation for the same completion.
The activation is scoped by the workspace, authenticated user, rail filter,
AgentGUI node, and Engine identity, not by the currently selected Session's
provider or target; selecting a row must not rebuild a cross-provider Activity
queue.
Search temporarily takes over the content area and clearing search restores the
same activation. Closing the view discards the activation and its retained row
cache. Existing workspace, authenticated-user,
rail-filter, AgentGUI-node, and Engine identities fence the activation
internally; the selected Session's provider and target do not. No Activity
filter or additional host scope contract is introduced. Disabled hosts use an
empty Activity selector and do not scan root Sessions. Activity rows omit the
minute-clock subscription together with their hidden timestamp. The full
product contract is recorded in
`docs/specs/2026-08-05-agent-conversation-activity-view-prd.md`.

The full first-page query is the only Rail read that resolves a navigation
scope and clears its pending state. Targeted section refresh and pagination may
update only an already-resolved matching scope. A subordinate result must not
cancel the full query, publish partial membership for an unresolved scope, or
unlock Rail interactions.

When Activity View has a non-null in-memory projection, that projection remains
visible while the unrelated initial Rail membership query is pending; Rail
loading, empty, or failure placeholders must not replace it. A refresh or page
failure after Rail rows already exist preserves those rows and reports a
non-blocking error through the host toast capability, falling back to the UI
System toast when that optional capability is absent. An unresolved empty Rail
scope retains the centered error state and its retry action.

AgentGUI owns one bounded retry for first-page and targeted membership reads so
every host receives the same recovery behavior across daemon restarts, transient
upstream failures, and transport loss. A fast transient failure retries once
after a short deterministic jitter while publication remains pending. A request
that already reached its timeout publishes the retained or empty failure state,
releases the interaction lock, and performs its one retry after a longer
background delay. Cancellation and permanent authorization, parameter, or other
non-retryable client failures never retry. Scope replacement and surface detach
abort both the active read and any scheduled retry; hosts must propagate the
controller-owned `AbortSignal` while retaining their own request timeout.

Presentation-invisible Sessions remain canonical engine entities and stay
available through exact Session selectors for trusted open, reconcile, and
command flows. Plural consumer selectors exclude them before Rail and Message
Center collection projection; a hidden Session must not become a list row just
because it is resumable or receives later canonical updates.

When runtime sections are enabled, projection unions IDs from the current
section, search, reconciliation, and every in-progress root Session in the
exact target scope, then joins canonical Sessions. In-progress Sessions remain
display overlays until the bounded section query contains them; overlay rows
do not alter cursors, `hasMore`, or server totals. Unchanged summaries preserve
structural sharing so unrelated engine updates do not rebuild the whole Rail
snapshot.

A locally initiated Session creation projects its exact target identity as
pending-creation reconciliation evidence until the canonical Session arrives.
This covers both new-conversation activation and Session fork, and the marker
is independent from any optimistic or runtime-overlay render source. When that
identity becomes canonical, the Rail controller refreshes the exact persisted
`railSectionKey` even if the new Session is currently selected. The selected
historical-Session fast path remains valid only when no pending-creation
evidence exists. An active or running overlay must never mask a missing
authoritative section membership that would disappear after the Turn settles.

Scroll, section collapse, visible limits, and search query belong to mounted view scope. Non-search state is isolated by `workspaceId + agentTargetId/all`; search creates a temporary navigation scope. `activeConversationId` expresses selection only. Scrolling requires an explicit reveal intent.

On the Home composer, a single-Agent Rail filter follows the effective composer
Agent Target whether the change originates inside AgentGUI or from host-owned
node data. The `all` filter remains broad, an open Session keeps its current
Rail filter, and unresolved/loading targets neither rewrite presentation state
nor expose placeholder target labels in Home chrome.

Rail scroll memory is captured by scroll events and explicit navigation. Effect cleanup must not synchronously read `scrollTop`: React may already have dirtied the document, turning that read into a full layout inside the interaction task.

An empty bounded Rail result must not unactivate an active or persisted Session.
Only an explicit Agent target selection may move the detail to that target's
Home composer.

Contain selection and presentation identity at the Rail boundary. Each section receives the active ID only when it owns the canonical or overlay row; unrelated sections receive `null` so their memoized props remain equal. Rail pane, section, and row receive a dedicated Rail-label projection whose identity changes for locale changes, not provider-specific detail copy. Event handlers shared by every section keep stable identities and read the current scope and lock state when invoked.

Keep section header/action chrome independent from changing item collections. A memoized header receives scalar presentation fields and stable event-time actions; it must not receive the section object or rebuild project/session semantics. Split the header into narrow render islands. Frequently changing derived booleans such as project drag disabled, project action locked, and batch deletion disabled may cross the Section presentation boundary through separate primitive Context projections. The Rail pane owns those providers outside the memoized Section so a projection-only update does not execute item projection; only the frame, forwarded-ref button leaf, or open menu content that renders the value may consume it. Do not combine those values into one Context object or copy them into persistent state. Menu disclosure is view-local state. A conversation row keeps its context-menu root mounted so right-click remains immediate, but may defer its normally hidden direct actions and dropdown root until the row is first hovered, focused, or opened by context menu. Once activated, those controls stay mounted for stable focus and keyboard behavior. Portaled menu content exists only while that menu is open, and a closed menu has no availability-state consumer. The project header remains the native drag source, each project section updates the insertion position across its full area, and the Rail scroll viewport owns the final drop so section gaps cannot discard an already visible insertion target. This is a presentation boundary, not a second Rail or lifecycle store; stable event-time guards remain authoritative for action delivery.

Relative time uses one renderer-realm minute clock. Timestamp leaves subscribe
directly; do not thread a tick prop through Rail pane/section/row and rerender
the interactive subtree every minute. Fully occluded AgentGUI surfaces do not
subscribe to that minute cadence. They retain the last clock snapshot while
hidden and refresh from current time when visual exposure resumes.

### 4.6 Detail and transcript

Rail selection, detail hydration, older-page loading, and transcript projection are separate states.

Desktop and Mobile use the same renderer-neutral AgentGUI conversation-message
controller for focused detail message queries. Initial hydration and latest
refresh enter the Engine as Session reconcile intents; explicit older-page
loads read only the Engine's authoritative message window, share one
in-flight/retry/stale-request fence, and apply mapped durable pages back to the
same Engine. Switching the focused Session or pausing the host aborts and
generation-fences the obsolete older-page request. A failed request remains
retryable at the same cursor.

The host owns mapped transport, foreground/background and disconnected-polling
triggers, diagnostics enrichment, scrolling, and rendering. Canonical messages,
Turns, Interactions, and optimistic prompts still come from the Engine; neither
Desktop view state nor Mobile services keep an older-message entity store. An
empty message list means neither hydrated nor not-found.
Selecting an already hydrated Session must not start another detail reconcile;
the selection controller alone decides whether hydration is missing. Composer
option synchronization does not own Session detail reloads. On Desktop the
selection controller also owns activation guards and Rail projection
coordination before requesting idempotent initial hydration. A repeated
automatic selection restoration must not become a forced refresh or append
pending demand to the in-flight reconcile; explicit user refresh is a separate
intent. The message paging adapter owns only focused message-controller
lifetime, transport mapping, diagnostics, and initial/older commands; it does
not call back into selection or Rail state. There is no separate messages-only
Engine reconcile helper.

Timeline projection is pure, deterministic, and provider-neutral. React views render rows/cards and dispatch actions.
Transcript Turn membership and order come only from timeline items in the
hydrated message window. Session-wide canonical Turn metadata may enrich an
already projected Turn by exact `turnId`—for example, by adding a view-only
terminal error when the provider emitted no error message—but it must not
create a transcript Turn that has no item in that window. The missing item
normally belongs to an older page; the projection adds the error when that
page is hydrated. A `user_prompt` Turn that still has no transcript item after
authoritative full hydration is an invariant or data-repair case, not an empty
row to manufacture. Goal and provider-initiated activity without transcript
items use their dedicated presentation surfaces.
Canonical reducers preserve entity and collection references when an accepted
Session snapshot is semantically unchanged, while still merging changed Turns
and Interactions at the same Session version. The legacy activity snapshot
projector preserves each unchanged domain-slice projection so reconcile
bookkeeping or composer-option updates do not rebuild transcript inputs.

Turn elapsed-time presentation starts at the client submission timestamp carried
by the canonical user-message payload, not at provider runtime start. Historical
activity without that timestamp falls back to the leading user-message
timestamp.

Completed Turn disclosure collapses only process-oriented rows such as thinking,
tool groups, progress, turn-boundary messages, and transient processing.
Ordinary assistant content, user messages, and the response-tail file summary
remain visible. The file summary owns the diff panel and stays at the end of its
canonical Turn after the final assistant reply.

High-frequency transcript updates must not pair DOM mutation with unconditional synchronous reads of the timeline's full scroll geometry. Conversation switches, explicit submit-to-bottom requests, skeleton transitions, and older-page prepend restoration may perform pre-paint scroll correction.

Transcript end-following is one UI-local state machine shared by DOM, TanStack
Virtual, and React Native adapters. It has only `following` and `detached`
modes. User scroll-away intent detaches synchronously, before the first scroll
frame. A mounted detail view retains the scroll anchor and follow-end mode for
each exact Agent Session it visits. First selection follows the end; returning
to a detached Session restores its retained position, while returning to a
following Session stays at the end. This mounted-view memory retains at most 64
recently used Sessions and evicts the least recently used entry beyond that
limit. It expires with the mounted view and never enters navigation, Engine, or
Session state. Prompt submission, an explicit scroll-to-end request, or the
user actually reaching the end may reattach. Content growth, layout effects,
observers, virtualizer geometry, and near-end thresholds are sensors or
executors only; they must not transition the mode.

Turn-level virtualization has one geometry owner. When the transcript is
virtualized and the state machine is `following`, TanStack Virtual owns append
following, streaming size adjustments, prepend anchoring, end detection, list
height, and item transforms. While `detached`, AgentGUI disables append
following so TanStack cannot bypass the shared intent owner, but retains
stable-item mutation anchoring so prepending an older page preserves the
visible viewport without reattaching to the end. AgentGUI retains Session
selection, explicit user intent, top-page loading, bottom-dock safe-area
measurement, and the non-virtualized short-transcript branch. It must not apply
native `scrollHeight`-delta prepend compensation or a content-resize bottom
write after the virtualizer accepts ownership.

The detail view reaches that owner through a narrow controller containing the
exact `agentSessionId`, `isAtEnd`, and `scrollToEnd`. Every read or write checks
the current Session identity; a stale controller is inert. Controller readiness
is reported back to the detail scroll controller so initial end positioning
still runs when the virtualizer acquires its scroll element after the first
detail layout. Virtual measurement keys also include the exact Agent Session
id, so replacing a conversation cannot reuse another Session's measured Turn
height. The virtual list measures its offset from the timeline scroll origin as
`scrollMargin`, including changes caused by the older-page loading indicator.
Direct DOM transform mode owns the virtual sizer height and item transforms;
React keeps only row content, measurement refs, cross-axis sizing, and
disclosure spacing.

Virtualizer- or layout-driven scroll events do not change the end-following
mode or trigger older-page loading without explicit user scroll-away intent. A
settled timeline that is too short to fill its viewport may still request older
pages.

Composer draft updates cross the view boundary through the stable `shell`,
`rail`, `detail`, `composer`, `interaction`, `readiness`, and `operations`
projections rather than one aggregate Detail prop. The active Timeline
`ScrollArea` is a memoized render island and does not consume draft state.
TipTap treats a controlled value as a local acknowledgement only when its
draft scope and local edit revision match; a scope change or other external
replacement may rebuild the document.

A virtualized transcript derives message-locator selection from the virtualizer's measured turn positions and explicit transcript identity. The currently mounted DOM window is rendering output, not a selection source; range changes must not make the locator temporarily select a neighboring message. Recent wheel and keyboard direction fences locator selection from reversing because of estimate-to-measurement scroll compensation or an item-list identity shift; the previous stable locator index is reconciled in a layout effect before paint. A genuine opposite input replaces that intent.

Historical rich text renders from the canonical Tiptap document through a static schema renderer. Only interactive composer surfaces own a Tiptap Editor/ProseMirror EditorView; read-only transcript surfaces reuse the same mention/token presentation without mounting editor lifecycle. Settled transcript messages reuse a bounded cache of pure Markdown ASTs and Tiptap JSON documents keyed by message identity and exact parser input; rendered React elements are never cached, and streaming Markdown bypasses this cache. Conversation titles are a separate plain-text projection: Markdown mention links are normalized to their `@label` text and never render mention SVGs or interactive rich-text tokens.

Fenced Markdown blocks whose exact language is `mermaid` use the bundled
Mermaid renderer only in non-inline transcript surfaces. While the owning
message is streaming, AgentGUI renders a stable diagram frame and placeholder;
it does not expose the growing source or repeatedly lay out the diagram. Once
the message settles, AgentGUI renders with Mermaid's strict security mode and
bounded text and edge limits. Active Turn lifecycle is authoritative over an
individual message or tool status: a completed tool must not settle a Mermaid
block while the owning Turn is still active. Oversized, invalid, or failed
diagrams render a compact failure state with an explicit source-copy action;
they do not automatically expose the source in the transcript. A rendered
diagram may open a presentation-local viewer with zoom,
reset, wheel input, and Space-modified pointer panning. Viewer transform,
disclosure, and theme-refresh state are UI-only and must not enter Message,
Turn, Session, activity-runtime, or workspace-engine state. The renderer is
packaged with AgentGUI and performs no runtime network fetch.

Attachment-only fallback labels such as `[Image]` may provide title or summary
text, but they are not an additional transcript text block when the canonical
structured content already renders the same image. Explicit display prompts
remain transcript content and continue to replace expanded rich prompt text,
except when the structured content carries the composer’s selected-text
reference blocks. In that case the conversation projection preserves ordinary
structured text and images, groups selected-text blocks into one leading typed
compact reference part, and uses `displayPrompt` only as a compatibility
fallback; the renderer owns the chip presentation. The selected reference is
presentation-only, so copy/edit actions remain attached to the ordinary typed
prompt part. This keeps the durable prompt and editing source unchanged while
preventing a display-only flattened prompt from discarding the reference
boundary.

Structured user-prompt transcript images keep resource acquisition and browser
image decoding as separate presentation states. A URL or hydrated data source
is not proof that pixels are ready: AgentGUI reserves the final thumbnail
geometry and shows its loading treatment until the exact image element reports
`load`. `error` replaces that slot with the retryable failure treatment. A retry
of the same URL or a replacement effective source starts a new decode attempt
instead of reusing stale loaded or failed state. These loading and retry states
are UI-local and never enter canonical Message or workspace-engine state.

Standalone hosts may opt a transcript into participant avatars through the
`agent-conversation` entrypoint's explicit presentation contract. Omitted or
disabled presentation preserves the existing transcript DOM. Enabled
presentation has distinct `loading` and `ready` states, so the renderer never
infers identity readiness from a missing image URL. The host supplies user and
Agent names and optional avatar URLs; AgentGUI owns the UI System Avatar,
fixed-size loading slot, fallback initial, and user-right/Agent-left layout.
Participant-header placement is projected from presentation turns rather than
individual message, tool-progress, or canonical Turn rows. A presentation turn
starts at a user message and continues until the next user message, so recovery
or provider continuation may span canonical Turns without duplicating the
participant header. Each speaker renders at most one header per presentation
turn, and a collapsed completed canonical Turn keeps the Agent header on visible
reply content.
This presentation input is view data only and must not enter canonical Session,
Turn, Message, activity-runtime, or workspace-engine state.

Standalone hosts rendering `AgentConversationFlow` may also pass the current
Agent target presentation catalog through the `agent-conversation` entrypoint.
The flow scopes that catalog to all historical rich-text rows, so `agent-target`
and `agent-session` mentions use the same provider icon and identity
presentation as the full AgentGUI node without copying the catalog into
canonical activity data. Omitting the catalog preserves an inherited AgentGUI
presentation context. The standalone flow also owns its visibility-aware
conversation clock, so a hidden host does not keep elapsed-time presentation
timers active.

Hosts whose action directories omit valid identities supply the complete
presentation-only catalog through `mentionAgentDirectory`. It retains exact
target IDs and unavailable Agents without making them launchable. Hosts that
omit this capability keep the existing union of provider-rail and handoff
targets. Interactive composer mentions, readonly rich text, and Markdown links
must resolve presentation through the shared target-presentation resolver.
They must not infer icons from target-id formats such as `local:*`; serialized
mention presentation is only the fallback when the current catalog no longer
contains a historical target.

## 5. Agent identity and provider architecture

### 5.1 `agentTargetId` is UI identity

Use `agentTargetId` for:

- Agent selection and Rail filtering
- composer-options cache
- Workbench node state
- new-session launch
- Agent mentions and handoff targets

`provider` is execution metadata, not UI identity. Multiple Agents may share a provider; UI must not group, deduplicate, cache, or fall back by provider.
Ordinary Session selection reads composer options through the existing
target/cwd/settings request cache. It does not force a refresh; force is
reserved for explicit invalidation, completed Session creation, and documented
provider prewarm behavior.

For an active Session, the composer treats `agentSessionId`, `agentTargetId`,
and `provider` as one Engine-owned identity projection. It must not combine a
target id from the canonical Session with a provider from lagging Workbench
node data. If the Engine target is not yet available or belongs to a different
selected Session, composer-option loading waits instead of issuing a guessed
request. The home composer continues to use its selected Agent Target as one
atomic projection.

Trusted host/daemon code resolves a target-backed request through `agent_targets`, then derives provider and runtime reference. If a client supplies both target and provider, daemon rejects a mismatch.

### 5.2 Provider strategy

```text
provider ID
  -> daemon providerregistry descriptor
  -> typed strategy / capability
  -> provider-neutral consumer
```

An unknown provider produces explicit unsupported behavior. Provider adapters normalize their own wire; shared renderers consume canonical message/tool/notice contracts only.

Desktop managed-provider setup reads the generated provider catalog's
`statusKind` strategy before requesting a provider-specific runtime candidate
catalog. The setup service and view must not keep a second provider-id list or
branch directly on provider names.

Skill invocation follows the same boundary. Filesystem and runtime adapters
discover skill identity, source, and plugin ownership; `providerregistry`
projects the provider-authored trigger and invocation strategy. Composer and
host adapters consume that projection and must not rebuild `$` versus `/`,
plugin namespaces, or prompt-item versus text-trigger behavior from provider
names.

For an active Session, composer Skill discovery also scans that Session's
isolated provider home. Opening slash search explicitly refreshes this catalog
so newly created Skills appear without restarting the Session; runtime-managed
Skills remain hidden through their `.tutti-managed-skill` marker.

App-server-backed skill discovery follows the descriptor boundary. Tutti Agent
requests only `skills/list` and retains the ordinary Skill projection through
the shared app-server transport, capability contract, cache, and structured
prompt-item submission path.

Model-only app-server catalog probes are a separate read path: they request
`model/list` without `skills/list` and pass the runtime launch preparation
contract's `SkipSkills` flag. These probes do not create a live Session and
must not resolve or materialize provider Skill directories. A Composer-options
read that returns both models and Skills keeps the normal Skill preparation
path.

Tutti Desktop's slash connector section is a local catalog projection,
not a Provider connector catalog. `services/tuttid/service/agent` reads the
daemon-owned connector-market application through its read-only snapshot port;
the Agent service never opens or receives the underlying repository directly.
It projects manifest presentation (including the catalog icon) plus installation,
authorization, and compatibility into a provider-neutral capability option, and
replaces any Provider-reported connector capabilities before returning composer
options. This keeps installable connectors visible in the slash menu while
ensuring that only installed and authorized connectors can be invoked. AgentGUI
does not scan external MCP, plugin, or package-manager configuration and does not
infer installation from a remote market response.

Authorization and draft selection are separate facts. Selected connectors are
stored as semantic draft blocks, rendered as removable chips, and submitted as
structured prompt content without synthesizing slash text. The compact Composer
trigger previews installed and authorized connectors independently from draft
selection, while preserving selected connectors first in that bounded preview.
A matching send on a session-scoped draft keeps those connector blocks and
clears the rest of the draft; home and other non-session scopes clear the
full draft. `/clear` keeps the session enable set. A new conversation starts
empty. The GUI submits the full enable set every turn; the daemon remembers
the last announced set and injects only the delta into the provider turn.

The device-global `lab.connectors` UI-preference flag controls whether that
projection is returned. The daemon fails closed when the preference is absent
or unreadable and removes Provider-reported connector entries as well as local
ones. Desktop invalidates cached Composer Options when the preference changes,
publishes the same invalidation through the AgentGUI host event bus, and
projects the host capability into the palette so stale cached connector rows
are hidden immediately. Workspace and standalone AgentGUI surfaces therefore
converge on the next canonical read without exposing stale entries. The flag
does not uninstall connectors, stop their runtimes, or reject an already
structured connector prompt.

Desktop also projects these flags through AgentGUI's existing host-owned
capability-menu state. The footer renders the Connectors menu only when
`lab.connectors` is on. The independent `lab.tuttiMode` flag defaults off; when
enabled, the same footer renders the Tutti Mode activation switch and the slash
palette exposes `/tutti`, including when Connectors are also enabled. When the
flag is off, both Tutti Mode entry points are omitted. The same footer serves
both the home hero and existing-session dock, so the two AgentGUI contexts
cannot drift. The one-time Desktop Preferences migration resets any persisted
`lab.tuttiMode` value to `false`; its durable migration marker preserves later
user opt-ins instead of resetting the preference on every launch.
The menu, selection-chip, and Palette-item implementations plus their neutral
item contracts belong to `@tutti-os/connector-renderer/ui`. AgentGUI owns only
the React-free capability projection under `integrations/connector`, Composer
placement, draft/prompt semantics, canonical option refresh request, and Tutti
Mode fallback. Its existing `onCapabilitySettingsRequest` host port emits the
exact connector key; the host delegates that intent to Connector Market's
shared open use case and mounts one window-level Connector Market dialog host.
AgentGUI does not load Connector Market state, construct its Root, or implement
Connector-specific visuals.

### 5.3 Agent Directory and setup

The host provides a complete, ordered Agent Directory with this load lifecycle:

```text
idle | loading | ready | error
```

`ready` may contain an authoritative empty list. `error` may retain the last successful snapshot. Components must not infer loading from `agents.length`.

One-shot Desktop surfaces that emit Agent identity, such as outcome
notifications, start and await their own Agent Directory load attempt before
resolving presentation. They must not depend on an AgentGUI or Workbench React
effect to initialize the directory.

The provider descriptor's target sort order owns the default built-in Agent
order. Tutti Agent is the first built-in target; an explicit device-local
Provider Rail reorder remains a presentation preference and takes precedence
over that default.

Tutti Agent is also the first Desktop default Provider for ambiguous new
entries. An exact persisted Agent Target or an explicit launch request still
takes precedence. AgentGUI and launch surfaces that require readiness fall back
through the authoritative ready Agent Directory when that default is
unavailable.

The directory owns Agent presentation. `agents[].iconUrl` is the primary
presentation asset used by conversation identity, Message Center, mentions,
and the empty-home carousel and Provider Rail. It is decorative metadata:
an Agent with an exact `agentTargetId` and name remains selectable when the
icon is absent. `maskIconUrl` may supply the monochrome conversation-row glyph.
Desktop Workspace Agent projections first inherit the resolved icon of their
Harness target by exact target ID, then use the provider/icon catalog fallback.
Host projections preserve these roles independently and do not create
provider-specific renderer catalogs.

AgentGUI accepts separate directory projections for separate responsibilities:
`agentDirectory` owns the current runtime rail, `handoffAgentDirectory` owns
launch choices, and optional `mentionAgentDirectory` owns exact rendered
identity. The mention directory may include offline or otherwise unavailable
Agents and must not participate in selection, admission, setup, or handoff.
This keeps availability as action state instead of deleting identity metadata.

Agent presentation images decoded for a canvas-backed texture must use
anonymous CORS loading before assigning `src`. Any host-owned custom protocol
that serves those images must return an `Access-Control-Allow-Origin` response
header so the decoded image cannot taint the texture canvas.

When the Desktop host projects built-in Agent mentions into a workspace app,
it replaces host-local file URLs with bounded 64px WebP data URLs. The external
bridge is the serialization owner: workspace apps must not read host paths,
register an Electron-only asset protocol, or re-encode the icon. Remote and
already-inline extension icons retain their authoritative URL.

Handoff target menus are an AgentGUI presentation contract. The shared
`AgentHandoffMenu` renders exact `agentTargetId` rows, ownership metadata, and
optional host-resolved `ownerDeviceLabel` metadata directly from the same
target, plus temporary disclosure/icon-motion state; a host supplies its
authoritative ready target projection and retains launch orchestration in
`onSelect`. Host surfaces must not reconstruct a second handoff row model,
observe the portaled menu DOM, or infer target identity from provider or
visible text. The current conversation's composer input availability is
independent from this launch surface: a target connection may disable input
while Handoff remains available when the host supplies the launch callback.
Handoff preserves canonical Rail placement: a source in the Chats section
omits its runtime `cwd` from the destination project selection, while a source
in a project section carries that project's path.
AgentGUI DOM surfaces render the target's owner badge through the shared UI
System Avatar primitive. A failed owner image falls back to the supplied owner
label initial instead of exposing a browser broken-image glyph.

For a signed Agent Extension, package `icon` is the primary identity and
optional package `maskIcon` is the conversation-row glyph. All assets remain
pinned to the verified active installation.

Target-managed setup uses exact `agentTargetId`; daemon persists its state and actions. Setup gates only the empty new-conversation surface. Active/history conversations follow host-projected Session runtime availability for exact-target capability and transport reachability. A blocked Session runtime disables both composer editing and submit until the host reports the Session available again.

For a built-in Runtime that is not installed or still requires authentication,
the Desktop readiness projection may additionally declare the host-owned
`onModelPlanSetup` action. AgentGUI then keeps the ordinary install/login
action and offers a secondary route to the host's Model Plan settings. Desktop
derives the capability from the provider descriptor's Model Plan protocol and
injects its managed-model settings route; shared AgentGUI does not name or open
that product destination. Unknown or unsupported providers omit it and keep the
single setup action. The capability is fail-closed: non-Tutti hosts, including
TSH/VN, omit it and never render the Model Plan route when they consume the
shared AgentGUI package. This route is navigation only: it does not rewrite
readiness, create a Session, or bypass activation-time Model Plan validation.

Provider-declared terminal authentication remains a Host capability, not React
or Session lifecycle. AgentGUI's target-setup controller owns the local
`idle`/`waiting`/`error` projection and terminal handle, while the Desktop host
launches the workspace terminal and monitors the authoritative target-setup
watch until it reports ready or the bounded wait expires. The view only renders
that controller state and dispatches start/cancel intent; it must not add its
own effect or timer polling loop, raise the AgentGUI degradation baseline, or
infer authentication from terminal output.

The built-in managed-environment wizard and Agent Extension setup have different owners. Shared UI must not combine their lifecycles by provider name.

See [Agent Extensions](./agent-extensions.md) for the detailed setup contract.

## 6. Agent GUI composition

### 6.1 UI chain

```text
AgentGUI
  -> AgentGUINode shell
  -> useAgentGUINodeController
  -> { viewModel, actions }
  -> AgentGUINodeView
  -> shared conversation components
```

Code uses stable horizontal layers and behavior-oriented vertical modules:

- shell: host/runtime/i18n/layout composition
- controller: selector binding, UI-local state, typed command dispatch
- model/projection: pure derivation
- view: DOM, focus, scroll, animation, event wiring
- vertical module: navigation, composer, timeline, Interaction, readiness, Goal, files/mentions

A controller may compose flows but cannot become a second lifecycle state machine. Extract complete behavior first; do not scatter it into a pile of domainless helpers.

Activation and existing-Session submit share a canonical prompt envelope. Submit eligibility includes text and renderable structured content; an individual composer does not redefine it.

`@tutti-os/agent-gui/quick-composer` is the draft-only public entry for
launch surfaces that need the canonical DOM Composer without a Rail or
timeline. It may present rich text, image draft blocks, and an exact Agent
Target selector, but it owns no Session, Turn, option-loading, or recovery
state. The host receives its typed prompt envelope and must route new Session
creation through the workspace's existing `AgentSessionEngine`; the entry must
never construct a second Engine or call a lifecycle transport.

The embedding host owns target readiness and capability loading. It passes the
canonical `agentTargetId` plus a capability snapshot for each selectable
target. Quick Composer resolves only the exact identifier and fails closed for
unknown, disabled, or capability-less targets; it never falls back to array
position, legacy `targetId`, or an inferred provider. Structured image content
is accepted only when the selected target declares image support. Submit emits
the resolved target identity with the prompt envelope, preserving the target
the user actually selected across the host activation boundary.
The Quick Composer public target omits legacy `targetId` and AgentGUI-internal
`ref`; the adapter derives both from canonical `agentTargetId` for the shared
Composer VM. Provider-menu selection therefore cannot cross or collide with a
second identifier namespace.

When an embedding host supports pre-session settings, it passes one explicit
settings capability containing authoritative `AgentActivityComposerOptions`,
a controlled sparse settings draft, its change callback, and option-loading
state for the exact target and project. Omitting any persistence path means
omitting the whole capability, so Quick Composer fails closed instead of
rendering interactive no-op controls. It projects supported values into the
same model, reasoning, speed, permission, plan, and browser controls rendered
by the full Composer; it does not maintain a second menu implementation or
fetch options itself. `computerUse` and gated `codexSaverMode` remain hidden
until an embedding activation seam preserves and authorizes them end to end. A
settings change returns a typed patch to the host, which refreshes authority
and forwards the settled draft through its existing activation command. Only
the very first options load for a target locks settings controls and submit;
once a good options snapshot exists, background refreshes keep every control
interactive and a failed refresh keeps the last good snapshot instead of
blanking the menus.

`@tutti-os/agent-gui/composer-settings-core` is the host-agnostic policy for
that settings capability. `ComposerSettingsCore` is a headless controller
(`subscribe`/`getSnapshot`, no React, no Engine dependency) that owns the
sparse settings draft, a revision-fenced options lifecycle with last-good
retention, defaults seeding via the daemon's defaults-merged
`effectiveSettings`, and trailing-edge write-back of explicit picks into the
canonical per-target composer-defaults ledger through injected ports
(`fetchOptions`, `rememberDefaults`). `resolveSubmitSettings()` returns the
exact values the composer displays; hosts must submit them verbatim so the
daemon never re-interprets empty fields against another surface's memory. A
Quick Composer host embeds this core instead of hand-rolling fencing,
failure semantics, or a parallel settings store; the desktop capture window
is the first adopter.

The Quick Composer uses the Composer's `embedded` layout contract. Unlike
`dock`, which intentionally grows attachments and long drafts upward over a
conversation timeline, `embedded` keeps the entire draft in normal document
flow. Compact host surfaces must select that layout instead of compensating for
dock overhang with consumer-specific offsets or clipping.

Embedding hosts may inject the same `RichTextMentionService` and workspace
reference-picker callback used by a full AgentGUI surface. Quick Composer wraps
those inputs in the canonical mention-service boundary and delegates reference
insertion to `AgentComposer`; it does not own a parallel mention catalog or
picker. A constrained host may also declare a top viewport inset for portaled
menus. Provider Select collision padding and mention-palette geometry must
honor that inset so host chrome is never treated as usable menu space.
An embedding host may also opt into the canonical project selector with a
controlled selected path and an explicit `WorkspaceUserProjectApi`. That
capability supplies the real registered-project catalog, selection preparation,
native directory choice, and project registration. A native directory callback
alone is insufficient: Quick Composer does not invent a project registry or
Session state, so it hides the project selector when no real project capability
is available. The host carries the resulting path through its existing
activation command as `cwd`.
AgentGUI's standalone locale runtime includes the scoped defaults of package
surfaces it mounts, including workspace-user-project. A host-supplied app
runtime may override those keys, but a standalone Quick Composer must never
render an unresolved scoped key as user-visible copy.
Quick Composer also establishes the canonical AgentGUI semantic-token scope,
so embedded placeholder, foreground, border, and menu colors never fall back
to inherited host text styles. Hosts may provide a compact action accessory;
`AgentComposer` renders it immediately before the primary send/stop action in
non-hero layouts instead of requiring consumer CSS to position controls over
the Composer DOM. An embedding host with a definite block size may opt into
`fillAvailableHeight`; the embedded Composer then gives its input group and
each rich-text editor wrapper the remaining height while keeping attachment and
footer rows intrinsic. The entire assigned editor block remains a native
contenteditable hit target instead of relying on a host-level click-to-focus
proxy. This remains explicit so ordinary launch surfaces keep the default
content-sized behavior.

An embedded host may also choose `composerActionPlacement="footer"`. In that
mode the same primary action cluster (including an optional host accessory)
joins the canonical Composer footer instead of the prompt row. This keeps the
reference controls, Agent selector, host modifier, and send button on one
alignment baseline without host positioning CSS; the default remains `input`
for existing consumers.

The canonical Composer gate belongs to the Session-presentation projection and
travels through the Composer view-model slice as one object. View-local
transition or workflow locks may layer on top as explicit presentation locks;
they do not copy or reinterpret runtime, connection, provider, ownership, or
queue readiness.

The conversation composer area is a stable `AgentComposerRegion` with explicit
floating-control, lifted-interaction, accessory, and primary-composer slots.
Workflow features compose through the accessory slot instead of adding another
bottom-dock layout or reaching into composer DOM. A disclosure accessory owns
only presentation and expanded state; its domain controller owns phase
selection and commands.

Tutti plan review and Issue execution project into one
composer-anchored `TuttiWorkflowDock`. The same banner shell expands upward and
moves through `review`, UI-local `materializing`, `execution`, or `error`;
there is no top-level Plan/Task tab and no duplicate full plan or Issue card in
the conversation timeline. Accepting a plan stores only the checkpoint identity
and title needed to bridge the read-model handoff, not an accepted-plan copy.
That UI-local marker is scoped by exact Session, workflow, and checkpoint, and
is cleared when the matching Issue or materialization failure arrives, the
decision fails, or a newer actionable checkpoint supersedes it. It must not
survive a completed handoff and later turn an ordinary Session re-entry into a
false materializing phase. During a genuine handoff the draft remains editable
while submit is disabled. The arrival of a newer actionable plan takes
presentation priority over an existing Issue. Each newly identified actionable
review starts expanded once; an explicit user collapse remains authoritative
for that review, while the disclosure's current expanded state survives
materialization and execution handoffs so the UI does not jump. The expanded
plan panel starts with the plan title and body; it does not repeat mode,
review-kind, or pending-state badges already communicated by the workflow
banner.

The reviewed document's effect and speed are immutable plan inputs, while the
Composer preferences remain mutable for the next Turn. A change is proven only
when the document carries both explicit frozen values and either differs from
the current Composer value; legacy documents with a missing pair never infer a
change from reasoning or orchestration fields. With a proven change, the empty
Composer shows `Request changes` beside `Accept`; without one, it shows only
`Accept`. Accept always targets the checkpoint bound to the currently projected
revision and therefore executes exactly the visible plan. The daemon rejects a
checkpoint that is no longer bound to the workflow's current revision, so a
stale render cannot execute replacement content. Typed feedback continues to
request changes and includes the current preferences when they diverge.

Task-assignment directories and target option catalogs are workspace query
projections, not Plan, Session, or Turn state. The Desktop assignment source
retains them in the shared bounded workspace query cache: directories are keyed
by workspace, while target options use exact workspace, Agent Target, and
provider identity. AgentGUI may synchronously reuse the last successful value,
including a stale value, while the source performs a deduplicated refresh.
Provider catalog and workspace model-configuration events invalidate only the
affected target entries; a generation fence prevents a pre-invalidation
response from becoming current. Composer options remain a separate
cwd/settings-sensitive projection and do not share this cache instance.

The materialized Issue is also a Tutti-owned aggregate-work projection for the
source composer. While dispatch is not paused and any task is nonterminal, an
empty composer shows the normal running Stop control even when the source
Session has no active Turn; this is presentation state and must not manufacture
an Agent Turn or change Host submit availability. Typed input replaces that
aggregate Stop with Send. Sending from the ordinary composer always uses the
normal source-conversation submit path, including while the Issue and source
Turn are active; canonical busy-session availability therefore keeps the prompt
in the normal queue. Provider guidance capability only enables an explicit
guidance action and never changes ordinary Send semantics. Stop durably pauses
Issue dispatch and cancels its running task Sessions, and also sends the
ordinary source-Session stop only when that Session has stoppable work. The two
idempotent paths are independent because canceling an idle Session merely to
trigger the Issue cascade could capture a later Turn.

Task-level accept and rework controls in that projection prepare localized
instructions in the exact source Session composer; they preserve any existing
draft and never send automatically. They do not call generic Issue Task
mutations or impersonate the source Agent's CLI authority. Once the user sends
the draft, the normal source-conversation submit path applies and the
Agent inspects the canonical Tutti execution before issuing checkpoint- and
revision-fenced commands. Other plan-panel interactions should use this
prompt-action pattern only when their intended effect requires source-Agent
judgment; navigation and existing daemon-owned commands remain direct semantic
actions.

An independent-review failure is a distinct workflow presentation, not a
generic retry loop. The dock may offer an explicitly user-triggered self-review
fallback through an optional host command and shows its pending, success, or
failure result together with the audit identifier. It never switches review
mode automatically.

An active Tutti Mode composer badge is a preference-settings entry, not a
destructive toggle. Clicking it opens the UI-local `TuttiBudgetPopover`, seeded
from the engine-projected `effect` and `speed` preferences. Every slider
movement sends its selected value directly through the existing Tutti Mode
activation command -- there is no draft/confirm step. Turning Tutti Mode off
remains a separate adjacent action, and all controls stay disabled while an
activation update is unresolved. The Desktop command host and HTTP adapter must
preserve the optimistic CAS revision and both optional preferences; dropping
any field turns a valid UI intent into a stale or semantically mismatched
response. Tutti Desktop advertises the Tutti Mode host capability only while
the default-off `lab.tuttiMode` preference is enabled. Toggling the preference
changes presentation without mutating an existing session's durable activation
or workflow state.

The preference popup uses two independent 0-100 sliders. `effect` raises the
minimum model capability and task-verification breadth. `speed` asks the
planning Agent to choose the fastest model that still satisfies that effect
floor and maps into an upper parallel target: `0-24 -> 1`, `25-49 -> 2`,
`50-74 -> 3`, and `75-100 -> 4`. They are combined, never averaged: high effect
plus high speed means "fastest suitable powerful model" with a target of up to
four parallel Agents, not a mid-tier model.

The popup previews a short model strategy and that parallel target. The target
is not a concurrency promise: the planning Agent may shape real independent
workstreams toward it, while actual scheduling remains bounded by dependencies,
ownership, safe isolation, ready work, budget, and the workspace-wide
four-Run ceiling. Exact models still come from the live composer catalog.
Effect-scaled verification remains planning policy but is not shown as a
primary preview metric.

Plan review reads the additive `execution.effect` and `execution.speed`
snapshots from current `tutti-mode-plan/v1` documents. A legacy v1 document
without those fields maps its single `orchestrationIntensity` value to effect
and uses the balanced speed default. The existing execution fields keep their
original Issue semantics; AgentGUI must not reinterpret
`orchestrationIntensity` as speed.

Home-composer project state distinguishes an unresolved durable default from an
explicit selection whose path may be null. The project selector may apply the
durable default only while that intent is unresolved. Entering the unscoped
conversation section resolves the intent to no project, so remounting the hero
composer or refreshing the project list cannot restore a previous project.

New-Session worktree launch is a fail-closed Host capability, not Session
lifecycle state in React. The host opts in with
`sessionWorktreeEnabled`, projects a launch preference map for the current
workspace keyed by the canonical project `sectionKey`, persists explicit
changes through `onSessionLaunchModePreferenceChange`, and supplies the exact
project-path probe through
`AgentHostApi.workspace.resolveSessionWorktreeSupport`. AgentGUI renders the
selector only when all four pieces exist, the selected target is explicitly
self-owned, a real project path and section key are selected, and the probe
succeeds. Existing Sessions and shared/remote targets never expose it.
Tutti Desktop carries the exact `agentTargetId` and project path through the
generated daemon support contract. Tuttid resolves that target through its
local launch authority and fails closed for shared-Agent identities. The
Session create boundary repeats the same target admission before allocating a
worktree and also requires a project `railPlacement` with a non-empty logical
project path. An unscoped `conversations` Session therefore cannot acquire
worktree isolation even through a direct API request, so React visibility is
presentation defense rather than the business authorization boundary.
The adapter records the selected repository-relative cwd and remaps it under
the isolated checkout, so a registered project below the repository root keeps
the same working-directory scope. A retry with the same Workspace, Session,
repository, and relative cwd reuses its exact metadata-backed checkout before
entering Host idempotency; a mismatched identity fails closed.

The stored `local | worktree` value records future launch intent; canonical
Session `isolation` records what actually launched. Probe failure, temporary
repository incompatibility, or a missing host capability makes the effective
mode `local` without overwriting a saved `worktree` intent. Visiting an old
Session also cannot write that preference. Tutti Desktop persists the nested
`workspaceId -> project.sectionKey -> mode` map in daemon-backed desktop
preferences and enables the capability. Each change uses the daemon-owned
`preferences.agent.session.launch.mode.patch.requested` workspace/project patch;
its SQLite transaction merges against the latest map, and full
desktop-preference updates preserve that field, so concurrent windows cannot
replace one another's choices. Renderer write failures roll back only
the still-current optimistic value and are consumed through the Workbench
diagnostic path. Published AgentGUI defaults the capability off so other hosts
may opt in independently. The composer only adds `isolation: "worktree"` to the
admitted activation input. Tutti's daemon adapter owns the filesystem checkout
and provider-preparation cwd, while Host continues to own the idempotent Session
create. The canonical Session projection later carries the created worktree
path, branch, and base commit. Rail rows render the worktree glyph from that
canonical isolation projection next to relative time in the unhovered row and
never infer it from `cwd`.

A locked Session cwd existence check is UI-local observation, not Session
truth. AgentGUI starts it only after pending creation has resolved, scopes its
result to the normalized selected path, and discards callbacks from a previous
path. Switching between Sessions that share the same cwd must not repeat the
same mounted probe. A host probe failure leaves existence unknown; only a
successful check that confirms absence may render missing-project chrome.

The empty-home carousel may measure its placeholder synchronously when live
alignment first activates. Later React updates coalesce alignment into the next
animation frame; ResizeObserver and MutationObserver keep layout roots current.

Composer text transactions may publish the current draft, but the draft value
must not drive synchronous pre-paint geometry reads or an urgent AgentGUI tree
render. The rich-text editor DOM owns the urgent input transaction. The latest
prompt ref updates synchronously for submit and attachment reconciliation,
while palette and controlled-draft projections publish in a React transition.
The editor recognizes stale controlled echoes from that transition so an older
projection cannot overwrite newer local input; a value not emitted locally
remains an authoritative external replacement.

An existing-Session composer derives input history from that Session's
canonical user-message projection and its turnless Goal-control audit entries;
it does not persist a second history store. These sources are merged by their
timeline timestamps so Goal commands participate in the same Up/Down sequence
as ordinary prompts.
The host capability remains explicit so unsupported hosts can fail closed, but
Tutti Desktop always supplies `sessionInputHistoryEnabled: true`; historical
`lab.agentInputHistory` preference values do not hide or disable the feature.

Composer model recents and favorites are separate browser-local menu chrome.
The Composer presentation projects the exact Agent Target identity together
with narrow provider-native catalog testimony, and one focused controller owns
storage reads, writes, cross-window refresh, and reconciliation. An unresolved
active-Session target disables history instead of reading or writing a shared
fallback bucket. Only an authoritative, settled native catalog may retire a
recent model; loading, empty catalogs, requested-origin entries, and
selected-model-only echoes remain unverifiable. Favorites preserve explicit
user intent even when a model is currently unavailable. The legacy shared
`default` bucket migrates lazily to the first exact target: recents pass through
current authoritative testimony before migration, while favorites migrate
without availability filtering.
Quick Composer projects the same history identity and testimony from its exact
selected target and host-owned options capability. Host-level option loading
keeps that testimony unsettled, so a retained last-good catalog cannot retire
history while the embedding host is refreshing or changing targets.

Bare Up/Down recalls older/newer structured drafts only from an empty composer
or an unchanged recalled entry, and only when the collapsed caret is at a
whole-document boundary. Palette handling and IME composition take precedence,
while editing a recalled draft exits history navigation. Moving past the newest
entry clears the composer. Adjacent equivalent submissions collapse, persisted
attachments are restored with exact workspace and Session identity, and
reaching the oldest loaded entry requests the existing authoritative older-page
read while preserving the timeline prepend scroll anchor. The history cursor
is UI-local and resets when the draft Session scope changes; Home has no
Session history.

The dock observes geometry through one coalesced animation-frame measurement
entry point. Editor document updates, attachment membership or intrinsic
attachment size changes, and changes to the stable input-shell width may
invalidate that entry point.
`ResizeObserver` must not observe the animated input area or editor block size:
their height transition is an output of measurement and must never feed back
into another measurement cycle. Width observations compare inline size before
invalidating, while attachment observers cover asynchronous chip and preview
sizes without a duplicate global resize listener.

The measurement pass is read-only. It derives natural text height from the
editor document blocks, reads attachment heights, and publishes one atomic
composer-metrics snapshot only when the snapshot changes. It must not
temporarily collapse or restyle either the editor or transitioned input
container. The dock input area establishes a local layout-containment boundary
so a composer read cannot invalidate the conversation root. Composer paragraphs
and the viewport calculation share the same line-height token so the 3.5-line
cap remains exact. Regression coverage must expand across explicit newline
rows, delete back to one row, and verify stable action-button placement.

Dynamic Agent surfaces must not use `:has()` on `.workbench-window`, the
timeline, or transcript rows. Composer and streaming DOM mutations would make
those relational subjects candidates for subtree style invalidation. Window
header layout and render-error state are projected onto the owning window or
header; message footer, speaker, thinking-edge, and row-kind state are projected
onto the owning message flow or transcript row. Small, self-contained controls
may still use local relational selectors when their subject and mutation scope
are bounded.

Composer mention providers own entity presentation metadata, including an
optional `iconUrl`, through their insertion result. AgentGUI mention
projections must preserve that metadata for every supported entity kind, and
the shared mention row renders the icon only when supplied. A provider-level
icon assertion is not sufficient coverage: presentation changes require both a
projection assertion and a consuming-row DOM assertion so an intermediate
view-model cannot silently discard the icon.

Composer copy and cut write both the canonical prompt Markdown as
`text/plain` and schema-serialized mention markup as `text/html`. Pasting that
markup reparses it through the AgentGUI editor schema, so built-in and
currently registered custom mentions retain their canonical href and chip
identity without a host DOM event interceptor.

External OS file paste and drop enter one host-injected classification boundary before draft attachment creation. The synchronous `resolveExternalPromptEntries` port classifies each source index as a live `WorkspaceFileReference` or a snapshot requiring preparation. AgentGUI owns ordered mention insertion and draft reconciliation: references become ordinary file/folder mentions and never consume prompt-asset slots, while only `prepare` entries create pending attachment state and enter `prepareExternalPromptFiles`. A host without the resolver prepares every external entry. The preparer owns native-path or byte lookup, size enforcement, persistence, and remote transport; each prepared input has one `sourceIndex` result, one failure must not fail siblings, successful results include a provider-readable `path` or `url`, and failures carry typed error codes. Hosts that classify path-backed entries as references must reject any such entry that unexpectedly reaches preparation, so classification failure cannot silently create a duplicate snapshot.

Plain-text absolute path paste may enter an optional host-owned
`workspace.resolvePastedPath` boundary. AgentGUI applies only a strict sync
candidate gate (one trimmed absolute path with no whitespace or quotes). The
host returns a `WorkspaceFileReference` to insert as a file/folder mention, or
`null`/rejection to fall back to plain text. Hosts that omit the callback keep
the previous plain-text paste path; existence checks, host-namespace
projection, and Shared-Agent policy remain host-owned.

Workspace picker results and internal workspace-reference drags remain live references. They enter the rich-text document as mentions and never pass through external-file preparation. A picker source whose selected locator is not yet consumer-readable may perform source-owned confirmation preparation before the mention is inserted; the picker waits in a loading state, publishes no partial result on failure, and remains open for retry. This confirmation transaction belongs to the reference source contract and is distinct from the external OS file preparation pipeline. Removing an inline external-file mention removes its draft intent; a later async result must not revive it or lose its error reason when the draft is in another scope.

A host may map a reference-source content error to a labeled recovery action
through the optional workspace contract. AgentGUI passes that policy through to
the shared picker without copying error state. The picker owns centered error
presentation and retries the failed browse or search; the host remains the
authority for deciding which structured errors can request authorization or
otherwise recover interactively.

### 6.2 Public node contract

`AgentGUINodeProps` groups fields by semantic responsibility:

| Object             | Responsibility                            |
| ------------------ | ----------------------------------------- |
| `identity`         | node, workspace, user, title identity     |
| `workspace`        | path, reference, project, Agent settings  |
| `frame`            | position, size, visibility, embedding     |
| `state`            | persisted Agent GUI node data             |
| `runtimeRequests`  | focus, launch, prefill, probe requests    |
| `hostCapabilities` | host catalog, readiness, menus, icons     |
| `hostActions`      | host mutations, Workbench/window actions  |
| `renderSlots`      | narrow product-neutral presentation slots |

`AgentToolBrowserPanel` owns its BrowserNode feature, surface identity, and
tab state. It also owns the single browser chrome instance for that surface.
Its controller may activate an existing page by URL inside that one surface;
the product Host remains responsible for choosing among Browser surfaces and
focusing the owning top-level node or window.
Desktop mode adapters register the same semantic Terminal, Browser, and Files
launch coordinators in each renderer. A Workspace adapter presents through its
Workbench host; a standalone Agent adapter presents through the right-side tool
sidebar and waits for the exact mounted controller when necessary. The
standalone AgentGUI `surface.host` represents the Agent node and must not be
used as a tool-launch host. After a canonical Turn is created, its originating
renderer claims the Browser presentation role through Electron main; Browser
automation then selects or creates that exact Agent or Workspace surface.
Automation may wait briefly when a provider tool request races ahead of that
claim. Unclaimed legacy Turns retain the user/Workspace fallback. Host
readiness must not be used to infer Turn origin. These tools remain Desktop
chrome and do not enter AgentGUI lifecycle state.
Hosts compose window controls into the tab strip through `defaultActions`,
pass draggable-header semantics through `dragHandleProps`, and use
`navigationActions` for address-row actions. A host must not wrap the panel in
a second visible title bar or recreate the browser header outside the panel.

Host-issued `runtimeRequests.composerAppend` values are one-shot requests. An
append may carry prompt text, prepared files, or one semantic connector key.
AgentGUI waits until the exact requested Session is the active conversation,
applies the append once to the structured draft, and then calls
`hostActions.onComposerAppendHandled(sequence)`. A Host that retains routed
requests must clear only the acknowledged sequence; it must not let an older
open-Session append mask a newer request.

Collaborative Hosts may supply
`hostCapabilities.interactionReadinessSource` for exact pending Interaction
write admission. The source is keyed by
`(workspaceId, agentSessionId, turnId, requestId)` and exposes only
`ready` or `blocked(synchronizing | owner_offline | binding_revoked)`.
AgentGUI does not compose presence, transport, or lifecycle facts. When the
capability exists, a missing exact record fails closed as synchronizing;
omitting the capability preserves ordinary local-Host behavior. AgentGUI reads
the same source for presentation and again at the event-time submission
boundary. This readiness is ephemeral Host policy and must not enter canonical
Session, Turn, Interaction, or Engine state.

While an exact approval or server-projected interactive prompt is presented,
this capability owns its transport chrome. Target connection and observation
gap sources still govern target discovery, ordinary composer writes, and
sessions without an exact Interaction, but they must not override an exact
ready or blocked result. Synchronizing and owner-offline results keep the
pending card visible while disabling its actions; binding revocation is the
terminal exception.

If an approval and a server-projected prompt coexist, AgentGUI reads readiness
for both exact identities. Each surface consumes only its own admission result;
selecting one as the active prompt must not reuse its readiness for the sibling
Interaction.

Do not restore flat compatibility props or hide workflow inside a render slot.
The optional `renderSlots.projectDirectoryPickerHeaderActions` slot is limited
to host presentation beside the directory picker's title. AgentGUI owns picker
state and supplies refresh plus source-located target selection after host
mutations; the host owns the action's side effects and must not duplicate
picker navigation or selection state.
Hosts that render capabilities owned by another device set
`hostCapabilities.capabilityControlsReadOnly`; AgentGUI keeps owner-supported
Browser/Computer entries visible but disables their mutation and setup actions.
Unsupported capabilities remain absent according to the authoritative composer
capability descriptor. A caller host must not open its local device settings as
a fallback for a remote owner.
Account and Commerce UI is Host chrome rendered through
`@tutti-os/commerce/react`; it is not an AgentGUI node capability. AgentGUI
accepts only generic `hostCapabilities.visibleErrorPresentationOverrides` for
structured product errors. The host owns Account/Commerce requests,
login/logout, external navigation, reward receipt persistence, clipboard
writes, notifications, localization, feature gating, and menu lifecycle.
Neither AgentGUI nor the frontend Commerce package may receive a Cookie or
start a Commerce request.
For a shared Agent conversation, the Host sets the presentation-only
`hostCapabilities.visibleErrorPresentationScope` to `shared_caller`.
AgentGUI preserves the canonical structured reason and existing diagnostic
disclosure, substitutes caller-safe contact guidance only when the structured
code identifies an Owner-remediable failure, and suppresses current-device and
current-account remediation actions. Transport and ambiguous failure copy stays
neutral and retry-oriented. Omitting the scope preserves `local_owner`
behavior. The scope must not enter Turn, activity, Engine, event, persistence,
or provider contracts.
The optional `renderSlots.agentConfigAccount` is a presentation-only Host
chrome seam for the exact selected Agent Target. Its paired
`hostActions.onAgentConfigMenuOpen` notification lets the Host refresh account
state without hiding workflow in the render slot. Returning no renderable
content keeps the provider account and quota block unchanged. Returning the
package-owned `AgentGUIConfigAccountFallbackSuppressed` marker suppresses those
generic fallback rows without adding Host content.

Tutti Desktop fills this seam only for its self-owned local Tutti Agent target.
The Desktop Account service remains the source of account, membership, credit,
and Commerce-link state; opening the target menu asks that service to refresh,
and the render slot stays request-free. Its compact Agent menu omits the
redundant Tutti account identity row while retaining credit, membership, and
account-center actions. A signed-out local Tutti Agent returns the suppression
marker because the generic provider-account and quota rows do not describe its
Host-owned account model. Other providers return `null` and retain AgentGUI's
default provider-account and quota presentation.
The optional `renderSlots.agentTargetInfo` seam enriches the exact target icon
in the provider Rail and Conversation Rail. The same
`AgentGUIAgentTargetInfoRenderer` may be passed to
`AgentGuiWorkbenchHeader.renderAgentTargetInfo` with its exact
`conversationAgentTarget`. AgentGUI owns Tooltip disclosure, positioning,
focus behavior, and the built-in label fallback; the Host renderer receives
only `{ target, surface }`, remains presentation-only, and is invoked lazily
while the Tooltip content is mounted. Conversation rows resolve the target by
canonical `agentTargetId` from the current Host directory and fail closed when
it is absent. They do not copy owner, device, availability, or other target
metadata into Session state.

Unavailable Agent targets retain the standard empty-home identity. AgentGUI
projects offline transport and revoked-sharing states through the same Home
status chrome used by other runtime failures, immediately above the composer;
it does not expose a second Host-owned availability container. The canonical
composer gate blocks both editing and submission until the selected target is
available.
Host chrome that aligns to AgentGUI's internal layout must consume explicit
package signals such as `hostActions.onConversationRailLayoutChange`; it must
not observe package DOM, CSS variables, or class names with
`MutationObserver`. Composer affordances belong in AgentGUI itself or a
narrow `renderSlots` contract, not in host-owned portals inserted into package
DOM. During a Conversation Rail drag, AgentGUI emits this signal with
`resizing: true`; the Workbench and standalone desktop headers apply that
ephemeral width only to their own grid alignment, while the existing
`onUpdateNode` path remains the sole persistent width write. Hosts must not
write node state for each pointer movement. AgentGUI updates both its grid
track (`--agent-gui-conversation-rail-width`) and the Rail content width
(`--agent-gui-conversation-rail-content-width`) in that same pointer move;
updating only one leaves blank space when expanding or overflows detail content
when shrinking.

### 6.3 `AgentGUIRuntime` and `AgentHostApi`

`AgentGUIRuntime` is the runtime surface accepted by `AgentGUI`. It owns reads,
Rail queries, file/upload capabilities, subscriptions, diagnostics, and the
workspace `AgentSessionEngine` lookup. Shared lifecycle writes enter through
semantic Engine methods or typed intents; AgentGUI does not require duplicate
`activateSession`, `createSession`, `goalControl`, `sendInput`,
`submitInteractive`, `unactivateSession`, `updateSessionSettings`, or
`updateTuttiModeActivation` callbacks.

`AgentGUIRuntime` is the sole AgentGUI host contract. Hosts must not recreate
the removed lifecycle callbacks as no-op or forwarding adapters. Metadata
actions that AgentGUI still reads directly remain on this surface until their
Engine migration preserves all host observability and product integration.

AgentGUI performance correlation is package-owned through
`createAgentGUIPerformanceMonitor`. A host supplies the workspace Engine, the
existing Session-event subscription, a clock, and a product-neutral event
sink. The monitor joins AgentGUI's preserved `submittedAtUnixMs` and queue
diagnostics to exact Session and Turn identities, then emits activation
settlement, Prompt admission, first-token receipt, Turn settlement, and
Composer-options load facts. `trackComposerOptionsLoad` emits a start fact
before calling either the runtime `getComposerOptions` or exposed Engine
`loadComposerOptions` path, then emits a correlated completed or failed fact
with exact duration. An unmatched start therefore remains observable when a
Provider options request never settles. The facts distinguish runtime from
session-Engine entry, force refresh, directory presence, bounded error
category, section/stage, and model count. Settled Composer events may include
a bounded, deduplicated, control-character-cleaned allowlist of model
identifiers; paths, settings, prompts, credentials, and error messages remain
excluded.
Hosts map those facts to their own analytics catalogs; they must not copy the
Turn-binding, early-event buffering, duration-bucket, or token-classification
logic.

First-token time ends when the renderer receives the first non-empty Agent
content `message_delta`; its bounded kind is text, reasoning, plan, or other.
It deliberately does not use the producer timestamp, infer a latest Turn,
count tool output, or inspect Prompt or response content. Early deltas are
retained only until the Engine supplies the exact Turn binding, duplicate
deltas emit once, and bounded caches prevent an abandoned Prompt from growing
runtime memory without limit. Exact `durationMs` accompanies the stable
buckets `lt_1s`, `1s_to_3s`, `3s_to_10s`, `10s_to_30s`, `30s_to_60s`, and
`gte_60s`.

`AgentHostApi` supplies host capabilities only: files, clipboard, project/account lookup, Agent Target setup/probes, diagnostics, and OS/Workbench helpers. It must not become a Session, Turn, timeline, or write source again.

Terminal authentication is one such Host capability. AgentGUI receives an
optional atomic `terminalStartupAction` containing a safe slash-command name
and literal readiness marker, then returns it unchanged through
`terminalLogin.run`; neither layer accepts or synthesizes raw terminal input.
Hosts must explicitly list supported startup action types; an older Host that
omits that capability may still expose the manual command fallback but cannot
silently launch a typed action it does not implement.
The Desktop Workbench presenter owns node launch, exact-session readiness
matching, slash submission, diagnostics, and close cleanup. Its startup result
must settle before the setup-readiness monitor starts, so timeout, cancellation,
or transport failure cannot leave a second polling lifecycle behind.

The optional quick-prompt library follows that host-capability boundary. Tutti
Desktop projects the device-global `tuttid` quick-prompt CRUD service through
`AgentHostApi.quickPrompts`; AgentGUI owns only the picker/editor presentation
and inserts a selected prompt into the current TipTap selection without
submitting it. The library snapshot and cross-window invalidation are not
Session or Turn state and must not enter `AgentGUIRuntime` or the workspace
engine. Hosts that omit the capability render no quick-prompt composer entry.
AgentGUI may also present a small, localized set
of recommended templates; those only prefill the existing editor and remain
client-local until the user explicitly saves them through the CRUD capability.

### 6.4 Multiple surfaces

AgentGUI, Message Center, dock/header, workspace window, and standalone Agent window consume the same workspace engine.

Opening a panel/window creates presentation state only. It does not clone a Session, copy engine entities, or start another event stream. Standalone tools are Desktop chrome, not AgentGUI lifecycle.

Workbench previews must not mount a second AgentGUI tree. Genie capture prefers
the host-provided native image and clones the visible node DOM into a texture
only after native capture fails or exceeds its bounded wait. Electron hosts
pass the sanitized node region directly to `webContents.capturePage`, retain
the returned region for Genie, and resize a copy for the Dock. The Genie path
must not reuse an undersized Dock image. Dock popup
cards and minimized slots use the bounded image and its cache. A background or
minimized popup node must not request a fresh DOM snapshot: AgentGUI may be
unhydrated, and `surface.isVisible=false` deactivates imperative resources such
as the hero Canvas. Those nodes reuse only a previously successful image. If no
captured image exists, the Dock shows a static terminal placeholder rather than
an in-flight skeleton; it does not mount AgentGUI or render a conversation
summary as a fallback. Capture failure is not cached across popup lifetimes, so
a later foreground attempt may still populate the image. AgentGUI therefore
has no preview-mode rendering contract.
When a minimized node has a cached Genie texture, Workbench completes the
restore animation before launching the host node, then replaces the final
texture frame only after launch settles. The expensive AgentGUI reconstruction
therefore stays outside the animation. Workbench also prepares the Genie canvas
during browser idle time with representative scanline, scaling, and glow
operations, and commits the final minimize state in a later task instead of
extending the last animation frame. A later minimize may start from that
retained texture while the host refreshes its native capture asynchronously;
a native image replaces the retained Genie texture only when it can cover the
current window without upscaling. Low-resolution thumbnails update only the
Dock preview cache. A late native result updates that Dock cache immediately,
but Workbench decodes its full-size image only after the active Genie animation
settles and the browser is idle. Without a reusable full-resolution texture,
Workbench falls back to the visible DOM capture. The retained Canvas cache is bounded by
both entry count and estimated RGBA bytes. Restored nodes keep their texture for
the next minimize; controller state changes remove textures only after their
nodes are closed. Eviction leaves the separate Dock image cache intact.

Genie node hiding uses a per-node operation token. A newer operation for the
same node may supersede an older reveal, but another node's animation may not
leave the first node hidden. The global animation generation controls only the
shared Genie Canvas.

The empty AgentGUI Hero renders its existing DOM player before initializing the
optional WebGL carousel. A host projects whether the normal window presentation
is currently visible; the carousel waits for that visibility and then browser
idle time before creating its WebGL renderer. This keeps Genie restore work out
of the WebGL creation task without exposing Genie state to AgentGUI. A fully
occluded presentation releases its scene, decoded images, observer, and wheel
listener; exposure restores them after the reveal interaction settles. Once
initialized, WebGL renders only for texture or size changes and carousel
selection changes; the spring stops requesting frames after it settles. The DOM
turntable record uses a compositor animation only in the active visible
AgentGUI, and composer prompt tips follow the same active-surface rule.
Empty-Hero entry animations may fill backwards across their delay, but must
release their final identity transform after completion so every mounted
AgentGUI does not retain decorative compositor layers. An embedded AgentGUI
skips those internal entry animations because the Workbench shell already owns
its appearance transition. Background Workbench AgentGUI bodies remain mounted
so drafts and local conversation presentation survive focus changes. Focus does
not determine visibility. Workbench frame geometry and z-order classify bodies
as fully occluded or visually exposed; partial exposure counts as visible.
While Genie replaces a real node with Canvas output, or scale minimize marks
the node as pending, Workbench excludes that departing node from geometric
occlusion. Covered windows therefore resume presentation during minimize; a
restoring Genie node stays non-occluding until its real node is revealed.
Scale restore, shell frame transitions, and onboarding entry keep the moving
node's own presentation visible while temporarily excluding it as an occluder;
DOM transition and animation completion release that state. Portal-backed
`dialog-popover` nodes sort above default-layer nodes before Workbench applies
normal stack order.
Only fully occluded bodies pause descendant animations and use
`content-visibility: hidden`. Visible Empty-Hero surfaces may own carousel
images, alignment observers, wheel input, and a Three.js/WebGL scene.
Occlusion releases those resources; exposure restores the DOM presentation
immediately and defers WebGL reconstruction until after the reveal interaction
settles. Detail timelines follow the same geometric boundary: fully occluded
surfaces disconnect dock/timeline resize observation and scroll listeners,
while exposure reattaches them and resynchronizes the retained bottom lock.
Elapsed Turn, compaction, subagent, and Goal labels subscribe to one shared
renderer-realm second clock only while their containing presentation is
visible; exposure catches the displayed value up from canonical timestamps.
Focus alone must not stop either behavior because multiple exposed AgentGUI
windows remain live at the same time.
On workspace restore, Desktop mounts the focused AgentGUI body immediately and
hydrates inactive bodies sequentially after browser idle, one animation frame
at a time. Window shells and persisted geometry remain synchronous; this
staging is Desktop presentation work and does not enter engine or Session
lifecycle state.
WebGL scene readiness remains local presentation state; it must not enter
`AgentGUIRuntime`, the workspace engine, or Workbench node state.

The shared Workbench Header owns conversation-identity visibility. When no
Conversation exists, it ignores conversation titles, Agent titles, primary
icons, exact Agent targets, target-information renderers, and fallback icons
even if a host supplies them. When target information is enabled, only the
session icon becomes a no-drag Tooltip trigger; the surrounding title remains
owned by the Header's existing drag and menu behavior.

The reusable tool-sidebar contract lives in
`packages/agent/gui/workbench/tool-sidebar`. Hosts provide the supported panel
catalog and render adapters; the shared component owns tab selection, picker,
sizing, toolbar mechanics, and a structured `AgentToolSidebarHeaderLayout`.
Standalone Desktop registers Side only while the exact external projection
exists, opens the matching source-Session tab, and uses the existing Side width
bounds (`440px` default, `360px` minimum, `600px` maximum). Collapsing the
sidebar retains the Side tab/runtime and releases Side focus; closing the exact
tab invokes the projected close intent. Stream updates notify only the mounted
Side panel, while the sidebar subscribes to a stable identity projection so it
does not rerender for each delta. Other hosts keep explicit panel catalogs and
do not receive Side implicitly.
Hosts may hide the shared toolbar toggle through the explicit
`showToggleButton` presentation input; omission preserves the standard visible
entry. Hiding the entry does not duplicate or override sidebar behavior in the
host.
That layout carries the actions, open state, and reserved width into the one
authoritative `AgentGuiWorkbenchHeader`.

The standalone Files tool reuses the Desktop file-manager pane and its complete
context menu. Its Open With submenu keeps Tutti's file viewer and in-app browser
alongside system applications, default-browser handling, and the system
application picker. Double-clicking a file still delegates to the desktop
host's system-default opener; directories continue to navigate inside Files.

Header ownership is explicit. A native standalone window selects the
window-owned contract, so the shared sidebar composes the Workbench Header and
body frame. An embedded Workbench selects the host-owned contract and projects
the same header layout into its existing Header. The sidebar never creates a
second visible panel Header. Interactive controls stop host drag gestures,
while blank host-owned Header space bubbles to the host drag owner; native
window ownership alone uses Electron app-region dragging.

Header layout is independent from ownership. `overlay` means the Header is
layered above a full-height body, so open tool-panel content reserves the shared
Header height and the Header stacks above `--z-panel`. `stacked` means the host
has already placed the body below the Header and no panel spacer is added.

The package owns one responsive Rail presentation policy for every surface.
`resolveAgentGUIConversationRailPresentation` derives the effective Rail width,
automatic collapse, and combined collapsed state from container width plus the
persisted user preference. Hosts must not supply an alternative breakpoint,
copy Rail dimension constants, or restyle `AgentGuiWorkbenchHeader` to move its
controls. The shared Workbench contribution selects an overlay Header with no
bottom border, and native standalone composition projects that same explicit
window presentation state. Standalone identity remains relevant only to native
window ownership such as Electron drag regions and full-viewport sizing; it is
not a Header layout or separator switch.

## 7. Key flows

### 7.1 New conversation

```text
home composer submit
  -> engine pending activation + optimistic Session/message
     (including the resolved immutable railSectionKey)
  -> Host CreateSession(initial content, clientSubmitId)
  -> provisional runtime + canonical transaction
  -> first Turn accepted
  -> authoritative Session/Turn replaces optimistic projection
```

Initial content is one user-owned submit flow, but provider acceptance is not the prompt's durability boundary. Once the submitted Turn and prompt are durably recorded, a deterministic provider rejection keeps the visible Session, failed Turn, and user prompt so the failure can be rendered as history. Host then discards the startup runtime without publishing canonical completion. AgentGUI may offer provider login for an authentication failure, but it does not offer manual activation retry for failed or canceled Sessions; the user starts a new conversation instead. Restarted Sessions already project their canonical canceled state, so this presentation rule does not require a separate provider-history query. Only a pre-dispatch startup/validation failure may compensate an empty provisional shell; an outcome-unknown delivery keeps its recovery claim instead of guessing whether the provider ran.
The rejected submit claim is terminal and remains bound to that failed Turn, so
replaying the same `clientSubmitId` is an idempotent read of the persisted
failure and never dispatches a second provider Turn.
The initiating composer snapshots Tutti activation plus effect and speed with
that submit. An explicit active or inactive submit snapshot is authoritative
over a later read of mutable home-draft state; non-composer callers may fall
back to the engine draft when no snapshot exists. `capabilityRefs` remain
independent audit provenance and must never substitute for
`initialTuttiModeActivation`.
An activation may instead carry `initialGoalControl`. In that branch the engine
and runtime adapter preserve the structured `{action, objective}` command.
Desktop and Mobile map it to the typed `initialGoalControl` Create field and
send an empty `initialContent`; the daemon delegates that field to Agent Host,
which creates a non-provisional Session and the durable Goal operation without
manufacturing a Turn. Typed initial Goal and non-empty initial content are
mutually exclusive. The structured field is authoritative; integrations must
not reparse the display prompt or forward `/goal ...` as backend command text
to recover Goal semantics. Host retains text parsing only for compatibility
callers that omit the structured field. AgentGUI represents the pending control
and its durable audit with the same client-submit presentation identity, so
canonical replacement does not remove and recreate the visible `goal-control`
row.
Hosts that can observe the durable Goal saga may additionally project the
optional Session `goalSyncState` (`revision`, `syncStatus`, and
`pendingOperationId`, plus optional `executionPending`). It is read evidence
owned by the Host, not Session-owned Goal lifecycle state. AgentGUI uses an
identified `pending`, `applying`, or `unknown` operation while the exact initial
Goal mutation remains pending. After mutation convergence, `synced` retains the
bridge only when the Host explicitly reports `executionPending=true`. The Host
clears that proof on the first canonical Turn with exact Goal provenance or on
terminal, diverged, failed, or non-active Goal evidence. Omission fails closed,
including across mixed-version hosts; AgentGUI never infers future execution
from `synced` alone or uses a UI timeout.
The pending activation carries the same resolved project section key as the
create command. Exact rail projection therefore shows the conversation as soon
as the intent is accepted; it does not wait for provider startup or invent a
temporary catch-all section.
AgentGUI may select that optimistic conversation in mounted UI immediately,
but it must not persist the provisional Session ID into Workbench navigation
state. The selection becomes durable only after the workspace engine confirms
the activation from an authoritative Session snapshot. On restart, absence
from a bounded Rail page is not deletion evidence. A host that proves the
selected Session is absent returns typed `session.not_found`; the activity
engine retains that code, and AgentGUI clears only the matching global and
per-target navigation memories before returning Home. Timeout, transport, and
other reconcile failures preserve the remembered selection.
The controller's new-conversation command must distinguish rail placement from
the active Session's runtime working directory before entering the home
composer. A Session in the Chats section may have a generated `cwd`, but that
path is not a selected user project and must be cleared. A Session in a
canonical project section resolves that section key back to the registered
project root; its runtime `cwd` may instead be a nested directory or isolated
worktree and is never reused as project identity. “Continue in new
conversation” uses the same resolution before moving the mention draft to
Home. A command already on the home composer preserves the user's explicit
project selection. Views only forward new-conversation intent; unresolved
active rail membership fails closed rather than guessing from composer
presentation fields.
For delegated/shared execution, the initiating caller remains the placement
authority: the adapter forwards that caller-selected `RailPlacement` through
the binding to the owner Host. The owner persists the same section key and does
not recompute it from the owner's user-project list.
The Agent CLI handoff adapter also inherits the caller Session's runtime `cwd`
so the delegate starts inside the same checkout or linked worktree. If a
project-backed caller has no runtime `cwd`, its canonical project path is the
fallback. A supplied caller Session ID that cannot be resolved fails the start
instead of creating a detached Session in an allocator directory.

### 7.2 Existing conversation submit

```text
composer submit
  -> engine pending submit / queue
  -> Host SendInput(clientSubmitId)
  -> durable submit claim
  -> provider execution
  -> exact authoritative Turn acknowledgement
  -> event/reconcile confirmation
```

A successful response includes the exact Turn. Clients must not repair a missing Turn by polling, sleeping, or synthesizing an entity.

AgentGUI-generated Prompt `clientSubmitId` values are canonical UUID v4
identities. They are opaque correlation and idempotency values because a host
may promote the same identity into a cross-device or shared-execution command.
Business meaning must not be encoded in or recovered from the UUID. In
particular, Plan feedback records its exact `turnId` and `requestId` in the
pending submit's typed `source`; Message Center reads that source through the
activity-core selector. Activity Core continues to accept caller-supplied
submit identities as opaque strings and does not reinterpret or rewrite them.

### 7.2.1 Existing conversation Goal Control

```text
AgentGUI goal action or structured /goal submit
  -> engine.controlGoal(action, clientSubmitId)
  -> Engine Goal operation + optimistic Goal projection
  -> Desktop or Mobile AgentSessionEffectPort.controlGoal
  -> tuttid HTTP request carrying the same clientSubmitId
  -> Agent Host durable Goal saga
  -> typed Session/Goal/operation result
  -> Engine validates Goal state and applies the returned canonical Session
```

Every admitted action reaches Host, even when the projected Goal already has
the requested value, because Host owns the durable revision, operation, and
audit. A typed response with `pending` or `applying` Goal state is `accepted`;
`synced` is `succeeded`; explicit `failed`, `diverged`, and `unknown` states
remain distinct. Only definitive protocol rejections become frontend
`failed`. Timeout, transport loss, or a malformed typed success remains
`unknown`; generic Session reconciliation does
not prove the outcome of a particular Goal operation. Retrying the same action
from `unknown` reuses its original `clientSubmitId`, so Host resolves the same
durable operation instead of creating a second one. A canonical Session Goal
cannot settle the operation by value equality because it carries no operation
identity. At most one operation record is retained per Session and Session
removal clears it. The package root exposes presentation and settlement
selectors, and the public Engine snapshot contains only their derived state,
not the raw Goal operation ledger. These maps are sparse and update only the
Session IDs whose Goal, Goal operation, or Goal-bearing activation changed, so
Turn streaming and unrelated Session changes preserve the Goal branch and
unaffected presentation references. The response `goal` is Host's durable
desired projection; provider observation remains in Goal state and may be
empty without clearing the visible Goal. Only a durable tombstone produces
`goal: null`. A definitive failure releases the old identity; only an unknown
result retains it for an explicit retry. Goal control enters only through the
workspace Engine; AgentGUI has no parallel runtime callback.

### 7.3 Interaction response

```text
canonical Interaction(pending)
  -> selector projection
  -> inline / Message Center / toast surface
  -> exact interaction response command
  -> Host idempotent transition
  -> answered or superseded projection
```

Every surface shares the exact interaction identity
`(workspaceId, agentSessionId, turnId, requestId)` and submitting state.
Collapsing an ask-user surface back into the conversation is presentation-only:
the canonical Interaction remains `pending`, no response or cancellation is
dispatched, and the mounted answer flow retains its in-memory draft for that
surface. The collapsed surface keeps a visible resume affordance. Hosts expose
this action only when their ordinary Composer can answer the exact pending
Interaction; Side and other prompt-only composers do not infer support from a
full-size layout. In the supported full conversation surface, a question with
structured options does not add a second
free-text answer field; users give a new direction through the ordinary
composer instead. When the active root Turn is waiting on exactly one pending
question whose normalized fields all accept free text, a text-only ordinary
composer submit is converted to the canonical answer payload and sent through
the existing Engine Interaction response operation for that exact Turn and
request. This resolves the provider's pending request so the same Turn can
continue; it does not cancel the Turn, enqueue a second prompt, or branch on
provider names. The composer draft clears only after Engine admits the response
and is restored if the response later fails. Fixed-choice questions and
non-text composer content remain on their existing paths.
Provider request ids remain unchanged and may repeat across Turns; no adapter
may recover a missing Turn by scanning for a session-wide request-id match.
An optional Host interaction-readiness capability may block an owner-dependent
response while preserving the canonical pending Interaction. Synchronizing
uses the existing device-connecting presentation and disables mutation; it is
not a terminal Interaction or Session outcome. Host submission adapters must
recheck their authoritative projection immediately before transport dispatch;
AgentGUI's early check does not replace Host or provider admission.
An interactive provider callback must not block the transport's message reader
while waiting for user input. If the provider can emit follow-up frames during
that wait, the adapter keeps reading and joins them before publishing the
canonical Interaction. When the answer is delivered, local call resolution is
serialized ahead of provider terminal messages caused by that answer.
Codex app-server requests are classified explicitly against the generated
server-request surface. A request being schema-known does not make it a
background request that may be declined silently. Message-only MCP form
elicitations reuse the canonical approval Interaction and preserve the exact
`accept`, `decline`, `cancel`, and advertised persistence semantics in the
app-server response. Field-bearing forms, URL elicitations, and other request
shapes that AgentGUI cannot represent losslessly fail closed before publishing
an Interaction; adapters must not coerce them into a partial approval or
question surface.
When a standard ACP provider bridges a structured question through
one `session/request_permission` as the complete question transaction, one
selected permission option is that bridge's entire response capacity. The
one-shot adapter therefore publishes only an exact single-question,
single-select mapping whose question labels correspond one-to-one with the
provider's non-rejection options. It marks that surface as option-only,
rejects multi-question, multi-select, free-text, duplicate, or
malformed/mismatched shapes before canonical Interaction publication, and
never records them as answered. On submission, only the single scalar value
in `answersByQuestionId` is authoritative; the flat `answers` list is display
data and must not select a provider outcome. The adapter preserves the
accepted canonical answer payload for local projection but translates its
chosen label back to the provider's opaque option ID. The wire response
remains ACP-native (`outcome=selected` plus `optionId`); renderer actions such
as `submit` are not provider outcome values. A provider may model richer
questions as a correlated sequence of permission requests, but Tutti must
implement that sequence as an explicit transaction before publishing the
richer surface; it must not batch answers into request ids that have not
arrived.
Non-DOM hosts such as React Native reuse the pure
`agent-conversation/interactive-answer` entrypoint for canonical ask-user
payload construction and own-property-safe question-id access. Presentation
components remain platform-specific, but they must not copy or reinterpret
this cross-provider answer contract.

A synthesized plan decision uses a durable `plan_decision` operation. A provider-native plan Interaction continues through `interactive_response`. Similar UI does not justify merging their write paths.

### 7.4 Resume

```text
select/open existing Session
  -> engine session reconcile
  -> Host GetSession / EnsureRuntimeSession
  -> canonical state + optional live observation
  -> messages/detail hydration
```

If resume is unavailable, return an explicit state. Do not create a shadow Session.

### 7.5 Conversation actions and copy

```text
rail row More menu / row context menu / workbench header menu
  -> one shared action-group contract (AgentGUIConversationActionsMenu)
  -> rename | copy as reference | copy as Markdown | open window | mark unread
```

All three surfaces render the same action groups; the header dispatches
one discriminated `AgentGuiWorkbenchCommand` protocol and the node resolves the
target session against canonical rail entities under the rail interaction
lock. While either row
menu is open the row keeps its hover layout (short title truncation, actions
visible) so titles cannot overlap the action cluster.
The existing package-owned AgentGUI external-request controller is the only
consumer of Workbench commands. It routes by exact Workbench instance and
executes new-conversation and Session actions directly, without a host hook,
React request state, or sequence projection. Product hosts provide only the
Workbench instance identity and an optional host-owned Rail response callback.
The reusable Workbench node-state source remains the only embedded Rail state
writer; its callback may record a host device preference but must not write the
same node state again. A standalone surface may use the callback as its sole
Rail state writer because it has no Workbench node-state source. The callback
contract contains no Tutti Desktop preference or product policy, so other hosts
such as TSH may persist their own Rail state without adopting Desktop behavior.

Attention state is unread-only: a live completion or explicit user unread
request creates a durable unread completion, and real user exposure removes it.
Absence of an unread completion means read; no separate durable read marker is
authoritative. Historical list/detail reads own canonical content but never
create, remove, or reconcile attention. Hydration restores only
`completed.unreadIds` and `failed.unreadIds`; legacy `readIds` are ignored on
read and every write payload explicitly empties both read buckets so stale read
markers cannot survive migration.

Selection is node-local while attention state is shared. An active Session may
remove unread attention only while its AgentGUI surface is host-focused,
host-visible, and the renderer document is visible and focused. A retained
hidden, occluded, unfocused, or backgrounded node must preserve unread
attention even when its local `activeConversationId` still names the Session.
The read-decision diagnostic records the exact node, completion, host focus,
document exposure, visibility, and decision reason without logging on stream
updates.

Read-only host surfaces reuse the complete workbench header and declare the
session actions they support. Omitting that capability list preserves the full
rename-and-copy menu; a copy-only surface does not render rename or an empty
separator. Hosts that already own a complete canonical message projection may
reuse the pure transcript serializer exported by the `agent-conversation`
entrypoint, while clipboard access, toasts, and session loading remain
host-owned capabilities. Window-level Agent chrome applies only when that Header
is rendered through the Workbench window's own header slot; a complete Header
nested in another host window's body remains ordinary embedded content and must
not alter the outer window's layout or drag layer.

Copy as reference copies the session-mention markdown link the @ panel
produces, so pasting into any composer reconstructs the session chip; it is
synchronous and only requires a writable host clipboard. Copy as Markdown
loads every canonical message page and serializes a lean transcript: user
inputs blockquoted in full, per-turn final agent replies plain, interim
narration collapsed in a `<details>` block; tool payloads (except image
outputs), thinking, `agent_system_notice` messages, and JSON fallbacks are
dropped. The clipboard write is dual-format: `text/plain` keeps short image
references and never carries base64, while `text/html` embeds images as
data URIs hydrated from inline data, the attachment store, and host
`workspace.readFile` — verified empirically: rich-paste targets (Feishu
docs) consume data URIs and re-upload them, but never fetch local paths or
localhost URLs. Images over the per-image embed cap, or with failed reads,
keep the lean reference and surface a toast that counts the omissions and
points at per-image copy. Because history loading and image hydration take
a noticeable moment on long conversations, selecting copy as Markdown opens
one toast immediately (`AgentHostToastApi.loading`): it shows busy with a
spinner and never auto-dismisses, and the handle it returns settles that
same toast in place to success, the omitted-images info tone, or failure —
at which point it starts auto-dismissing like any other toast. This is one
continuous toast, not a loading toast followed by a separate result toast.
Hosts without the `loading` capability get the prior plain info toast
instead, and the result lands as an ordinary second toast.

## 8. Change routing

Answer before editing:

| Question                                                                            | Owner                                                   |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Change when Session/Turn/Goal/operation is created, sent, terminated, or recovered? | `packages/agent/host`; add a conformance scenario first |
| Change canonical phase/outcome/Interaction vocabulary?                              | `store-sqlite/canonical`                                |
| Change an HTTP request/response?                                                    | OpenAPI first, then generated clients                   |
| Change provider wire normalization?                                                 | provider-owned daemon adapter                           |
| Change cross-provider behavior?                                                     | registry descriptor/strategy/capability                 |
| Change frontend async, optimistic, queue, or reconciliation semantics?              | `agent-activity-core` engine                            |
| Change projection, interaction, or loading behavior?                                | focused AgentGUI model/controller                       |
| Change DOM, focus, scroll, or animation?                                            | view/UI-local hook                                      |
| Change Electron, Workbench, OS, file, or window capability?                         | Desktop host adapter                                    |

Diagnose in owner order:

1. Did the canonical command accept and commit?
2. Did Host produce the correct lifecycle result/`CommittedDelta`?
3. Do tuttid events match the authoritative read?
4. Did Desktop reconciliation emit the correct engine intent?
5. Did the engine reducer/selector derive the correct state?
6. Did projection/view render only its input?

Do not start by adding a fallback to the visible component.

### 8.1 Agent settings surface

The desktop settings panel's Agent section has General Settings, Agent Runtime,
and Custom Agents available by default; Automation remains independently
gated. The Agent Runtime tab renders built-in provider rows from the
authoritative identity catalog plus the live `IAgentProviderStatusService`.
Stable Agent Extension maturity is declared separately from Early Access
activation flags, and those rows consume their live `IAgentsService` Targets
and package-provided identity assets rather than becoming built-in provider
descriptors. Its Enable/Disable control reads all Agent Targets from
`IAgentsService` and persists the daemon-owned Agent Target `enabled` field.
Tutti Agent is the built-in exception: its target is always enabled, its row
cannot be disabled, and it has no separate developer visibility switch.
Other disabled targets remain in this settings control plane so they can be
re-enabled, but they are excluded from the AgentGUI agent projection and from
CLI discovery and launch. The device-global provider-rail preferences remain
presentation-only (ordering and optional sidebar personalization); they do not
authorize an Agent Target or replace daemon enablement. Staged
(Beta/Preview/in-progress) rows are gated by the `lab.previewAgents` switch via
the provider-neutral `agentGuiWorkbenchPreviewProviders` predicate; stable
built-in and Agent Extension rows always show in settings and launch surfaces.
Deep links publish the existing
`openWorkspaceSettingsPanel` intent with optional `pane`/`provider`; the
Desktop Settings service is the single adapter that resolves legacy aliases
and current destinations for workspace and standalone windows. An Agent
Runtime destination also bumps `agentFocus` to scroll and briefly highlight the row;
a link to a hidden preview agent surfaces an "enable Preview Agents" hint rather
than failing silently. This is a settings surface, not a second Agent Target
state store.

New Custom Agent drafts derive an untouched display name from the selected
Model Plan and Agent Runtime, joined as `Model Plan - Runtime` when both are
present. Runtime or plan changes may refresh that suggestion only until the
user edits the name; after the first edit, the draft preserves the user's value
across later selection changes. Description, instructions, and call conditions
remain draft fields but are grouped under a collapsed-by-default Advanced
options disclosure.

### 8.2 Deleted-conversation settings surface

Deleted conversations are maintained by a top-level desktop Settings section
immediately before About; they do not belong to the Agent subsection. The page
is scoped to the current Workspace, while its 15/30-day automatic-cleanup
preference is device-global. Its fixed header owns the title-only search,
project filter, retention selector, and destructive “delete all” action so the
controls remain discoverable while the list scrolls.

Each row represents one topmost deleted Session component—a canonical root or
a child whose parent is not deleted—and reuses the two-line Activity View
summary convention: title first, then original project identity and the
pre-delete `updated_at`. The row body is not navigation. Restore and
permanent delete are the only row actions; restore has no confirmation and does
not navigate, while permanent delete uses the ordinary destructive
confirmation. Legacy lossy tombstones explain why restore is unavailable.
“Delete all” ignores search/project filters, confirms against the Workspace
component count with a typed phrase, and remains subject to the daemon idle gate.

The list uses stable cursor paging plus virtual scrolling and automatically
loads near its end. Project options include the unscoped case and original
paths whose project registration has since disappeared. Renderer state may
optimistically remove a row only after a successful restore/purge response; it
does not copy lifecycle semantics out of Host or trigger provider resume. The
canonical restore commit emits `session_restored`; the workspace engine clears
only that Session's deletion tombstone and performs an authoritative detail
reconcile before AgentGUI renders it again. Generic activity events remain
unable to resurrect a deleted Session.

## 9. Folder guide

| Path                                                      | Responsibility                                      |
| --------------------------------------------------------- | --------------------------------------------------- |
| `packages/agent/host/**`                                  | provider-neutral lifecycle application core         |
| `packages/agent/store-sqlite/**`                          | canonical SQLite transactions/repositories          |
| `packages/agent/store-sqlite/canonical/**`                | canonical vocabulary and projection contracts       |
| `packages/agent/daemon/**`                                | provider runtime, registry, wire adapters           |
| `services/tuttid/service/agent/**`                        | Host adapters, queries, HTTP/product preparation    |
| `services/tuttid/api/openapi/tuttid.v1.yaml`              | daemon HTTP contract                                |
| `packages/agent/activity-core/src/engine/**`              | frontend workspace engine                           |
| `packages/agent/gui/agentActivityRuntime.tsx`             | AgentGUI runtime interface                          |
| `packages/agent/gui/agentGUIPerformanceMonitor.ts`        | product-neutral AgentGUI latency correlation        |
| `packages/agent/gui/agent-gui/agentGuiNode/controller/**` | focused controller modules                          |
| `packages/agent/gui/agent-gui/agentGuiNode/model/**`      | pure node projection/policy                         |
| `packages/agent/gui/shared/agentConversation/**`          | reusable transcript projections/components          |
| `packages/agent/gui/agent-message-center/**`              | Message Center projection/presentation              |
| `apps/desktop/**/workspace-agent/**`                      | desktop activity service, adapter, host integration |

## 10. Validation

Follow the repository [Validation Selection](../conventions/testing.md#validation-selection).
The Agent architecture boundary commands available to that workflow are:

```sh
pnpm check:agent-host-boundary
pnpm check:agent-activity-runtime-boundaries
pnpm check:agent-provider-strategy-boundaries
pnpm check:agent-gui-degradation
pnpm check:renderer-boundaries
```

`check:agent-gui-degradation` is executable architecture. Its business-file 800-line limit and budgets for effects, memoization, render-mirror refs, provider branches, timers, component stores, and module globals may only stay level or decrease. Tighten the baseline when a metric drops; never raise it to merge new drift.

Any change to an owner, data flow, public contract, or recurring trap requires documentation impact:

- durable architecture rules update this or an adjacent architecture document
- implementation plans belong in `docs/specs` or `docs/plans`
- symptoms and investigation steps belong in troubleshooting
- historical migration records do not return to this document

## 11. Related documents

- [Agent Activity Packages](./agent-activity-packages.md)
- [Agent Host contracts](../../packages/agent/host/README.md)
- [Agent Extensions](./agent-extensions.md)
- [Provider-native Subagents](../specs/2026-07-15-provider-native-subagents.md)
- [Agent Reference Sources](./agent-reference-sources.md)
- [Agent Reference Mention Resolution](./agent-reference-mention-resolution.md)
- [Desktop Layering](../conventions/desktop-layering.md)
- [Agent Runtime Troubleshooting](../conventions/troubleshooting/agent-runtime.md)
- [Agent GUI Refactor History](./agent-gui-refactor-plan.md)