Merge pull request #70 from deepseek-ai/worktree-bash-owner-token

feat(bash): owner token in the executor seam

docs/rfc/README.md

@@ -31,7 +31,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Multiplex concurrent ACP sessions over one connection](proposed/2026-06-14-acp-multi-session.md) | 2026-06-14 |
 | [Optional Code Mode — model writes TypeScript against an SDK of all tools](proposed/2026-06-15-optional-code-mode.md) | 2026-06-15 |
 | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
-| [Agent lifecycle and ownership seams](proposed/2026-06-18-agent-lifecycle-and-ownership-seams.md) | 2026-06-18 |
+| [Unify the agent id and the session id](proposed/2026-06-20-unify-agent-and-session-id.md) | 2026-06-20 |
 
 ## Implemented
 
@@ -61,6 +61,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Real-API e2e in CI against the external DeepSeek API](implemented/2026-06-19-real-api-e2e-ci.md) | 2026-06-19 |
 | [Drop the mutable session summary](implemented/2026-06-19-drop-mutable-session-summary.md) | 2026-06-19 |
 | [Shared persistence write coordinator](implemented/2026-06-18-shared-persistence-write-coordinator.md) | 2026-06-18 |
+| [Agent lifecycle and ownership seams](implemented/2026-06-18-agent-lifecycle-and-ownership-seams.md) | 2026-06-18 |
 
 ## Rejected
 

docs/rfc/implemented/2026-06-18-agent-lifecycle-and-ownership-seams.md

