Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
587 lines
37 KiB
Markdown
587 lines
37 KiB
Markdown
# Agent Approvals And Child Sessions
|
|
|
|
Approval gates, plan exits, provider-native child-session attribution, root
|
|
settlement, cancellation, and Message Center.
|
|
|
|
The canonical child-agent architecture is
|
|
[`2026-07-15-provider-native-subagents.md`](../../specs/2026-07-15-provider-native-subagents.md).
|
|
Do not diagnose current recordings through retired timeline ownership fields or
|
|
session-level child summaries.
|
|
|
|
### External PR review approvals do not refresh gate status
|
|
|
|
- Symptom: an external review is approved, but the gate remains waiting.
|
|
- Check: compare the external review event identity with the persisted
|
|
interaction request and its latest version.
|
|
- Cause: the refresh path updated display data without resolving the canonical
|
|
interaction.
|
|
- Fix: normalize the provider event to the same request identity and commit the
|
|
interaction transition before publishing the activity update.
|
|
- Validate: replay the same event twice and confirm one terminal interaction and
|
|
one stable UI state.
|
|
|
|
### Approval card lacks command or file-change detail
|
|
|
|
- Symptom: a Cursor or Codex approval card shows only a generic title and
|
|
options, without the command or changed-file paths.
|
|
- Check: correlate the approval request with the earlier same-turn tool item.
|
|
Cursor may omit `rawInput` from `session/request_permission`; Codex may send
|
|
`changes` on `item/started` but only the matching `itemId` on
|
|
`item/fileChange/requestApproval`.
|
|
- Cause: a later empty or partial tool update replaced the earlier input, or
|
|
the approval path consulted the root normalizer instead of the exact child
|
|
turn normalizer.
|
|
- Fix: merge partial tool updates into the per-turn snapshot, expose the saved
|
|
input through `KnownToolCallInput`, and pass the exact root or child turn
|
|
normalizer into approval projection. AgentGUI renders structured `changes`
|
|
or `fileChanges`, `grantRoot`, and a standalone `reason`; approval reasons and
|
|
correlated file-change directories render directly below the title without
|
|
duplicate Summary or Path cards, and the title states that the authorization
|
|
is for editing files. Runtime adapters normalize the provider tool kind into
|
|
interaction metadata `approvalPurpose=edit-files`; GUI prompt projection uses
|
|
that semantic purpose and must not infer authorization intent from rendered
|
|
file details. A lone `grantRoot` outside a file-change approval remains a
|
|
labeled path detail. These remain approval previews, not evidence that a file
|
|
change executed.
|
|
- Validate: cover Cursor known-input fallback and Codex root and child
|
|
file-change approvals. When absolute paths share a directory, render that
|
|
directory once and show relative file paths beneath it. Confirm the reason
|
|
and correlated directory appear once below the title.
|
|
- References:
|
|
[acp_turn_normalizer.go](../../../packages/agent/daemon/runtime/acp_turn_normalizer.go)
|
|
[codex_appserver_event_interactive.go](../../../packages/agent/daemon/runtime/codex_appserver_event_interactive.go)
|
|
[interactive_projection.go](../../../packages/agent/daemon/runtime/interactive_projection.go)
|
|
|
|
### Approval controls submit a stale request after restart
|
|
|
|
- Symptom: approve/reject returns that the request is no longer live, while the
|
|
UI still shows it pending.
|
|
- Check: compare the durable interaction tuple
|
|
`(agentSessionId, turnId, requestId)` with the live adapter registry and
|
|
`workspace_agent_runtime_operations`.
|
|
- Cause: startup settlement or a provider terminal resolved the live request,
|
|
but its durable interaction did not transition atomically.
|
|
- Fix: prepare the runtime operation before provider submission; complete the
|
|
interaction, operation, and outbox event in one transaction. Startup recovery
|
|
must process leased operations before settling stale turns.
|
|
- Validate: inject a database failure after provider success and confirm retry
|
|
reaches one terminal operation without submitting the provider response twice.
|
|
|
|
### Approved call remains waiting after the Turn completes
|
|
|
|
- Symptom: the provider accepts an approval and completes the Turn, but the
|
|
historical approval row has no `call.completed` event or an adapter test
|
|
intermittently waits forever for that event.
|
|
- Check: compare the write of the provider response, emission of the matching
|
|
call-resolution event, and handling of the provider's immediate Turn terminal.
|
|
- Cause: provider acknowledgement and call resolution were not serialized with
|
|
Turn finalization. A fast terminal notification closed the event stream before
|
|
the response goroutine emitted `call.completed`.
|
|
- Fix: hold the active Turn processing boundary across the response write and
|
|
call-resolution commit. Let the queued terminal notification finalize only
|
|
after that boundary is released.
|
|
- Validate: use a transport that emits the terminal notification immediately
|
|
after receiving the approval response, then stress the test and assert the
|
|
call-resolution event always precedes the Turn terminal.
|
|
|
|
### Kimi Code split-frame approval or AskUserQuestion lacks detail
|
|
|
|
- Symptom: the Turn says it is waiting for an answer, and the transcript may
|
|
contain an `AskUserQuestion` tool row, but AgentGUI shows no selectable
|
|
question card.
|
|
- For an ordinary approval, the unsafe variant is a selectable card with only a
|
|
generic title and options because the file path or command has not arrived.
|
|
- A second failure can appear after the card is fixed: AgentGUI shows
|
|
`回答:<choice>`, but Kimi's tool output contains `answers: {}` and says the
|
|
user dismissed the question.
|
|
- Check: compare the pending canonical Interaction with the matching tool-call
|
|
message. The broken signature has `kind=question` and
|
|
`tool_name=AskUserQuestion`, but its `input.questions` is absent while the
|
|
same-Turn tool row contains the complete questions and options.
|
|
- For the empty-answer form, inspect the response to
|
|
`session/request_permission`. Kimi expects
|
|
`outcome.outcome=selected` with
|
|
`outcome.optionId=q0_opt_<index>`; a renderer-shaped
|
|
`outcome.outcome=submit` with an answer payload is treated as cancellation.
|
|
- Cause: Kimi Code can send `session/request_permission` with the request
|
|
identity and selectable outcomes before sending the matching `tool_call`
|
|
update with the question body. A synchronous permission handler blocks that
|
|
later frame; publishing the partial Interaction first also makes the missing
|
|
input permanent because pending Interaction input is immutable. After the
|
|
user answers, ACP still requires one of the provider's opaque option IDs;
|
|
canonical GUI answer labels are not themselves a valid permission response.
|
|
- Fix: keep the ACP reader active while the provider waits, correlate the two
|
|
frames by exact Turn and `toolCallId`, and publish `interaction.requested`
|
|
only after the question input is complete. Hide the same incomplete request
|
|
from `SessionState.PendingInteractive`; otherwise session-state reconciliation
|
|
can persist an immutable partial Interaction before the event is ready. Keep
|
|
response delivery and local call resolution ahead of the provider terminal
|
|
caused by that response.
|
|
Apply the same hidden-until-detail rule to ordinary Kimi approvals: never
|
|
publish an actionable approval without display input, never join a different
|
|
Turn or `toolCallId`, and do not use a timer to expose partial state. If no
|
|
matching detail frame arrives, normal Turn cancellation sends ACP
|
|
`session/cancel`, interrupts and removes the pending request, and emits no
|
|
`interaction.requested` or `interaction.superseded` for that hidden request.
|
|
For Kimi Code 0.29.x's one-shot question bridge, require exactly one
|
|
single-select question whose labels map one-to-one to the request's
|
|
non-rejection permission options; mark it option-only and fail the provider
|
|
request for multi-question, multi-select, free-text, malformed, duplicate,
|
|
or mismatched shapes. Preserve the accepted canonical answer payload
|
|
locally, resolve the single scalar `answersByQuestionId[questionId]` value
|
|
against the request's permission options, and send ACP `outcome=selected`
|
|
with the matching `optionId`. Never use the display-oriented flat `answers`
|
|
list as a routing fallback. Do not generalize this one-shot limit to ACP
|
|
providers that emit a correlated sequence of question permission requests;
|
|
those require an explicit multi-request transaction before Tutti may expose
|
|
a richer question surface.
|
|
- Validate: replay permission-before-tool-input ordering, assert exactly one
|
|
question Interaction with the complete question/options, submit an answer,
|
|
assert the provider receives `selected` with the expected opaque option ID,
|
|
and assert `call.completed` precedes the provider Turn terminal. Also replay
|
|
multi-question and multi-select inputs and assert no
|
|
`interaction.requested` is published, plus submit an ambiguous canonical
|
|
answer and assert the Interaction is superseded rather than completed.
|
|
For an ordinary approval, cover matching and mismatched Turn/tool identities,
|
|
preserve a Windows path in the joined input, and cancel a no-update request;
|
|
assert the provider receives `session/cancel`, the pending entry is removed,
|
|
its terminal disposition is interrupted, and neither requested nor
|
|
superseded Interaction is emitted.
|
|
Repeat under the Go race detector.
|
|
- References:
|
|
[acp_pending.go](../../../packages/agent/daemon/runtime/acp_pending.go),
|
|
[standard_acp_turn.go](../../../packages/agent/daemon/runtime/standard_acp_turn.go),
|
|
[standard_acp_stream.go](../../../packages/agent/daemon/runtime/standard_acp_stream.go),
|
|
[standard_acp_events.go](../../../packages/agent/daemon/runtime/standard_acp_events.go)
|
|
|
|
### Claude SDK ExitPlanMode is reported as interrupted after plan completion
|
|
|
|
- Symptom: the plan is visible, but the approval row becomes interrupted or
|
|
the follow-up implementation never starts.
|
|
- Check: distinguish provider-native `ExitPlanMode` interaction from Tutti's
|
|
synthetic plan-implementation decision.
|
|
- Cause: the two paths were treated as one request or a terminal event was
|
|
attributed to the wrong turn.
|
|
- Fix: provider-native exit-plan stays on the exact interaction tuple. Synthetic
|
|
implementation uses its durable plan-decision operation and stable
|
|
`clientSubmitId` reconciliation.
|
|
- Validate: cover both paths independently, including replay after daemon
|
|
restart.
|
|
|
|
### Codex child output appears as the root reply
|
|
|
|
- Symptom: the root answer contains child-only output, or child tools render as
|
|
top-level root rows.
|
|
- Check: correlate app-server `threadId` with the root
|
|
`provider_session_id` and the child session's provider thread handle.
|
|
- Cause: notifications sharing one connection were normalized against the root
|
|
session instead of their registered child thread. The live publication
|
|
boundary can also receive root and child Activity Events in one callback; if
|
|
that mixed batch is projected under the root scope, the business-event bridge
|
|
rejects every child delta and emits a reconcile request for every delta.
|
|
- Fix: unknown foreign threads never mutate the root. A registered child thread
|
|
emits events owned by its child session/turn and carries immutable root and
|
|
parent relations. The Controller groups live projections by canonical
|
|
`AgentSessionID` before publication, and AgentGUI keeps child rows out of the
|
|
root transcript and attaches them under `parentToolCallId`. The business-event
|
|
bridge coalesces concurrent/recent reconcile requests per workspace/session
|
|
while retaining bounded retries.
|
|
- Validate: inject root, known-child, and unknown-thread notifications in one
|
|
run; assert three distinct routing outcomes. Then replay one root plus at
|
|
least three children with high-frequency deltas and assert each scope matches
|
|
its payload and one reconcile request is emitted per throttle window.
|
|
|
|
### Codex subagents ran but AgentGUI shows no child lanes
|
|
|
|
- Symptom: Codex rollout data contains child threads, but the canonical store
|
|
has no child sessions and AgentGUI shows only the root conversation.
|
|
- Check: compare `thread/read(includeTurns=true)` spawn items with
|
|
`workspace_agent_sessions`. A current Codex app-server may report a spawn as
|
|
`subAgentActivity(kind=started, id, agentThreadId)` instead of
|
|
`collabAgentToolCall(tool=spawnAgent, receiverThreadIds)`.
|
|
- Cause: the adapter recognized only one provider-native spawn representation,
|
|
so it persisted neither the parent delegation card nor the child
|
|
Session/Turn. This is an adapter normalization gap, not an AgentGUI lane
|
|
projection bug.
|
|
- Fix: normalize both explicit representations into the same parent call and
|
|
canonical child relation. Keep duplicate notifications idempotent and retain
|
|
the existing post-cancel interrupt boundary.
|
|
- Validate: replay the exact observed item shape; assert parent call plus child
|
|
Session/Turn creation, duplicate suppression, and late-child interruption
|
|
after root cancellation.
|
|
|
|
### Claude SDK child events overwrite or complete the root turn
|
|
|
|
- Symptom: a child result replaces the root answer, the root completes while a
|
|
child is still running, or nested tools appear at root level.
|
|
- Check: inspect `parent_tool_use_id`, child session/turn ids, and the retained
|
|
root provider terminal record. For Claude SDK continuation ordering, filter
|
|
`tuttid.log` by
|
|
`event=agent_session.claude_sdk.lifecycle_event` and the root agent session
|
|
id, then compare the per-session `sequence` values. An
|
|
`sdk_lifecycle_observed` entry records the bounded raw SDK message type and
|
|
subtype before the sidecar projection; the following `task_completed`,
|
|
`turn_started`, and terminal entries record the normalized order. These
|
|
diagnostics intentionally exclude prompt, content, summary, and error text.
|
|
The former failure signature has the final child `task_completed` and SDK
|
|
`task_notification` followed by canonical root settlement/composer unlock,
|
|
then a later root assistant observation and synthetic `turn_started`.
|
|
- Cause: a nested SDK message was treated as root-owned, or SDK
|
|
`turn_completed` was projected directly as canonical root completion.
|
|
- Fix:
|
|
- Create the child session and submitted child turn from the earliest parent
|
|
`Task` tool-use event.
|
|
- Bind `taskId` and `agentId` only as aliases of that recorded child.
|
|
- Keep child messages, tools, interactions, and terminals on the exact child
|
|
session/turn.
|
|
- Normalize SDK root terminal as a root-provider fact. `services/tuttid`
|
|
settles the root only after every nested child turn is terminal.
|
|
- Treat later SDK continuation ids as provider turns attached to the same
|
|
canonical root turn.
|
|
- At the final async-child notification boundary, reserve the synthetic root
|
|
provider turn before emitting the child terminal. The expected normalized
|
|
order is `turn_started` and then `task_completed`; the later root assistant
|
|
confirms that reserved provider turn instead of opening another one.
|
|
- Identify background follow-up results from
|
|
`origin.kind=task-notification`. Do not compare task-notification and result
|
|
counts: the SDK may coalesce queued follow-ups.
|
|
- If the background level or task notifications make continuation pending
|
|
before the ordinary root result, retain the original root Turn until
|
|
session idle. Do not emit `turn_completed(root)` followed by
|
|
`turn_started(synthetic)`: with every child already terminal, durable state
|
|
can settle between those events and must reject the late provider start.
|
|
- Settle normally on `session_state_changed: idle`, after the SDK has flushed
|
|
its held-back result and exited the background-agent loop. Do not start a
|
|
post-result settlement timeout: queued follow-ups may begin several seconds
|
|
apart, so interrupting that wait converts valid work into provider errors.
|
|
- If root output does not begin within 30 seconds, emit the
|
|
`continuation_delayed` warning, complete the reservation with
|
|
`stop_reason=background_agent_continuation_timeout`, interrupt the pending
|
|
SDK query, and drop that continuation's later output. Cancellation disarms
|
|
the same timeout and the pending background-task quiescence timer, and
|
|
preserves the durable canceled outcome.
|
|
- Record a failed or canceled root result in the background-task lifecycle
|
|
owner. A later empty level or task notification may finish child state, but
|
|
must not reserve another synthetic root Turn.
|
|
|
|
Do not infer native SDK order from persisted message timestamps. Use the
|
|
per-session lifecycle sequence to verify that the adapter-established
|
|
provider start precedes the final normalized child terminal and that root
|
|
output either confirms that provider turn or reaches the bounded timeout.
|
|
|
|
- Validate: test both event orders—root terminal before the last child and last
|
|
child before root terminal—plus coalesced notifications/results, session
|
|
idle, delayed idle without early settlement, continuation start, timeout,
|
|
late-output rejection, cancellation during the quiescence grace, late
|
|
empty-level/task-notification signals after root failure, and guidance during
|
|
the reserved window. Confirm that composer availability follows only the
|
|
durable canonical root.
|
|
|
|
### Claude child card shows a generic Agent title and no task detail
|
|
|
|
- Symptom: the child lifecycle is correct, but AgentGUI renders a generic
|
|
`Agent` name and only a last-activity label such as `Bash` or `Read`; the
|
|
delegation description or prompt is missing.
|
|
- Check: compare the earliest `tool_started` payload with the later matching
|
|
`tool_completed` payload, then inspect the persisted child title and the
|
|
parent turn's tool-call row. A healthy completion keeps the full input and
|
|
does not end as `turn_completed_without_call_result`.
|
|
- Cause: Claude may emit a generic start before the full delegation input. If
|
|
the adapter resolves the later completion through the spawned child's own
|
|
alias, it moves that completion from the parent turn into the child turn.
|
|
The parent normalizer then falsely closes the still-open call as missing a
|
|
result, while the child session keeps its early generic title.
|
|
- Fix: keep every lifecycle event for the delegation tool call on its launching
|
|
parent turn; use only an explicit nested `parent_tool_use_id` to select a
|
|
parent child turn. Resolve that same owner before applying the closed-Turn
|
|
fence; checking child aliases first can discard a valid parent completion
|
|
after the child settles. Merge a later real description into the existing
|
|
child session and publish a normal child title update. The compact card may
|
|
still show only the latest child activity, but its name and task strip come
|
|
from canonical child/parent data rather than that activity label.
|
|
- Validate: start with a generic Agent event, finish the same call with a full
|
|
description and prompt, then settle the root provider turn. Assert one
|
|
completed parent call with full input, one updated child title, no synthetic
|
|
missing-result failure, and a child lane containing the expected name/task.
|
|
|
|
### Claude Goal completes while a child is still running
|
|
|
|
- Symptom: Goal shows complete and the SDK root call has returned, but the root
|
|
composer remains busy and the conversation still shows waiting.
|
|
- Check: inspect the three independent facts: Claude Goal metadata, the retained
|
|
root provider terminal, and canonical child turns under the root turn.
|
|
- Expected: `goal=complete`, canonical root `turn=waiting`, and child
|
|
`turn=running` is valid. The SDK must not be held open, and Goal completion
|
|
must not clear the root active-turn reference, unlock the composer, or permit
|
|
a new canonical turn.
|
|
- Fix: keep Goal as provider-native session metadata, normalize Claude
|
|
`turn_completed` as `root_provider_turn_completed`, and let
|
|
`services/tuttid` apply the retained provider outcome when the last child
|
|
becomes terminal. Do not wait for Claude to send a second terminal event.
|
|
- Validate: cover the valid three-state combination, assert the root composer
|
|
remains blocked, then settle only the child and assert the root completes
|
|
without another Claude terminal.
|
|
|
|
### Child approval is stuck or persisted on the root
|
|
|
|
- Symptom: a child approval remains visible or submission reports that the
|
|
request is no longer live. Another form renders and submits correctly, but
|
|
the durable interaction and approval call row belong to the root session and
|
|
turn instead of the child. In a transport-correlation variant, the
|
|
interaction is on the correct child and `interactive_response` remains
|
|
prepared after approval. Its error says the sidecar disposition is unknown.
|
|
In a projection variant, the interaction and operation are already answered,
|
|
but the project-list attention icon remains until the turn settles and the
|
|
runtime log reports `workspace agent session kind is immutable`.
|
|
- Check: confirm the UI action carries the exact child
|
|
`(agentSessionId, turnId, requestId)` tuple. Then verify the child's root
|
|
relation points to the live root provider session. For Claude SDK, also
|
|
inspect the permission callback and sidecar `approval_requested` payload:
|
|
a child callback must carry SDK `agentID` through as provider `agentId`.
|
|
Compare the canonical child turn stored on the interaction with the provider
|
|
`turnId` from that callback and with the `turnId` sent in both
|
|
`submit_interactive` and `interactive_disposition`. If durable state is
|
|
already answered, inspect the resolved event report: its agent session id,
|
|
session kind, root/parent fields, and turn id must consistently describe the
|
|
child. For Codex, correlate the app-server server request's `threadId` and
|
|
`itemId` with the persisted command tool call. If the command is child-owned
|
|
while the Approval row is root-owned, the server-request path bypassed the
|
|
registered child-thread route.
|
|
- Cause: the prompt was aggregated into the root conversation and later
|
|
submitted using the root tuple, or the controller tried to find a separate
|
|
live runtime for the child. Claude-specific root attribution can also happen
|
|
when the sidecar drops the callback `agentID`; the callback still carries the
|
|
current provider/root turn id, which identifies transport lifecycle but not
|
|
the canonical owner of the interaction. Conversely, once ownership is
|
|
correctly scoped to the child, reusing that canonical child turn id as the
|
|
sidecar correlation id makes the sidecar look in the wrong pending-request
|
|
bucket. A separate projection bug occurs when a child-scoping helper writes
|
|
only relation fields but leaves the root agent session id on an acknowledgment
|
|
event; persistence correctly rejects that mixed identity. Codex has the same
|
|
ownership hazard when notifications route by `threadId` but JSON-RPC server
|
|
requests are normalized directly against the active root turn. Its
|
|
`serverRequest/resolved` notification can also strand child pending state if
|
|
child-notification filtering drops it before the shared registry is reached.
|
|
- Fix: `services/tuttid` resolves the durable child relation and supplies both
|
|
root and target identity. The controller locates the shared runtime by root
|
|
session and passes the child target to the adapter. The Claude sidecar
|
|
preserves `agentID`, and the adapter resolves it through the recorded child
|
|
aliases before persisting the interaction. The adapter retains the original
|
|
provider turn id separately and uses it only for sidecar submission and
|
|
disposition queries. Do not register a second mutable child-state authority
|
|
in the controller, infer ownership from the provider turn id alone, or replace
|
|
provider correlation with the canonical child turn. Child event scoping must
|
|
replace the event agent/provider session identity and relation fields as one
|
|
operation, even though the event is delivered through the shared root runtime.
|
|
The Codex adapter applies the registered child-thread lookup to both
|
|
notifications and server requests, stores pending state under the canonical
|
|
child tuple, and resolves provider out-of-band notifications through that
|
|
child target. An unknown non-root request is rejected rather than persisted
|
|
on the root.
|
|
- Validate: keep a focused test where only the root runtime is registered, yet
|
|
the adapter receives the exact child target and the durable child interaction
|
|
becomes answered/superseded. For Claude, cover a child permission callback
|
|
whose `turnId` is the root provider turn and whose `agentId` identifies the
|
|
child; both requested and resolved events must use the child session/turn,
|
|
while initial submit and lost-ack disposition query both retain the provider
|
|
`turnId`. Also cover the acknowledgment path and assert its projected state
|
|
patch and message update are child-owned, so the pending indicator clears
|
|
before the root turn settles. For Codex, request an approval on a registered
|
|
child `threadId`, submit it through the child tuple, and assert both requested
|
|
and resolved events remain child-owned. Separately send
|
|
`serverRequest/resolved` on that thread and assert the child request becomes
|
|
superseded without a root interaction.
|
|
|
|
### Root remains active after all child turns settle
|
|
|
|
- Symptom: child lanes are terminal but the root composer remains busy.
|
|
- Check:
|
|
- root provider terminal row and pending outcome;
|
|
- every child session whose `rootTurnId` equals the active root turn;
|
|
- each child's canonical active/latest turn;
|
|
- root session `active_turn_id`.
|
|
|
|
- Cause: a child terminal did not trigger root-gate evaluation, or a later
|
|
provider continuation opened without publishing its root-provider lifecycle.
|
|
In the Codex adapter, a child can outlive the root Turn. If its terminal
|
|
notification arrives after that root active-Turn emitter is detached, the
|
|
session-level handler must not discard the reduced child event or attach it
|
|
to a newer root Turn's emitter. A newly started client must also refresh the
|
|
live root provider-thread identity before routing that notification; the
|
|
startup Session snapshot predates `thread/start` and may not contain it.
|
|
If provider logs contain `turn/completed` and the controller emits an event,
|
|
but the root turn's persisted root-provider columns are empty, check that the
|
|
runtime reportable-event filter includes both root-provider lifecycle event
|
|
types; stream publication alone does not update durable state.
|
|
- Fix: child terminal, exact child-cancel completion, and root-provider terminal
|
|
transitions all run the same durable root settlement check. The Codex
|
|
session-level handler refreshes the live root provider-thread identity and
|
|
compares each child event's canonical `rootTurnId` with the active root
|
|
Turn. Matching events stay on that Turn's emitter; detached events go through
|
|
the root runtime's Session event sink with an adapter lifecycle snapshot. The
|
|
Controller applies the same commit-before-publish barrier to terminal events
|
|
from that sink, so a child terminal is durable before consumers observe it.
|
|
It does not replay unrelated unowned root events. The final
|
|
transition atomically clears the root active-turn pointer, emits the root turn
|
|
update, and reconciles the controller's root runtime view. Root-provider
|
|
lifecycle events must reach `services/tuttid` through the state-report path.
|
|
- Validate: cover concurrent and nested children, failed children, and a later
|
|
root continuation. Complete the root first and deliver a child terminal
|
|
through the actual session-level transport handler both with no active root
|
|
Turn and while a newer root Turn is active. Assert that the child terminal
|
|
bypasses the newer emitter, reaches the Session event sink, waits for the
|
|
durable report before stream publication, and remains unpublished when that
|
|
report fails. Child failure may remain visible without forcing root failure.
|
|
|
|
### Provider terminal report replays a settled root as running
|
|
|
|
- Symptom: the UI and durable root appear settled, but logs immediately report
|
|
`workspace agent activity turn transition was rejected`. Older summaries may
|
|
misleadingly show `turn=-` on the rejected state patch.
|
|
- Check: inspect the same patch's explicit `Turn`, runtime `TurnLifecycle`, and
|
|
`RootProviderTurn` fields. A provider lifecycle patch may legitimately have
|
|
no explicit canonical `Turn`; it must not inherit a running/waiting lifecycle
|
|
that `services/tuttid` then converts into a turn transition.
|
|
- Cause: persistence-report enrichment copied the controller's runtime
|
|
lifecycle snapshot onto every state patch, while the service treated a bare
|
|
`TurnLifecycle` as a fallback canonical turn fact. A late provider terminal
|
|
could therefore attempt `settled -> running`; SQLite correctly rejected the
|
|
invalid regression and rolled back the report.
|
|
- Fix: persisted event reports receive stable session metadata only. Keep full
|
|
runtime lifecycle enrichment on the live stream, and require an explicit
|
|
structured `Turn` patch for every canonical turn mutation. Do not relax the
|
|
SQLite transition guard. Log summaries should include both
|
|
`turnLifecycle` and `rootProviderTurn` so the two facts are distinguishable.
|
|
- Validate: settle a root, then report a matching provider terminal while the
|
|
controller snapshot still says waiting/running. Assert the provider terminal
|
|
persists, no canonical turn transition is derived, the root stays settled,
|
|
and no transition-rejected error is emitted.
|
|
|
|
### Root cancellation does not stop or settle child turns
|
|
|
|
- Symptom: root stop returns, but one or more child lanes keep running or
|
|
reappear after late provider events. A second form looks correct in the UI,
|
|
but provider logs show a later unowned root `turn/started` or another child
|
|
spawn after the canonical root was canceled. A third form looks correct in
|
|
the UI while `publish runtime operation outbox` retries every second with
|
|
`data.turn.error requires failed or interrupted outcome`. In Claude Code, the
|
|
UI and final rows may both be correctly canceled while a late
|
|
`tool_failed(user_interrupt)` report logs
|
|
`workspace agent activity turn transition was rejected`.
|
|
- Check: inspect the cancel operation payload. It must contain
|
|
`rootAgentSessionId` plus every active canonical target
|
|
`(agentSessionId, turnId)` for that root turn. Also compare the timestamps of
|
|
cancel preparation, late spawn registration, provider `turn/started`, and
|
|
`turn/interrupt`; query for child sessions created after cancel preparation
|
|
and for a settled canonical root whose `root_provider_turn_phase` remains
|
|
`running`. If `confirmed_target_count` includes only a child, inspect the
|
|
provider rollout: a root that continues with another `spawn_agent`, message,
|
|
or `wait_agent` after the canonical cancel did not receive its native
|
|
interrupt even though the UI correctly rendered the durable root as stopped.
|
|
- Cause: the adapter discovered children privately, the controller looked up a
|
|
child as an independent live session, only the root turn committed, or the
|
|
controller canceled its local Exec context before invoking the adapter. The
|
|
last case can unregister the live root provider-turn handle, so child
|
|
interruption succeeds while the root native turn receives no interrupt and
|
|
continues its multi-agent queue behind an already-canceled canonical turn.
|
|
- Fix:
|
|
- `services/tuttid` enumerates the durable tree before provider invocation.
|
|
- Preparing the root cancel operation closes durable child creation for that
|
|
root turn, so a child revealed after the target snapshot cannot race into
|
|
SQLite before cancel completion.
|
|
- The controller finds the live adapter through the root session.
|
|
- The controller invokes the bounded provider cancel before canceling its
|
|
local Exec context. Provider termination uses the still-live native root
|
|
handle; local context cancellation runs afterwards as cleanup even when the
|
|
provider call fails.
|
|
- The adapter maps only supplied targets to provider-native handles.
|
|
- Codex interrupts the root provider turn before waiting for known child
|
|
interrupts, preventing a slow child RPC from leaving the root free to
|
|
launch the next serial child.
|
|
- The provider adapter keeps an execution-local cancellation boundary: late
|
|
unowned root turns and newly revealed native child threads are interrupted,
|
|
and the latter never receive canonical child identities.
|
|
- Claude records the daemon-supplied exact root/child turn targets at that
|
|
boundary before issuing its root-query cancel. A later SDK
|
|
`task_completed(status=stopped)` or `tool_failed(user_interrupt)` for one of
|
|
those child turns is dropped in the adapter instead of being projected as a
|
|
contradictory child failure. Do not match the rejection error text or
|
|
weaken the durable turn state machine.
|
|
- The controller returns the exact provider-acknowledged target subset and
|
|
never settles durable turns itself.
|
|
- Target turn transitions, pending interaction supersession, operation
|
|
completion, and outbox data commit together.
|
|
- Canonical canceled turns clear transport-only errors such as
|
|
`context canceled`; outbound turn projection omits errors unless the
|
|
outcome is `failed` or `interrupted`, so an old dirty row cannot block the
|
|
reliable notification queue.
|
|
- Confirmed cancellations settle `canceled`; targets without terminal
|
|
confirmation settle `interrupted` after the bounded timeout. Late events
|
|
never resurrect the root.
|
|
- A matching late root provider terminal may close the provider lifecycle
|
|
projection on an already settled canonical root, but cannot change its
|
|
canonical canceled outcome or publish another settlement.
|
|
|
|
- Validate: include nested children, a child that finishes during cancellation,
|
|
a provider handle that cannot confirm cancellation, restart recovery, and a
|
|
late child terminal. Also cover a spawn racing after the durable cancel
|
|
operation is prepared and a server-initiated root turn after cancellation.
|
|
For the serial-spawn regression, cancel after the first child appears and
|
|
assert that provider requests include interrupts for both the live root turn
|
|
and that child, the root is provider-confirmed, and any already-in-flight
|
|
second child is interrupted without receiving a canonical session. For
|
|
Claude, also assert that ordinary root-provider-first/child-terminal-later
|
|
ordering still settles the child, while a late cancel-caused child terminal
|
|
emits no second activity transition and produces no rejected-report log.
|
|
|
|
### Claude reply completed but a detached command keeps the turn busy
|
|
|
|
- Symptom: Claude has printed its final answer after starting a long-lived
|
|
`run_in_background` command, while the session rail and composer remain
|
|
loading. The launch tool may end as `turn_completed_without_call_result`.
|
|
- Check: correlate the root `turn_completed` with SDK `task_started` and
|
|
`background_tasks_changed`. If the task has a `tool_use_id` but no subagent
|
|
identity (`agent_id` or explicit agent task type), inspect whether the Host
|
|
created a child session/turn for it or left the launch call running.
|
|
- Cause: generic Claude task-system events were classified as delegated
|
|
subagents. A persistent server therefore became child work whose terminal
|
|
notification might never arrive, so it gated root activity indefinitely.
|
|
- Fix: classify detached processes separately in the Claude sidecar. A
|
|
successful provider result completes a root `run_in_background` launch even
|
|
if `task_started` arrives later; retain the provider task id only for stop
|
|
routing. Do not emit child task lifecycle events or reserve a delegated
|
|
continuation for the process.
|
|
- Validate: cover `task_started` both before and after the successful result,
|
|
leave the process running indefinitely, and assert the launch call and root
|
|
turn complete with no child session, call failure, or synthetic continuation.
|
|
|
|
### Deleted root leaves orphan child sessions
|
|
|
|
- Symptom: a deleted conversation disappears from the rail, but its child
|
|
sessions, turns, or interactions remain in SQLite or later projections.
|
|
- Cause: deletion targeted only the selected session row instead of expanding
|
|
its immutable parent tree.
|
|
- Fix: resolve the selected session and every nested child in the deletion
|
|
transaction and tombstone the full tree with one deletion generation. Keep
|
|
its Turns, Interactions, submit claims, history, and Messages intact for
|
|
restore; terminalize only active work. Remove those rows only during the
|
|
separate permanent-purge transaction.
|
|
- Validate: cover both single-session and batch deletion with a nested child
|
|
tree, assert every descendant receives the same tombstone, restore the exact
|
|
tree atomically, and verify legacy incomplete tombstones fail closed.
|
|
|
|
### Interactive response or exact-turn cancel succeeds but durable state stays pending
|
|
|
|
- Symptom: the provider consumed the response/cancel, while HTTP reports a
|
|
persistence error or durable state remains active.
|
|
- Check: inspect `workspace_agent_runtime_operations` status, lease,
|
|
`next_attempt_at_unix_ms`, payload targets, and its unpublished outbox rows.
|
|
- Cause: provider side effects and SQLite cannot share a transaction; durable
|
|
intent was absent or completion was split across writes.
|
|
- Fix: prepare a deterministic operation, lease it, invoke the provider, then
|
|
commit the domain transitions, completed operation, and outbox rows
|
|
atomically. Recovery requeues old leases before stale-turn settlement.
|
|
- Validate: use a fake clock and failure injection around every boundary. An
|
|
idempotent replay must reach exactly one terminal operation and must not
|
|
revert a terminal interaction or turn.
|