The commands entry's inline comment described the old routing shape
("clients only send a sessionId for a published session") without the
ownership fence that agentFor now applies on every path — the fence's
contract home is the api/commands.ts module JSDoc, so trim the duplicate
and point at the routing shape only, keeping one home per fact.
Explicit-id adoption of a cold session-backed subagent under a *different*
cwd answered `session-conflict` because the cwd check ran before the
persistence inspection classified the identity. The api/commands.ts
contract states explicit-id `session.create` adoption rejects
session-backed subagents with `agent-busy` — ownership is an identity
property, so it must win regardless of the requested workspace.
Reorder the stored-session branch to inspect and classify ownership
first, then enforce the cwd match, making the response match the
documented contract.
When a generic `agentFor` cold resume loses the identity to a parent's
concurrent `enter()` — the collision rejection arrives from
`ctx.agents.resume` publication after the pre-resume re-check — the error
fell through to the `internal` mapping. Clients retrying then see a
transient-looking internal failure instead of the stable ownership error
that `ensureSession`'s `.catch` already produces for the exact same
published-winner case.
Mirror that re-classification in `agentFor`'s resume error path: after the
typed errors, re-check the registry and attached store and answer
`agent-busy` when the raced winner is subagent-owned. Adds a regression
test whose resume mock publishes the subagent winner before throwing the
ID-collision error.
`agentFor` fenced subagent ownership through the attached session store
(`ctx.sessions.get`) and only then returned a live registered agent. A
registered agent whose session is ever absent from the attached store —
an invariant nothing in this package guarantees — would therefore be
handed out through generic Host routing unfenced, bypassing subagent
delivery entirely.
Fence `live.session` directly whenever a live agent exists, and keep the
attached-store check only for the not-live durable classification.
`ensureSession`'s race `.catch` already fences `live.session`; this makes
the fast path the same check instead of an asymmetric weaker one.
`hasSubagentDescriptor` sliced the whole own-suffix events array on every
Agent-bound RPC — including each `session.prompt` and `sessions.models`
call on long transcripts — and `ensureSession` rescans the same suffix
after creation. Replace the slice-then-some with an indexed loop from the
seed boundary, so the classification is a plain O(suffix) read with no
allocation.
A removed session can no longer be the delivery owner of its continuable
children, but the `host/session-removed` handler only reconciled the
removed row's own activity. `parentAvailable` was updated exclusively from
`refreshSubagents` success, and removal schedules no catalog refresh — so
after the parent's Activation detaches, an addressed child kept a writable
editor against a dead continuation owner until an unrelated refresh (or
forever, for a closed menu).
Flip `parentAvailable` to false on the owned catalog and push
`handleSubagentParentAvailable(false)` to every addressed child Session at
removal time, matching the refresh path's notification. New Session
instances already read `parentAvailable` from the catalog, so they inherit
the invalidated state.
Adds a regression test: removing the catalog's owning parent flips the
snapshot's `parentAvailable` and notifies the addressed child instance.
`refreshSubagents` single-flights per catalog owner: a request arriving
while a pull is in flight returns the in-flight promise and is silently
coalesced into it. The in-flight response was requested before the
triggering change, so it can never contain that change — a debounced
membership refresh (50ms after `host/session-added`) firing during a slow
pull therefore lost the new child, and the catalog stayed stale until an
unrelated trigger (reselection, menu reopen, reconnect).
Mark the owner stale on coalescing and re-arm one trailing pull in the
settlement `finally`, so every membership change observed during a pull is
carried by a follow-up refresh exactly once. Bounded: the trailing pull
only runs when a refresh request was actually coalesced, and a new
coalescing during the trailing pull re-marks the same set.
Adds a fake-timer regression test: a `host/session-added` debounce firing
mid-pull yields exactly two `subagent.list` calls and the catalog
eventually contains the new child.
Recheck the listing cancellation signal after each child inspection settles:
a per-child read failing with a diagnostic-mapped code during an abort
previously bypassed the inspection's own checkpoints, letting a cancelled
single-child scan return a successful result.
- listChildren() checks its cancellation signal before starting the corpus
trace and immediately after it resolves, so a pre-aborted or trace-time
abort fails CANCELLED instead of returning a successful empty result.
- Corrected the persistence-repair claims: session query resolves persisted
candidates through the non-mutating inspect() read, so listing is
storage-read-only and a torn child tail is surfaced (shorter valid prefix)
rather than repaired; the Agent Note, README, and JSDoc now state that,
and the zh pair is re-recorded.
- listChildren() takes an optional AbortSignal and rechecks it after every
un-signalled session-query await (the cold-resume cooperative-cancellation
boundary); list_agents forwards exec.signal so the registry's drain of
started tool bodies cannot block on a slow or large catalog.
- The list_agents description now presents running/complete as a stored-record
snapshot and defers deliverability to send_message, matching the ownership-
conflict semantics the service tests pin.
Implements the durable-subagent-catalog RFC: SubagentControlService.listChildren()
enumerates a parent's direct continuable children from one sessionQuery trace,
validates each child's sole subagent/descriptor event (now carrying the durable
creation label), and returns one ordered SubagentListEntry[] with per-child
corrupt/unsupported/unavailable diagnostics. The list_agents tool ships as a
separately loadable plugin of dsh-tool-subagent-control requiring sessionQuery
at load; send_message stays usable without it.
Remove the host-user continuation capability and the public residency query,
then separate the seam's public event payloads from its internal lifecycle
control interfaces.
`followup()` now takes the exact live direct parent `Agent` instead of a
`SubagentAuthority` union. No production adapter ever supplied user authority,
so the `UserAuthorityGrant` brand token existed only to stop a forged
discriminant from bypassing the direct-parent check — deleting the branch
retires the token, its mint method, and that attack surface together.
Narrowing `parent` from `Agent | undefined` to `Agent` removes three special
cases, including the path where a parentless epoch dispatched its lifecycle
events unscoped. Scoped-versus-global dispatch is now decided by the event, not
by whether a caller happened to have a parent.
`activationState()` had no caller; `ActivationState`, `ActivationObserver`, and
`ContinuationHost` are package-private.
New `src/lifecycle.ts` owns the contained emitter, the one-shot run observer,
and the Activation observer, while `SubagentRunInfo`/`SubagentRunEndInfo` move
to `src/types.ts` beside the other consumer-facing contracts. Those payloads are
public API — dsh-jsonrpc, hooks-claude, and the package invariant all consume
them — whereas the observer is a contract between two in-package collaborators,
so they no longer share a home merely for both being lifecycle-shaped. The
service keeps ownership of the scope carrier: `scopeTarget()` composes the
service's own context filter, so a narrowed stand-in would silently change
scope filtering.
Also drops now-unused dsh-tasks-local and dsh-tool-tasks dev dependencies, and
corrects the README claim that a pre-residency failure emits a terminal edge —
that path only ever rethrew.
- Make host-user authority unforgeable. `{ kind: 'user' }` was a bare
discriminant, so any plugin holding `ctx.subagents` — including
model-generated cordis_mount code, which the advanced ACP composition ships
alongside continuable subagents — could construct it and skip the
direct-parent check for any known child id. It now carries an opaque grant
that only SubagentService.userAuthority() mints, which composition hands to
trusted host adapters; a model-facing tool uses parent authority from its own
execution context.
- Reconcile a delivery discarded inside its own admission window. An enqueue
listener that cancels fires the discard before followup() returns, so the
discard listener could not clear an id it had not seen; submit() retained it
and residency stayed `running` until an explicit drain.
- Recheck the caller signal after materialization. An abort landing between
publication and inbox acceptance still submitted the prompt and returned both
ids; it now rolls the child back.
- Stop promising the model transcript access that no shipped continuable config
mounts. The tools now state only that a background child does not report back.
- Restate the implemented note as shipped state rather than a proposal, so it
works as current authority.
Round 1 traded one teardown ordering problem for another. The observer now
splits capture from emission, which satisfies both consumers at once:
- Terminal facts are captured while the child is still registered, so consumers
that resolve it for the child's log and scope still work.
- The edge is emitted only after handle disposal settles, so a rejecting scoped
cleanup is reported as a failed epoch instead of a successful one.
Also:
- Keep the Activation in the map until disposal settles. Removing it first let a
racing followup() see no Activation and cold-resume into the still-registered
agent, and let a concurrent forest drain skip a still-disposing child and
release its parent first.
- Derive terminal telemetry from this epoch's event suffix rather than the whole
session, so a cold resume whose prompt is blocked no longer reports the
previous epoch's answer and turn reason.
- Cancel the ACP bridge's own prompts before awaiting the descendant drain: a
drain can block on persistence, and the top-level agents must not keep running
model and tool work for its whole duration.
All five findings were real:
- The terminal lifecycle edge derived its stop reason from teardown success, so a
child that errored, hit its token ceiling, or was cancelled reported as
completed once its checkpoint and disposal succeeded. It now reads the child's
own last message turn/end, which is authoritative.
- Live delivery never rechecked the caller signal after authorization yielded, so
an abort that won before acceptance still enqueued the message and returned an
id. Admission now re-checks at the boundary that owns the decision.
- Drain flushed before cancelling, letting a running turn keep appending events
the checkpoint could not cover and letting model work continue through a slow
flush. It now cancels to quiescence first.
- subagent/end fired after AgentHandle.dispose() unregistered the child, so the
hooks bridge could not resolve it for the child's cwd and scope. The edge now
publishes while the child is still registered.
- activationState() read Agent.status alone, which stays idle between an accepted
waking send and the microtask that admits it, so a synchronous inbox observer
could see settled with a queued turn. Residency now also counts messages this
manager admitted but has not seen leave the inbox.
Pins that the bridge releases the Activation forest before its own sessions, and
that a failed drain is reported without stranding that teardown. Reads the one
teardown method structurally so the bridge keeps no dependency on the subagent
seam.
A continuable Activation outlives the turn that started it and owns descendant
teardown, so the bridge must drain that forest child-first before releasing the
top-level agents whose runtime the descendants depend on.
Also rewrites the authored continuable snapshot transcript for the Task-free
tool surface; the scenario's keyless replay is still under diagnosis.
Tianyi Cui
imccyu
Dudu-0223