@@ -0,0 +1,42 @@
+# RFC: Agent lifecycle and ownership seams
+
+Status: implemented
+
+## Problem
+
+Several ACP and tool-bash limitations were symptoms of the same missing seam: plugins could create or resume agents through `ctx.agents`, but they could not own and dispose one agent independently, and long-running bash tasks carried no stable owner in the executor itself. ACP aborted and awaited agents on disconnect but could not unregister just that session's agent; `session/cancel` could not cancel queued-but-not-yet-started work; and `tool-bash` kept task ownership in a plugin-local `Map`, so an HMR reload could make an old task look unowned.
+
+## What was implemented
+
+The three seams shipped across a stacked chain of PRs (the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token), each converged independently.
+
+### 1. Queue-aware `Agent.cancel(reason?)`
+
+A new `cancel()` verb on the `Agent` interface (distinct from the narrower step-only `abort()`). It clears the inbox's queued + steering FIFOs, aborts the in-flight step if any, and drives a **turn-scoped cancellation marker** the driver loop checks at every turn-decision point — so a prompt that is queued-but-not-yet-started never runs, a cancel landing in the pre-step / continuation window drops the about-to-run turn (ending it `aborted`), and a later prompt cannot be batched into the cancelled turn. `whenIdle()` reaches post-cancel quiescence. ACP `session/cancel` maps to `cancel()`. The marker is armed ONLY when there is something to cancel, so an idle no-op cancel cannot strand the next prompt.
+
+### 2. `AgentHandle` async disposer
+
+`ctx.agents.create`/`resume` (and the `AgentFactory` interface) return `AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear down exactly this agent: stop its loop, `await` the loop's exit (true quiescence, not just the `disposed` status flip), unregister it, and remove its session from the store. `ctx.agents.get(id)` still returns a bare `Agent`. Config-created agents stay owned by the `AgentLoop` fiber (the handle is discarded). ACP holds each session's disposer in its `SessionRecord` and runs it on disconnect/teardown, so a bare client disconnect leaves no registered agent and no session-store entry — even when `session/load` races teardown (the just-resumed handle is disposed before the closed-guard throw).
+
+**Teardown ORDER is load-bearing for durability**, and the implementation folds the session lifecycle into the agent's SINGLE composite cordis effect (`SessionStore.prepare`/`enter`/`announce`, replacing a sibling-effect split). A fiber unload disposes sibling effects concurrently (`Promise.all`), which would race the session's `onAppend` detach against the loop's closing `session/flush` and drop the closing `turn/end`; inside one effect the disposers run as an ordered LIFO chain (loop stopped + `await agent.done` BEFORE the session detaches), so the loop's final flush is captured on BOTH the handle's `dispose()` and a fiber unload. The register disposer's `agent/disposed` emit is contained (a throwing listener must not reject the chain and skip the later session detach).
+
+### 3. Bash owner token in the seam
+
+Background-task ownership moved from a `tool-bash` plugin-local `Map<string, Agent>` into the executor. `BashExecRequest` gains an optional `owner?: string`; the resolved `BashExecSpec` carries it as required-but-nullable `owner: string | undefined` (a forgotten owner is a visible `undefined`, never a silently-absent property). The executor stores the token on its task and exposes it via a new `BashExecutor.ownerOf(id): string | undefined` seam (NOT on the public `BashTask` — one read path, no redundant API). `tool-bash` deletes its `Map` entirely: it stamps `exec.agent?.session.header.id` as the owner at `start`, and `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token with `!== undefined` semantics (an empty-string token is still a real owner). The completion notice finds the live agent by scanning `ctx.get('agents')?.list()` for `agent.session.header.id === ownerToken` (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, where the `ctx.agents` proxy would throw). Because ownership now lives on the task in the executor (disposed with the `dsh-bash` fiber), it SURVIVES a `tool-bash` HMR reload — closing the old `XXX(tool-bash-owner-hmr)` gap. (The `onTaskDone` listener is still effect-scoped to `tool-bash`'s `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+
+## Acceptance Criteria (met)
+
+- ACP disconnect/session close leaves no registered agent AND no session-store entry for that session, even when `session/load` races teardown.
+- `session/cancel` before a queued prompt starts prevents that prompt from running and cannot batch the next prompt into the cancelled turn.
+- A `tool-bash` HMR reload does NOT make an existing background task readable or killable by a different session (ownership survives on the executor).
+- Existing non-ACP demos still work without managing handles explicitly; config-created agents remain owned by the `AgentLoop` plugin fiber.
+
+## Seam precondition (recorded)
+
+The bash owner-token comparison relies on `session.header.id` being unique among live agents. The agent registry does NOT enforce this — it rejects a duplicate *agentId*, not a duplicate session id, and `createAgent` accepts an arbitrary `sessionId`. This is NOT reachable via ACP (UUID sessionId, `agentId === sessionId`, duplicate-load rejected), so it is not a live product hole, but a programmatic caller that registers two agents with the same session id would break bash isolation and mis-route the completion notice. The access *policy* (token comparison) stays in `tool-bash` (the consumer); the bash seam stores only an opaque `owner` string and never interprets it — the correct interface/impl/consumer split.
+
+The planned resolution is to remove the precondition by construction — see [unify the agent id and the session id](../proposed/2026-06-20-unify-agent-and-session-id.md): once an agent IS its session (one id), the registry's existing unique-`agentId` check is a unique-session-id guarantee and no two live agents can share a session token.
+
+## Notes
+
+This touched public interfaces (`Agent`, `AgentFactory`, the bash seam) deliberately, not as a local ACP patch. The simple synchronous `Agent.send()` ergonomics were preserved; the async lifecycle path is additive, for owners that need it.

docs/rfc/proposed/2026-06-14-acp-multi-session.md

@@ -3,13 +3,13 @@
 Status: proposed
 
 <!-- XXX: legacy ADR/RFC body format, not yet normalized to a unified RFC template. -->
-> **Implementation status:** the multi-session bridge (steps 1, 3, 4) and the bash task-ownership isolation are implemented in `packages/acp` + `packages/tool-bash`. **Per-session *permission* ownership is deferred** — it depends on [the ACP support permission gate](2026-06-14-acp-agent-client-protocol.md) (`TODO(rfc010-permission-gate)`), which is itself deferred; the `agent→sessionId` reverse map the gate will route through is in place. Step 2's per-session disposer scope is now implemented (see [agent lifecycle & ownership seams](2026-06-18-agent-lifecycle-and-ownership-seams.md)): the factory returns a per-agent `AgentHandle` whose `dispose()` stops the loop, awaits quiescence, unregisters the agent, and removes its session, so a bare client disconnect leaves no registered agent or session-store entry. Status stays `proposed` until per-session permission ownership lands.
+> **Implementation status:** the multi-session bridge (steps 1, 3, 4) and the bash task-ownership isolation are implemented in `packages/acp` + `packages/tool-bash`. **Per-session *permission* ownership is deferred** — it depends on [the ACP support permission gate](2026-06-14-acp-agent-client-protocol.md) (`TODO(rfc010-permission-gate)`), which is itself deferred; the `agent→sessionId` reverse map the gate will route through is in place. Step 2's per-session disposer scope is now implemented (see [agent lifecycle & ownership seams](../implemented/2026-06-18-agent-lifecycle-and-ownership-seams.md)): the factory returns a per-agent `AgentHandle` whose `dispose()` stops the loop, awaits quiescence, unregisters the agent, and removes its session, so a bare client disconnect leaves no registered agent or session-store entry. Status stays `proposed` until per-session permission ownership lands.
 
 ## Problem
 
 [ACP support](2026-06-14-acp-agent-client-protocol.md) ships with a single active session per connection: a second `session/new` is rejected. Editors expect to run several conversations over one agent subprocess — a user opens multiple threads, or a client pre-warms sessions. The single-session guard is a deliberate MVP scope cut, not an architectural limit; this RFC lifts it.
 
-This paragraph is historical: the multi-session bridge has landed. The remaining proposed work is per-session permission ownership plus the lifecycle seams now tracked in [agent lifecycle and ownership seams](2026-06-18-agent-lifecycle-and-ownership-seams.md).
+This paragraph is historical: the multi-session bridge has landed. The remaining proposed work is per-session permission ownership plus the lifecycle seams now tracked in [agent lifecycle and ownership seams](../implemented/2026-06-18-agent-lifecycle-and-ownership-seams.md).
 
 ## Proposal
 

docs/rfc/proposed/2026-06-18-agent-lifecycle-and-ownership-seams.md

@@ -1,26 +0,0 @@
-# RFC: Agent lifecycle and ownership seams
-
-Status: proposed
-
-## Problem
-
-Several ACP and tool-bash limitations are symptoms of the same missing seam: plugins can create or resume agents through `ctx.agents`, but they cannot own and dispose one agent independently, and long-running bash tasks carry no stable owner in the executor itself. ACP currently aborts and awaits agents on disconnect, but cannot unregister just that session's agent; `session/cancel` cannot cancel queued-but-not-yet-started work; and `tool-bash` keeps task ownership in a plugin-local `Map`, so an HMR reload can make an old task look unowned.
-
-## Proposal
-
-Add explicit lifecycle ownership to the agent factory and explicit ownership metadata to background tasks.
-
-1. `ctx.agents.create/resume` should return an `AgentHandle` (or add an adjacent method) that exposes the `Agent` plus an async disposer. The disposer unregisters the agent, aborts queued/running work, and resolves only when the driver loop reaches quiescence.
-2. Add a queue-aware cancel primitive to the `Agent` interface. It must clear queued work that has not started, abort the current step if one exists, and make `whenIdle()` wait for the post-cancel quiescent state. ACP `session/cancel` and bridge teardown then become honest cancellation, not best-effort pre-step cancellation.
-3. Move background task ownership into the bash seam. `BashExecSpec` or `BashTask` should carry a stable owner token, preferably the session id rather than the `Agent` object identity. `bash_output`/`bash_kill` then ask the executor for ownership rather than relying on a `tool-bash` instance-local map.
-
-## Acceptance Criteria
-
-- ACP disconnect/session close leaves no registered agent for that session, even when `session/load` races teardown.
-- `session/cancel` before a queued prompt starts prevents that prompt from running and cannot batch the next prompt into the cancelled turn.
-- A `tool-bash` HMR reload does not make an existing background task readable or killable by a different session.
-- Existing non-ACP demos still work without managing handles explicitly; config-created agents remain owned by the `AgentLoop` plugin fiber.
-
-## Risks
-
-This touches public interfaces (`Agent`, `AgentFactory`, and the bash seam), so it should not be smuggled into a local ACP patch. The compatibility trap is preserving the simple synchronous `Agent.send()` ergonomics while adding a robust async lifecycle path for owners that need it.

docs/rfc/proposed/2026-06-20-unify-agent-and-session-id.md

@@ -0,0 +1,57 @@
+# RFC: Unify the agent id and the session id
+
+Status: proposed
+
+## Problem
+
+The agent factory carries TWO ids for what is, in every live consumer, one thing:
+
+- `agentId` — the `AgentRegistry` handle (the actor identity; the registry rejects a duplicate).
+- `sessionId` — the event-sourced session / persisted-log identity (`session.header.id`).
+
+`CreateAgentOptions` takes both separately; `ResumeAgentOptions` takes an `agentId` plus a `resumeSessionId`. They diverge in exactly two places:
+
+- **Config-driven create** (`AgentLoop.create`): a stable `agentId` (e.g. `"echo"`) with a fresh per-run `sessionId` (`${id}-session-<uuid>`).
+- **Resume**: a caller-supplied `agentId` (e.g. `"main"`) on a persisted `resumeSessionId`.
+
+Everywhere a live consumer actually looks an agent up — the **ACP bridge, the only production path** — the two are already unified: `agentId === sessionId === <uuid>`.
+
+The separation is **latent generality no consumer exercises**: nothing reads a *stable* `agentId` back across runs (each process starts fresh, and persistence keys off the session id, never the agent id). The config path's "stable agentId, fresh sessionId" buys nothing concrete — it is cosmetic. And the `agentId !== sessionId` case is precisely what opens the bash owner-token alias hole: the bash completion-notice routes by `session.header.id`, but the registry enforces uniqueness only on `agentId`, so a programmatic caller registering two agents with different agent ids but the SAME session id can mis-route a notice (see [agent lifecycle and ownership seams](../implemented/2026-06-18-agent-lifecycle-and-ownership-seams.md) § Seam precondition). The current code documents this as a precondition rather than guaranteeing it.
+
+## Proposal
+
+Make an agent BE its session: one id. An agent's registry handle IS its `session.header.id`.
+
+- `CreateAgentOptions` drops the separate `sessionId` — the single `id` is both the registry handle and the live/persisted session id. (ACP already passes the same UUID for both, so its call site simplifies to one field.)
+- `ResumeAgentOptions` drops the separate `agentId` — resuming `sessionId` X registers the agent under id X. (ACP already does this.)
+- The config path (`AgentLoop.create`) uses its configured `id` directly as the session id, applying whatever resume-or-create policy it adopts (today it appends a per-run uuid to avoid colliding with an on-disk log; that policy moves onto the single id, e.g. the config id IS the session and a durable backend resumes it — to be settled in the implementing PR).
+- The registry's existing unique-`agentId` check becomes, by construction, a unique-session-id guarantee — the bash alias hole is closed with NO new defensive invariant: two agents cannot share a session id because the session id is the agent id.
+
+## Why not just enforce session-id uniqueness in `AgentRegistry.register()`?
+
+That was the review's first suggestion. It would couple the generic registry to a session-uniqueness assumption (the registry tracks *agents*, not sessions) and entrench the very separation this RFC removes. Unifying the ids closes the hole more cleanly — there is nothing left to enforce.
+
+## Acceptance criteria
+
+- `ctx.agents.create`/`resume` take a single id; the ACP bridge passes one id.
+- The config-driven agent path has a deliberate, documented session-id policy (no silent per-run id divergence that no consumer reads).
+- The bash owner-token alias hole is gone by construction (no two live agents can share a session id).
+- All existing behavior the tests pin (ACP create/resume/load, config startup, durability) still holds — or the tests change WITH the behavior where the divergence was an artifact (per AGENTS.md "tests document behavior, not golden truth").
+
+## Risks
+
+This touches public factory interfaces (`CreateAgentOptions`, `ResumeAgentOptions`, `AgentFactory`) and the config-agent id scheme, so it is a deliberate cross-package change, not a local patch — it ships as its own PR (converged with Codex), stacked on the bash owner-token work that surfaced the precondition.
+
+The genuine risks of collapsing the two ids into one (the case AGAINST this proposal — to be weighed honestly before implementing):
+
+- **It forecloses a one-agent-resumes-many-sessions / one-session-driven-by-many-agents future.** Today the separate ids leave room for an agent (a stable actor) to detach from one session and attach to another, or for a handoff where a new agent process adopts an existing session under a new actor handle. Unifying makes "agent" and "session" the same lifetime, so any such future needs a NEW seam (e.g. an explicit `actorId` distinct from the session) — re-introducing the very separation we removed. We judge this generality currently unused, but it is a door this change closes.
+
+- **Sub-agents / fork / spawn (an explicitly deferred seam) may WANT a stable actor id across forked sessions.** `AgentLoop.create`'s `TODO(sub-agents)` envisions a child agent seeded from a parent's event log. If the design wants "the same agent identity across a fork" (parent and child share an actor but have distinct session logs), a unified id blocks it. The implementing PR must check the intended fork/spawn model BEFORE unifying, or accept that fork always mints a fresh combined id.
+
+- **The config-driven resume-or-create policy becomes load-bearing, not cosmetic.** Today the per-run-uuid session id quietly sidesteps the "a fixed id collides with its own on-disk log on the second run" problem. Once the id is unified and stable, a config agent restarting MUST decide resume-vs-fresh deliberately — there is no longer a throwaway session id to hide behind. Getting this wrong reintroduces the create-collision the uuid was avoiding (a durable backend refuses to re-create an id whose log exists). This is the one real design decision the implementing PR owns, and it is easy to get subtly wrong.
+
+- **Persisted/on-disk identity becomes the agent identity.** Unifying means the registry handle is now a persisted, externally-meaningful string (a session id a client chose), not an internal label. A caller that previously used a short human label (`"main"`) as the agent id now must use the session id. This is fine for ACP (already a UUID) but is a semantic narrowing for any programmatic embedder that relied on naming its agents independently of session storage.
+
+- **Migration churn touches every create/resume call site and its tests.** `CreateAgentOptions`/`ResumeAgentOptions` shape changes ripple to ACP, the config path, the agent-loop factory, and ~dozens of test fixtures that currently pass distinct `agentId`/`sessionId` (some deliberately distinct to exercise the divergence — those tests change WITH the behavior, per AGENTS.md "tests document behavior, not golden truth"). The risk is mechanical but broad; a missed call site is a type error, but a missed *test* could silently lose coverage of a path.
+
+The one real design question the implementing PR must settle first is the config-driven resume-or-create policy once the id is unified (today's per-run-uuid behavior is a demo simplification already flagged `TODO(demo)`). If, on closer look, the fork/spawn or multi-session-actor futures turn out to be wanted, this RFC should be REJECTED in favor of the lighter "enforce session-id uniqueness in the registry" guard — the alias hole is not reachable via ACP, so keeping the ids separate and merely documenting (or mechanically enforcing) the precondition remains a valid alternative.

packages/acp/README.md

@@ -34,7 +34,7 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline `
 
 The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map<sessionId, SessionRecord>` (forward) with a `WeakMap<Agent, sessionId>` reverse map so `agent/*` events — which carry only the `Agent` — demux in O(1). Every `session/event` and `agent/status` is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. (Per-session *permission* ownership is reserved for the deferred permission gate — `TODO(rfc010-permission-gate)`.)
 
-Background-task isolation rides on `dsh-tool-bash`: bash task ids are global and predictable, so the tool layer records each background task's owning agent and `bash_output`/`bash_kill` reject a task owned by a different agent — one session's agent can't read or kill another's task.
+Background-task isolation rides on `dsh-tool-bash`: bash task ids are global and predictable, so each task carries an opaque owner token — the owning agent's `session.header.id` — stored on the task inside the executor (`dsh-bash`'s `ownerOf(id)` seam). `bash_output`/`bash_kill` reject a task whose token differs from the caller's session token, so one session's agent can't read or kill another's task. Ownership is by session TOKEN, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the token lives on the executor's task it survives a `tool-bash` HMR reload.
 
 ## Per-session cwd
 

packages/bash-local/README.md

@@ -22,7 +22,7 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 - **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after a 3s grace (OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
 - **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
 - **Model-friendly env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results.
-- **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything.
+- **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything. The spec's opaque `owner` token is stored on the tracked task and returned by `ownerOf(id)` — the executor never interprets it (the consumer's access policy does), and because it lives with the task here it survives a `tool-bash` HMR reload.
 
 ## Sandboxing
 

packages/bash-local/src/index.ts

@@ -49,6 +49,8 @@ interface TrackedTask extends BashTask {
   /** Whole-stream byte offsets already delivered via {@link LocalBashExecutor.readOutput}. */
   stdoutOffset: number
   stderrOffset: number
+  /** Opaque owner token from the {@link BashExecSpec} (the consumer's isolation key). */
+  owner: string | undefined
 }
 
 /**
@@ -114,6 +116,9 @@ export class LocalBashExecutor extends BashExecutor {
       workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
       timeoutMs,
       ...request.signal ? { signal: request.signal } : {},
+      // Carry the owner through verbatim (required-but-nullable on the spec):
+      // the executor never interprets it — the consumer's access policy does.
+      owner: request.owner,
     }
   }
 
@@ -149,6 +154,7 @@ export class LocalBashExecutor extends BashExecutor {
       status: 'running',
       exitCode: null,
       signal: null,
+      owner: spec.owner,
       running,
       stdoutOffset: 0,
       stderrOffset: 0,
@@ -174,6 +180,12 @@ export class LocalBashExecutor extends BashExecutor {
     return this.tasks.get(id)
   }
 
+  ownerOf(id: string): string | undefined {
+    // Unknown id and known-but-ownerless both read as undefined — the consumer
+    // treats undefined as "open" and a truly unknown id fails at readOutput/kill.
+    return this.tasks.get(id)?.owner
+  }
+
   list(): BashTask[] {
     return [...this.tasks.values()]
   }

packages/bash/README.md

@@ -19,6 +19,7 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su
 | `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `BashRunResult`. |
 | `start(spec)` | Background execution. Returns a `BashTask` handle immediately; **no timeout applies** (stop tasks via `kill`). |
 | `get(id)` / `list()` | Task lookup. |
+| `ownerOf(id)` | The opaque OWNER token recorded for a background task at `start` (from the spec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores/returns it verbatim and NEVER interprets it — the access POLICY lives in the consumer (`dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Storing ownership here (disposed with the executor's fiber) is what makes it survive a consumer HMR reload. |
 | `readOutput(id)` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. Throws for unknown ids. |
 | `kill(id)` | Kill a running task. Returns `false` when it already finished; throws for unknown ids. |
 | `onTaskDone(listener)` | Completion listener (effect-based, disposer returned). Fires exactly once per task; never after the service is disposed. |
@@ -27,4 +28,4 @@ Implementations subclass `BashExecutor`, implement the abstract methods, and cal
 
 ## Vocabulary
 
-`BashExecRequest` (command, workdir?, timeoutMs?, signal?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?) before execution; `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. See `src/types.ts` for the full contracts.
+`BashExecRequest` (command, workdir?, timeoutMs?, signal?, owner?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, owner) before execution; `owner` is optional on the request and **required-but-nullable** (`string | undefined`) on the resolved spec, so a forgotten owner is a visible `undefined` rather than a silently-absent property. `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. See `src/types.ts` for the full contracts.

packages/bash/src/index.ts

@@ -88,6 +88,21 @@ export abstract class BashExecutor extends Service {
   /** Look up a background task by id. */
   abstract get(id: string): BashTask | undefined
 
+  /**
+   * The opaque OWNER token recorded for a background task at {@link start}
+   * (from the {@link BashExecSpec}'s `owner`), or `undefined` for an unknown id
+   * OR a known-but-ownerless task. The executor stores and returns the token
+   * verbatim — it never interprets it; the access POLICY (who may read/kill a
+   * task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares
+   * `ownerOf(id)` to the caller's token. Collapsing unknown-id and
+   * known-but-unowned into the same `undefined` is fine: the consumer's access
+   * gate treats `undefined` as "open", and a genuinely unknown id then fails
+   * loudly at the subsequent {@link readOutput}/{@link kill} ("unknown task").
+   * Storing ownership in the executor (disposed with ITS fiber) — not in the
+   * tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
+   */
+  abstract ownerOf(id: string): string | undefined
+
   /** All tracked background tasks (insertion order). */
   abstract list(): BashTask[]
 

packages/bash/src/types.ts

@@ -20,6 +20,15 @@ export interface BashExecRequest {
   timeoutMs?: number | undefined
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
+  /**
+   * Opaque OWNER token for a background task — the consumer's isolation key
+   * (the tool layer passes the owning agent's `session.header.id`). The
+   * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
+   * the executor itself NEVER interprets it (no access policy lives in the
+   * seam — that is the consumer's job). Absent for foreground runs and for an
+   * ownerless background start (a non-agent caller).
+   */
+  owner?: string | undefined
 }
 
 /**
@@ -36,6 +45,15 @@ export interface BashExecSpec {
   timeoutMs: number
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
+  /**
+   * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
+   * being required on the resolved spec): {@link BashExecutor.resolve} carries
+   * the request's `owner` through, defaulting a missing one to `undefined`. A
+   * required field makes a forgotten owner a VISIBLE `undefined` rather than a
+   * silently-absent property that yields an unowned (cross-session-readable)
+   * task. `start()` stores it; `run()` (foreground) ignores it.
+   */
+  owner: string | undefined
 }
 
 /** One captured stream: the (possibly truncated) text plus recovery info. */

packages/bash/tests/service.spec.ts

@@ -6,6 +6,7 @@ import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRe
 /** Minimal concrete executor: records calls, lets tests drive completions. */
 class StubExecutor extends BashExecutor {
   tasks = new Map<string, BashTask>()
+  private owners = new Map<string, string | undefined>()
 
   resolve(request: BashExecRequest): BashExecSpec {
     return {
@@ -13,6 +14,7 @@ class StubExecutor extends BashExecutor {
       workdir: request.workdir ?? '/stub',
       timeoutMs: request.timeoutMs ?? 1000,
       ...request.signal ? { signal: request.signal } : {},
+      owner: request.owner,
     }
   }
 
@@ -38,6 +40,7 @@ class StubExecutor extends BashExecutor {
       done: Promise.resolve(),
     }
     this.tasks.set(task.id, task)
+    this.owners.set(task.id, spec.owner)
     return task
   }
 
@@ -45,6 +48,10 @@ class StubExecutor extends BashExecutor {
     return this.tasks.get(id)
   }
 
+  ownerOf(id: string): string | undefined {
+    return this.owners.get(id)
+  }
+
   list(): BashTask[] {
     return [...this.tasks.values()]
   }

packages/tool-bash/README.md

@@ -30,7 +30,7 @@ Result text: stdout, then a `[stderr]` section, then status markers — `[timed
 
 ### Task ownership (cross-session isolation)
 
-The owning agent is recorded per task id at spawn and kept for the lifetime of the loaded plugin instance (it is **not** cleared on completion). `bash_output`/`bash_kill` reject a task owned by a *different* agent with `task <id> belongs to another session` (a task started with no agent — a non-loop caller — has no owner and is open to anyone; a call with no `exec.agent` cannot access an owned task). Task ids are global and predictable, so under multi-session ACP this ownership check is the fence that stops one session's agent from reading or killing another session's background task. (`XXX(tool-bash-owner-hmr)`: an independent HMR reload of this plugin starts a fresh map, so a task spawned before the reload becomes un-owned — acceptable as HMR is dev-only and the session boundary is one user's cooperative editor; a durable fix attaches ownership to the executor/task lifetime.)
+The owning agent's session token (`session.header.id`) is stamped onto the task at spawn — passed to the executor via `resolve({ …, owner })` and stored ON THE TASK inside the executor (the `dsh-bash` `ownerOf(id)` seam), **not** in a plugin-local map. `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token (`session.header.id`) with `!== undefined` semantics and reject a task owned by a *different* session with `task <id> belongs to another session` (a task started with no agent — a non-loop caller — has no owner token and is open to anyone; a call with no `exec.agent` cannot access an owned task). Task ids are global and predictable, so under multi-session ACP this token check is the fence that stops one session's agent from reading or killing another session's background task. Because ownership lives on the task in the executor (disposed with the `dsh-bash` fiber), it **survives an independent `tool-bash` HMR reload** — closing the old plugin-local-map gap where a reload orphaned pre-reload tasks. (The `onTaskDone` listener is still effect-scoped to this plugin's `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
 
 ## UI presentation
 
@@ -38,7 +38,7 @@ These tools own how their calls render in a UI (an editor's tool-call card) via
 
 ## Background completion notices
 
-When a background task finishes, a short notice is injected into the owning agent's session (`agent.inject()`, source `{kind: 'plugin', plugin: 'tool-bash'}`). Injection is **durable context for the next model request, not a wake-up** — an idle agent stays idle until something sends a message. That's why the tool descriptions tell the model to poll with `bash_output`.
+When a background task finishes, a short notice is injected into the owning agent's session (`agent.inject()`, source `{kind: 'plugin', plugin: 'tool-bash'}`). The owning agent is found by its session token: the listener reads `ctx.bash.ownerOf(task.id)` and scans `ctx.get('agents')?.list()` for an agent whose `session.header.id` matches (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, so the `ctx.agents` proxy would throw). If no live agent carries that token — e.g. the owning session disconnected and its agent was disposed while the task ran on — the notice is dropped cleanly. Injection is **durable context for the next model request, not a wake-up** — an idle agent stays idle until something sends a message. That's why the tool descriptions tell the model to poll with `bash_output`.
 
 ## Permissions
 

packages/tool-bash/src/index.ts

@@ -11,22 +11,24 @@
  * message, which is why the tool descriptions tell the model to poll with
  * `bash_output`.
  *
- * Task ownership: the owning agent is recorded per task id at spawn and kept
- * for the lifetime of THIS plugin instance (it is NOT cleared on task
- * completion — a finished task must stay un-readable / un-killable by a
- * different agent). `bash_output`/`bash_kill` reject a task owned by a DIFFERENT
- * agent (a task with no recorded owner is open to anyone). Task ids are global
- * and predictable (`bash-1`, …); under multi-session ACP (RFC 011) this
- * ownership check is the fence that stops one session's agent from reading or
- * killing another session's background task.
+ * Task ownership: a background task's OWNER is an opaque token — the owning
+ * agent's `session.header.id` — passed to the executor at spawn
+ * (`resolve({ …, owner })`) and stored ON THE TASK inside the executor
+ * (`@deepseek-ai/dsh-bash`'s `ownerOf(id)` seam), NOT in a plugin-local map.
+ * `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token
+ * and reject a task owned by a DIFFERENT session (`owner !== undefined && owner
+ * !== caller`); an unowned task (no token — started by a non-agent caller) is
+ * open to anyone. Task ids are global and predictable (`bash-1`, …); under
+ * multi-session ACP (RFC 011) this token check is the fence that stops one
+ * session's agent from reading or killing another session's background task.
  *
- * XXX(tool-bash-owner-hmr): the ownership map is per-plugin-instance, so an
- * independent HMR reload of `tool-bash` (without reloading `dsh-bash`) starts a
- * fresh map and a task spawned before the reload becomes un-owned (open to any
- * caller). This is acceptable today — HMR is dev-only, the ACP session boundary
- * is one user's cooperative editor (not an adversarial trust boundary), and the
- * executor's own disposal kills its tasks — but a durable fix would attach
- * ownership to the executor/task lifetime via a `dsh-bash` seam.
+ * Storing the token on the task in the EXECUTOR (disposed with the `dsh-bash`
+ * fiber), rather than in this plugin, is what makes ownership survive a
+ * `tool-bash` HMR reload — a reload that reset a plugin-local map would orphan
+ * a task spawned before it. (The `onTaskDone` listener is still effect-scoped
+ * to this plugin's `apply`, so a
+ * completion landing during the reload gap still drops its one notice — the
+ * pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
  *
  * TODO(permissions): commands run with the executor's full authority. The
  * permission/sandbox seam is the `tools/execute` waterfall (veto/ask) plus
@@ -268,33 +270,47 @@ function statusLine(task: BashTask): string {
 }
 
 export function apply(ctx: Context): void {
-  // Owning agent per background task id, recorded at spawn. Kept for the
-  // lifetime of THIS plugin instance (NOT cleared on completion): a completed
-  // task must stay un-readable / un-killable by a DIFFERENT agent, so the
-  // ownership record outlives the task. Under multi-session ACP (RFC 011) this
-  // is the isolation fence — one session's agent must never read or kill
-  // another session's background task. A task with no recorded owner (started by
-  // a non-loop caller, `exec.agent` absent) is unowned and accessible to anyone.
-  // An independent `tool-bash` HMR reload resets this map — see the
-  // XXX(tool-bash-owner-hmr) note in the module doc.
-  const taskOwner = new Map<string, Agent>()
+  /**
+   * The caller's owner TOKEN — the owning agent's `session.header.id`, or
+   * `undefined` for a non-agent caller. Read `session.header.id` (NOT
+   * `session.id`): every other subsystem keys off the header id (the ACP bridge,
+   * both persistence backends), and the sibling `resolveWorkdir` already reads
+   * `session.header.cwd`, so using `session.id` here would be the asymmetry smell
+   * the conventions flag. The two are equal in production, but the header is the
+   * canonical identity.
+   */
+  const callerToken = (exec: { agent?: Agent }): string | undefined => exec.agent?.session.header.id
 
   /**
-   * Authorize a `bash_output`/`bash_kill` call against a task's owner. Rejects
-   * when the task has a recorded owner and the caller is not that exact agent —
-   * including the conservative no-agent case (`exec.agent` absent cannot prove
-   * ownership of an owned task). An unowned task (no record) is allowed.
+   * Authorize a `bash_output`/`bash_kill` call against the task's stored owner
+   * token. Rejects when the task HAS an owner and it differs from the caller's
+   * token — using `!== undefined` semantics, NOT truthiness, so an empty-string
+   * token is still a real owner (never treated as unowned). An unowned task
+   * (`ownerOf` returns `undefined`) is allowed; a truly unknown id is also
+   * `undefined` here and then fails loudly at the subsequent
+   * `readOutput`/`kill` ("unknown bash task"). The conservative no-agent caller
+   * (`callerToken` undefined) cannot match an owned task and is rejected.
    */
   const assertTaskAccess = (taskId: string, exec: { agent?: Agent }): void => {
-    const owner = taskOwner.get(taskId)
-    if (owner !== undefined && owner !== exec.agent) {
+    const owner = ctx.bash.ownerOf(taskId)
+    if (owner !== undefined && owner !== callerToken(exec)) {
       throw new Error(`task ${taskId} belongs to another session`)
     }
   }
 
   // Background completion → inject a notice into the owning agent's session.
+  // Find the live agent by its session id token via the agent registry, read
+  // opportunistically with `ctx.get('agents')` (NOT `ctx.agents`/static inject):
+  // this listener runs from `task.done.then` on the bash fiber — a foreign
+  // fiber — where the `ctx.agents` property proxy would throw through the
+  // traceable shadow; `ctx.get(name)` is the topology-independent lookup. No
+  // registry mounted (`undefined`) → drop the notice. Match on
+  // `agent.session.header.id`, NOT the registry key: a config agent's id differs
+  // from its session id, and the owner token IS the session id.
   ctx.bash.onTaskDone((task) => {
-    const agent = taskOwner.get(task.id)
+    const ownerToken = ctx.bash.ownerOf(task.id)
+    if (ownerToken === undefined) return
+    const agent = ctx.get('agents')?.list().find(a => a.session.header.id === ownerToken)
     if (!agent) return
     try {
       agent.inject(
@@ -348,8 +364,11 @@ export function apply(ctx: Context): void {
         ...exec.signal ? { signal: exec.signal } : {},
       }
       if (args.run_in_background === true) {
-        const task = ctx.bash.start(ctx.bash.resolve(request))
-        if (exec.agent) taskOwner.set(task.id, exec.agent)
+        // Stamp the owner token (the agent's session id) onto the spec so the
+        // executor stores it on the task — the isolation fence for bash_output/
+        // bash_kill. Foreground runs pass no owner (they finish inline; nothing
+        // to fence).
+        const task = ctx.bash.start(ctx.bash.resolve({ ...request, owner: callerToken(exec) }))
         return [{ type: 'text', text: `started background task ${task.id}` }]
       }
       const result = await ctx.bash.run(ctx.bash.resolve(request))

packages/tool-bash/tests/tools.spec.ts

@@ -8,6 +8,8 @@ import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead } from '@deepseek-ai/dsh-bash'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { renderResult } from '@deepseek-ai/dsh-tool-bash'
@@ -18,12 +20,43 @@ async function setup() {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
   ;(ctx.bash as LocalBashExecutor).internals = { spillDir, graceMs: 200 }
   await ctx.plugin(ToolBash)
   return ctx
 }
 
+/**
+ * Build a fake {@link Agent} whose session token is `sessionId`, REGISTER it in
+ * `ctx.agents` (the completion-notice path finds the owning agent by scanning
+ * the registry for a matching `session.header.id`), and return it. The returned
+ * agent is also passed to `execute` as `exec.agent` so it owns the spawned task.
+ * The registration disposer is tracked so {@link unregisterFakeAgents} can drop
+ * it (simulating the owning session disconnecting before a task completes).
+ */
+const fakeAgentDisposers = new Map<Context, (() => void)[]>()
+function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void): Agent {
+  // The registry KEY (agent.id) is deliberately DIFFERENT from the session
+  // token (session.header.id) — a config agent has `agentId !== sessionId`. The
+  // owner token IS the session id, so the notice path must find the agent by
+  // `session.header.id`, NOT the registry key. Using distinct values here makes
+  // the test fail if a regression matched on the wrong field (a same-value fake
+  // would pass either way — the "hits the line but not the scenario" trap).
+  const agent = { id: `agent-${sessionId}`, inject, session: { header: { version: 1, id: sessionId, createdAt: 0 } } } as unknown as Agent
+  const dispose = ctx.agents.register(agent)
+  const list = fakeAgentDisposers.get(ctx) ?? []
+  list.push(dispose)
+  fakeAgentDisposers.set(ctx, list)
+  return agent
+}
+
+/** Unregister every fake agent in this ctx (simulate the owning session disconnecting). */
+function unregisterFakeAgents(ctx: Context): void {
+  for (const dispose of fakeAgentDisposers.get(ctx) ?? []) dispose()
+  fakeAgentDisposers.delete(ctx)
+}
+
 let callCounter = 0
 function call(ctx: Context, name: string, args: unknown) {
   return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args })
@@ -49,6 +82,7 @@ class LossyReadBashExecutor extends BashExecutor {
       workdir: request.workdir ?? process.cwd(),
       timeoutMs: request.timeoutMs ?? 0,
       ...request.signal ? { signal: request.signal } : {},
+      owner: request.owner,
     }
   }
 
@@ -64,6 +98,10 @@ class LossyReadBashExecutor extends BashExecutor {
     return id === this.task.id ? this.task : undefined
   }
 
+  ownerOf(): string | undefined {
+    return undefined
+  }
+
   list(): BashTask[] {
     return [this.task]
   }
@@ -320,10 +358,13 @@ describe('background tools', () => {
     expect(text(result)).toMatch(pattern)
   })
 
-  it('injects a completion notice into the owning agent', async () => {
+  it('injects a completion notice into the owning agent (found via the registry by session token)', async () => {
     const ctx = await setup()
     const inject = vi.fn()
-    const agent = { inject, session: { header: { version: 1, id: 'bg', createdAt: 0 } } } as unknown as import('@deepseek-ai/dsh-agent').Agent
+    // The notice path looks the agent up in ctx.agents by its session token, so
+    // the agent must be REGISTERED (not merely passed to execute). Mount a
+    // registry and register a fake whose session.header.id IS the owner token.
+    const agent = registerFakeAgent(ctx, 'bg', inject)
 
     const started = await ctx.tools.execute({
       callId: CallId('call-bg'),
@@ -346,10 +387,7 @@ describe('background tools', () => {
 
   it('swallows ONLY the disposed-agent inject error', async () => {
     const ctx = await setup()
-    const agent = {
-      inject: () => { throw new Error('agent "x" is disposed') },
-      session: { header: { version: 1, id: 'bg', createdAt: 0 } },
-    } as unknown as import('@deepseek-ai/dsh-agent').Agent
+    const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('agent "x" is disposed') })
 
     const started = await ctx.tools.execute({
       callId: CallId('call-bg2'),
@@ -368,10 +406,7 @@ describe('background tools', () => {
     // the listener itself must have thrown rather than silently eaten it.
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
     try {
-      const agent = {
-        inject: () => { throw new Error('unexpected inject bug') },
-        session: { header: { version: 1, id: 'bg', createdAt: 0 } },
-      } as unknown as import('@deepseek-ai/dsh-agent').Agent
+      const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('unexpected inject bug') })
 
       const started = await ctx.tools.execute({
         callId: CallId('call-bg3'),
@@ -390,6 +425,28 @@ describe('background tools', () => {
     }
   })
 
+  it('drops the notice cleanly when the owning agent is gone from the registry by completion', async () => {
+    // A bash task (owned by the host-scoped bash-local fiber) can OUTLIVE its
+    // per-session agent — e.g. the ACP session disconnects and its AgentHandle
+    // disposes while the background task is still running. The owner token is
+    // still on the task, but no live agent carries it anymore, so the registry
+    // lookup finds nothing and the notice is dropped (no throw).
+    const ctx = await setup()
+    const inject = vi.fn()
+    const agent = registerFakeAgent(ctx, 'bg', inject)
+    const started = await ctx.tools.execute({
+      callId: CallId('call-bg4'),
+      name: 'bash',
+      arguments: { command: 'true', description: 'test command', run_in_background: true },
+      agent,
+    })
+    const id = /task (bash-\d+)/.exec(text(started))![1]!
+    // Unregister the agent BEFORE the task completes (simulate disconnect).
+    unregisterFakeAgents(ctx)
+    await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
+    expect(inject).not.toHaveBeenCalled()
+  })
+
   it('does not notify when no agent owned the task', async () => {
     const ctx = await setup()
     const started = await call(ctx, 'bash', { command: 'true', description: 'test command', run_in_background: true })
@@ -403,18 +460,23 @@ describe('background task ownership (cross-session isolation)', () => {
   function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, name: string, args: unknown) {
     return ctx.tools.execute({ callId: CallId(`own-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
   }
-  // Distinct identities — ownership is by agent object identity, not id.
-  const fakeAgent = () => ({ inject: () => undefined, session: { header: { version: 1, id: 'bg', createdAt: 0 } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
+  // Ownership is by TOKEN (session.header.id), NOT agent object identity — so
+  // each agent needs a DISTINCT session id, else every fake yields the same
+  // token and the isolation tests pass for the wrong reason (all tasks owned by
+  // the same token). The impl reads `session.header.id`, so the fakes MUST carry
+  // it.
+  const fakeAgent = (sessionId: string) =>
+    ({ inject: () => undefined, session: { header: { version: 1, id: sessionId, createdAt: 0 } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
 
-  it('rejects bash_output/bash_kill for a task owned by a DIFFERENT agent', async () => {
+  it('rejects bash_output/bash_kill for a task owned by a DIFFERENT session token', async () => {
     const ctx = await setup()
-    const a = fakeAgent()
-    const b = fakeAgent()
+    const a = fakeAgent('sess-a')
+    const b = fakeAgent('sess-b')
     // Agent A starts a long-running background task.
     const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
     const id = /task (bash-\d+)/.exec(text(started))![1]!
 
-    // Agent B cannot read or kill A's task.
+    // Agent B (a different session token) cannot read or kill A's task.
     const readByB = await callAs(ctx, b, 'bash_output', { task_id: id })
     expect(readByB.isError).toBe(true)
     expect(text(readByB)).toMatch(/belongs to another session/)
@@ -428,12 +490,26 @@ describe('background task ownership (cross-session isolation)', () => {
     expect(text(killByA)).toBe(`killed background task ${id}`)
   })
 
+  it('a DIFFERENT Agent object with the SAME session token may access the task (ownership is by token, not object identity)', async () => {
+    // Ownership fences by session.header.id, NOT Agent object identity. Two
+    // distinct Agent objects sharing one session token (e.g. an agent re-created
+    // on the same session) are the SAME owner.
+    const ctx = await setup()
+    const a1 = fakeAgent('sess-shared')
+    const a2 = fakeAgent('sess-shared') // distinct object, same token
+    const started = await callAs(ctx, a1, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
+    const id = /task (bash-\d+)/.exec(text(started))![1]!
+    const readByA2 = await callAs(ctx, a2, 'bash_output', { task_id: id })
+    expect(readByA2.isError).toBe(false)
+    await callAs(ctx, a1, 'bash_kill', { task_id: id }) // cleanup
+  })
+
   it('the no-agent (non-loop) caller cannot access an owned task', async () => {
     const ctx = await setup()
-    const a = fakeAgent()
+    const a = fakeAgent('sess-a')
     const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
     const id = /task (bash-\d+)/.exec(text(started))![1]!
-    // A call with no exec.agent cannot prove ownership of an owned task.
+    // A call with no exec.agent has no token → cannot prove ownership of an owned task.
     const read = await callAs(ctx, undefined, 'bash_output', { task_id: id })
     expect(read.isError).toBe(true)
     expect(text(read)).toMatch(/belongs to another session/)
@@ -442,20 +518,20 @@ describe('background task ownership (cross-session isolation)', () => {
 
   it('an UNOWNED task (started with no agent) is accessible to anyone', async () => {
     const ctx = await setup()
-    // Started by a non-loop caller (no exec.agent) → no recorded owner.
+    // Started by a non-loop caller (no exec.agent) → no owner token recorded.
     const started = await callAs(ctx, undefined, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
     const id = /task (bash-\d+)/.exec(text(started))![1]!
     // Any agent (and the no-agent caller) may read/kill it.
-    const read = await callAs(ctx, fakeAgent(), 'bash_output', { task_id: id })
+    const read = await callAs(ctx, fakeAgent('sess-x'), 'bash_output', { task_id: id })
     expect(read.isError).toBe(false)
     const killed = await callAs(ctx, undefined, 'bash_kill', { task_id: id })
     expect(killed.isError).toBe(false)
   })
 
-  it('the owner can still access its task AFTER it completes (owner record persists)', async () => {
+  it('the owner can still access its task AFTER it completes (owner token persists on the task)', async () => {
     const ctx = await setup()
-    const a = fakeAgent()
-    const b = fakeAgent()
+    const a = fakeAgent('sess-a')
+    const b = fakeAgent('sess-b')
     const started = await callAs(ctx, a, 'bash', { command: 'echo done', description: 'bg', run_in_background: true })
     const id = /task (bash-\d+)/.exec(text(started))![1]!
     await ctx.bash.get(id)!.done
@@ -467,12 +543,12 @@ describe('background task ownership (cross-session isolation)', () => {
     expect(readByA.isError).toBe(false)
   })
 
-  it('documents the HMR caveat: an independent tool-bash reload resets ownership', async () => {
-    // The ownership map is per-plugin-instance (XXX(tool-bash-owner-hmr)). When
-    // ONLY tool-bash is reloaded (bash/executor + task survive), the new instance
-    // has an empty map, so the previously-owned task becomes unowned (open). This
-    // test pins that documented behavior — a regression here (e.g. an accidental
-    // global map) would change it.
+  it('ownership SURVIVES an independent tool-bash HMR reload (token lives on the executor)', async () => {
+    // The owner token lives on the TASK inside the executor (dsh-bash fiber), NOT
+    // in a tool-bash plugin-local map. So reloading ONLY tool-bash (executor +
+    // task survive) preserves ownership. This is the regression guard: a
+    // plugin-local map would make B accessible after reload, and this test would
+    // catch it.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -480,21 +556,23 @@ describe('background task ownership (cross-session isolation)', () => {
     ;(ctx.bash as LocalBashExecutor).internals = { spillDir, graceMs: 200 }
     const fiber = await ctx.plugin(ToolBash)
 
-    const a = fakeAgent()
-    const b = fakeAgent()
+    const a = fakeAgent('sess-a')
+    const b = fakeAgent('sess-b')
     const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
     const id = /task (bash-\d+)/.exec(text(started))![1]!
     // Before reload: B is rejected (A owns it).
     expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
 
-    // Reload ONLY tool-bash; the executor and its running task survive.
+    // Reload ONLY tool-bash; the executor and its running task (with its owner
+    // token) survive.
     await fiber.dispose()
     await ctx.plugin(ToolBash)
     expect(ctx.bash.get(id)?.status).toBe('running')
+    expect(ctx.bash.ownerOf(id)).toBe('sess-a')
 
-    // After reload the fresh map has no owner → B can now access it (the caveat).
-    expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(false)
-    await callAs(ctx, b, 'bash_kill', { task_id: id }) // cleanup
+    // After reload, ownership is INTACT → B is STILL rejected.
+    expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
+    await callAs(ctx, a, 'bash_kill', { task_id: id }) // cleanup
   })
 })