@openparachute/agent 0.2.0 → 0.2.3-rc.10

package/.parachute/module.json

@@ -52,7 +52,7 @@
         "module": "vault",
         "event": "note.created",
         "filter": {
-          "tags": ["#agent/message/inbound"],
+          "tags": ["agent/message/inbound"],
           "has_metadata": ["channel"],
           "missing_metadata": ["channel_inbound_rendered_at"]
         }
@@ -85,7 +85,7 @@
         "module": "vault",
         "event": "note.created",
         "filter": {
-          "tags": ["#agent/definition"]
+          "tags": ["agent/definition"]
         }
       },
       "sink": {
@@ -110,7 +110,7 @@
         "module": "vault",
         "event": "note.updated",
         "filter": {
-          "tags": ["#agent/definition"]
+          "tags": ["agent/definition"]
         }
       },
       "sink": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.0",
+  "version": "0.2.3-rc.10",
   "description": "Vault-native agents for Claude Code — a #agent/definition note + an inbound message becomes a sandboxed claude turn; the reply is written back as a note. Messaging gateway on :1941.",
   "license": "AGPL-3.0",
   "type": "module",
@@ -24,6 +24,8 @@
     "test:spa": "cd web/ui && bun run test",
     "test:all": "bun run test && bun run test:spa",
     "test:e2e": "bun e2e/llm/run.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
     "prepack": "bun run build:spa"
@@ -39,6 +41,11 @@
     "typescript": "^5"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
     "@types/bun": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ParachuteComputer/parachute-agent.git"
   }
 }

package/src/agent-defs.ts

@@ -389,6 +389,15 @@ export function parseAgentDef(note: {
   }
 
   // Filesystem read scope.
+  //
+  // NOTE (step-up, agent#80): `filesystem: "full"` is the dangerous, full-disk
+  // case. The step-up PIN gate is enforced on the HTTP spawn path only
+  // (`POST /api/agents` in daemon.ts). This VAULT-NATIVE path (a #agent/definition
+  // note with `filesystem: full`) is NOT step-up-gated — registering it requires
+  // `vault:write` to author the note, which is itself separately scope-gated, so a
+  // step-up challenge here would gate a capability the caller already had to hold a
+  // write credential to reach. If the threat model is ever revisited (e.g. less-
+  // trusted note authors), this is the gap to close.
   const filesystem = metaStr(meta.filesystem);
   if (filesystem !== undefined) {
     if (filesystem !== "workspace" && filesystem !== "full") {

package/src/auth.ts

@@ -7,13 +7,26 @@
  *   - Layer 1 (bridge / session↔channel): the bridge presents the token as an
  *     `Authorization: Bearer` header on `/events` + `/api/*`.
  *   - Layer 2 (human / chat UI): the page fetches a short-lived token from the
- *     hub (`/admin/agent-token`) and attaches it — as a Bearer header on the
- *     `send` POST, and as a `?token=` query param on the `/ui/events` SSE
- *     (EventSource can't set headers).
+ *     hub (`/admin/agent-token`) and attaches it as a Bearer header on the
+ *     `send` POST. For the browser SSE streams (`/ui/events`,
+ *     `/api/channels/<ch>/turn-events`) — which an `EventSource` can't set a
+ *     header on — the page does NOT put the JWT in the URL. Instead it mints a
+ *     one-time SSE TICKET (`POST /api/ui/sse-ticket`, Bearer-authenticated) and
+ *     opens `…?ticket=<nonce>`. See `requireSseTicket` below + `ui-ticket.ts`.
  *
- * `requireScope` accepts the token from EITHER source so one helper guards both
- * layers. The no-token path short-circuits before any JWKS fetch, keeping it
- * unit-testable without a live hub (same approach Layer 1 used).
+ * `requireScope` accepts the token from a Bearer header (and, for the
+ * agent:admin terminal WebSocket only, a `?token=` query param). The no-token
+ * path short-circuits before any JWKS fetch, keeping it unit-testable without a
+ * live hub (same approach Layer 1 used).
+ *
+ * WHY THE TICKET (agent#25). A full hub JWT in a `?token=` URL lands in any
+ * access/proxy log, browser history, or network trace — a credential leak
+ * mitigated before only by the token's short TTL. The browser SSE endpoints now
+ * trade the JWT for an opaque, single-use, ≤60s ticket (`requireSseTicket`); the
+ * JWT only ever travels in a `fetch` Bearer header. The legacy `?token=` SSE
+ * path was REMOVED (pre-1.0, no deprecation window). The terminal WebSocket
+ * (`agent:admin`) still uses `?token=` — a separate, operator-gated mechanism
+ * out of this change's scope.
  *
  * DUAL-ACCEPT (channel→agent rename transition,
  * `parachute-patterns/migrations/2026-06-17-channel-to-agent.md` rule 1). New
@@ -26,6 +39,8 @@
 
 import { validateHubJwt, HubJwtError } from "./hub-jwt.ts";
 import { extractBearer } from "@openparachute/scope-guard";
+import { consumeTicket } from "./ui-ticket.ts";
+import { isStepUpTokenValid, isStepUpConfigured } from "./step-up.ts";
 
 /** Agent scopes, declared here so callers share one spelling. */
 export const SCOPE_READ = "agent:read" as const;
@@ -79,15 +94,18 @@ export function json(data: unknown, status = 200): Response {
 
 /**
  * Extract a presented token from a request: the `Authorization: Bearer` header
- * first (the bridge + the UI's POST), falling back to a `?token=` query param
- * (the SSE case — `EventSource` can't set headers). Returns null if neither is
- * present.
+ * first (the bridge, the UI's POST, the SSE-ticket mint), falling back to a
+ * `?token=` query param only when `allowQueryParam` is set. The ONLY caller that
+ * opts into the query param is the agent:admin terminal WebSocket
+ * (`new WebSocket()` can't set headers); the browser SSE streams moved to the
+ * one-time-ticket path (`requireSseTicket`) so a JWT never rides in a URL. Returns
+ * null if neither source is present.
  */
 export function extractToken(req: Request, url: URL, allowQueryParam = false): string | null {
   const bearer = extractBearer(req.headers.get("authorization"));
   if (bearer) return bearer;
-  // `?token=` is opt-in (the SSE case only). The bridge + the UI POST present a
-  // Bearer header, so they never enable it — keeps query-param tokens off every
+  // `?token=` is opt-in (the terminal WebSocket only). Every other caller presents
+  // a Bearer header, so they leave it false — keeping query-param JWTs off every
   // endpoint that doesn't strictly need them (and out of those access logs).
   if (allowQueryParam) {
     const q = url.searchParams.get("token");
@@ -99,9 +117,10 @@ export function extractToken(req: Request, url: URL, allowQueryParam = false): s
 /**
  * Guard an HTTP endpoint on a hub-issued JWT carrying `scope`. The token arrives
  * as an `Authorization: Bearer` header; pass `allowQueryParam: true` to also
- * accept a `?token=` query param (the SSE case only — `EventSource` can't set
- * headers). Bridge + UI-POST callers leave it false, so query-param tokens are
- * confined to the one endpoint that needs them.
+ * accept a `?token=` query param (the agent:admin terminal WebSocket only —
+ * `new WebSocket()` can't set headers). All other callers leave it false, so
+ * query-param JWTs are confined to that one endpoint. Browser SSE streams use
+ * `requireSseTicket` (the one-time ticket), not this.
  *
  * Returns `null` when the request is authorized (caller proceeds), or a
  * `Response` (401/403) the caller must return as-is.
@@ -138,3 +157,152 @@ export async function requireScope(
     );
   }
 }
+
+/**
+ * Mint endpoint for a one-time SSE ticket (agent#25). Authenticate the presented
+ * Bearer JWT for `scope` (the SAME validation `requireScope` runs — no-token →
+ * 401 pre-JWKS, bad/insufficient → 401/403), then issue a single-use, ≤60s
+ * opaque ticket carrying ONLY the token's validated scopes. The ticket — never
+ * the JWT — goes in the SSE URL. Returns the mint `Response` (200 `{ ticket,
+ * expires_at }`, or the gate's 401/403) for the caller to return as-is.
+ *
+ * `mintTicket` is injected (defaults to the real `ui-ticket.ts` store) so unit
+ * tests can assert what scopes get carried without reaching into the singleton.
+ * Critically, an UNAUTHENTICATED mint is impossible: the scope gate runs first
+ * and short-circuits before any ticket is created — minting without a valid
+ * bearer would be an auth bypass.
+ */
+export async function mintSseTicket(
+  req: Request,
+  url: URL,
+  scope: string,
+  mint: (scopes: readonly string[]) => { ticket: string; expiresAt: number },
+): Promise<Response> {
+  const token = extractToken(req, url); // Bearer header ONLY — never a query param.
+  if (!token) {
+    return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+  }
+  let scopes: string[];
+  try {
+    const claims = await validateHubJwt(token);
+    if (!grantsScope(claims.scopes, scope)) {
+      return json(
+        { error: "insufficient_scope", message: `requires ${scope}`, granted: claims.scopes },
+        403,
+      );
+    }
+    // Carry the token's OWN validated scopes — never widen beyond what it holds.
+    scopes = claims.scopes;
+  } catch (err) {
+    return json(
+      { error: "unauthorized", message: err instanceof HubJwtError ? err.message : "invalid token" },
+      401,
+    );
+  }
+  const { ticket, expiresAt } = mint(scopes);
+  return json({ ticket, expires_at: new Date(expiresAt).toISOString() });
+}
+
+/**
+ * Guard a browser SSE endpoint on a one-time `?ticket=<nonce>` (agent#25 — the
+ * EventSource auth path that replaced the leaky `?token=<JWT>`). Look up + CONSUME
+ * the ticket (single-use: a second connect 401s), then assert the ticket's carried
+ * scopes include `scope` (the ticket can never authorize more than the JWT that
+ * minted it — `mintSseTicket` stored exactly that JWT's scopes). Returns `null`
+ * when authorized (caller opens the stream) or a 401 `Response` to return as-is.
+ *
+ * No JWKS fetch on this path — the JWT was validated at MINT time and its scopes
+ * captured in the ticket; consume is a pure in-memory lookup. So an absent /
+ * expired / already-used / under-scoped ticket all map to 401 with no network I/O.
+ */
+export function requireSseTicket(url: URL, scope: string): Response | null {
+  const consumed = consumeTicket(url.searchParams.get("ticket"));
+  if (!consumed) {
+    return json({ error: "unauthorized", message: "valid one-time SSE ticket required" }, 401);
+  }
+  if (!grantsScope(consumed.scopes, scope)) {
+    return json(
+      { error: "insufficient_scope", message: `ticket lacks ${scope}`, granted: consumed.scopes },
+      403,
+    );
+  }
+  return null;
+}
+
+/**
+ * The header a request carries the step-up token on (agent#80). The terminal
+ * WebSocket — which `new WebSocket()` can't set a header on — uses the
+ * `?step_up=` query param instead (mirroring the `?token=` exception).
+ */
+export const STEP_UP_TOKEN_HEADER = "x-step-up-token";
+
+/** Extract a presented step-up token: the header first, then `?step_up=` when allowed. */
+export function extractStepUpToken(req: Request, url: URL, allowQueryParam = false): string | null {
+  const header = req.headers.get(STEP_UP_TOKEN_HEADER);
+  if (header && header.length > 0) return header;
+  if (allowQueryParam) {
+    const q = url.searchParams.get("step_up");
+    if (q && q.length > 0) return q;
+  }
+  return null;
+}
+
+/**
+ * SECOND-FACTOR gate (agent#80) for the genuinely dangerous `agent:admin` actions:
+ * set/rotate credentials, open a terminal, spawn a `filesystem: full` agent. The
+ * caller runs {@link requireScope}(`agent:admin`) FIRST; this asserts — IN ADDITION —
+ * a valid step-up token (the operator entered their PIN recently).
+ *
+ *   - Step-up NOT configured (no PIN set) → returns `{ ok: false, reason: "setup" }`.
+ *     The caller maps it to `403 { error: "step_up_required", reason: "setup" }` so
+ *     the UI runs its FIRST-TIME PIN-setup flow before the action.
+ *   - PIN configured + valid token → `{ ok: true }` (the action proceeds).
+ *   - PIN configured + missing/expired token → `{ ok: false, reason: "token" }` →
+ *     `403 { error: "step_up_required" }` so the UI PROMPTS for the PIN.
+ *
+ * The 403 is deliberately DISTINCT from `requireScope`'s 401 (no/invalid Bearer):
+ * a 401 means "re-authenticate", a 403 `step_up_required` means "enter your PIN".
+ * The step-up token NEVER widens scope — the request already passed `agent:admin`;
+ * this is purely a recency re-confirm on top.
+ *
+ * `allowQueryParam: true` accepts `?step_up=` for the terminal WebSocket only.
+ * Pure in-memory token check — no I/O on the gated request path, no secret logged.
+ */
+export function requireStepUp(
+  req: Request,
+  url: URL,
+  allowQueryParam = false,
+  opts?: { configured?: () => boolean; valid?: (token: string | null) => boolean },
+): { ok: true } | { ok: false; response: Response } {
+  const isConfigured = opts?.configured ?? (() => isStepUpConfigured());
+  const isValid = opts?.valid ?? ((t: string | null) => isStepUpTokenValid(t));
+  if (!isConfigured()) {
+    // No PIN yet — the UI must set one before this action can proceed.
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "setup",
+          message: "set a step-up PIN before performing this action",
+        },
+        403,
+      ),
+    };
+  }
+  const token = extractStepUpToken(req, url, allowQueryParam);
+  if (!isValid(token)) {
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "token",
+          message: "enter your step-up PIN to confirm this action",
+        },
+        403,
+      ),
+    };
+  }
+  return { ok: true };
+}

package/src/backends/registry.ts

@@ -174,8 +174,16 @@ export interface ThreadNote {
  * per channel, multi-threaded writes one per fire. A write failure is the implementation's
  * to surface (the registry logs whatever it throws); it never re-runs the turn. Optional on
  * the registry — when unwired (no vault-backed channel), a turn still runs, just no note.
+ *
+ * RETURNS the WRITTEN thread-note's id (`{ id }`) so the drain can use it as a RESOLVABLE
+ * `source_thread` on the agent-to-agent callback (agent#124) — for BOTH modes, this is the
+ * actual note an orchestrator can pull with `query-notes { id }` (single-threaded: the
+ * deterministic `Threads/<safeChannel>/<safeName>` note; multi-threaded: the per-fire
+ * `Threads/<safeChannel>/<uuid>` note). `void` is in the union (back-compat) — a transport
+ * with no durable store, or one that can't surface an id, returns it and the drain falls
+ * back to the per-turn id.
  */
-export type WriteThread = (thread: ThreadNote) => Promise<void>;
+export type WriteThread = (thread: ThreadNote) => Promise<{ id?: string } | void>;
 
 /**
  * A callback delivered back to a SENDER's channel when a turn it requested finishes —
@@ -216,15 +224,16 @@ export interface CallbackMeta {
   /** The channel/def whose turn just finished (the recipient) — provenance for the sender. */
   source_channel: string;
   /**
-   * The per-turn thread id the drain minted. RESOLVABILITY DIFFERS BY MODE:
-   *  - multi-threaded: this IS the per-fire note's leaf — the orchestrator can pull the
-   *    thread note at `Threads/<channel>/<source_thread>`.
-   *  - single-threaded: this is a per-turn CORRELATION id, NOT the note leaf (the
-   *    single-threaded note lives at the deterministic `Threads/<channel>/<name>`), so it
-   *    is NOT directly resolvable. Use `source_message` as the reliable pull-link for a
-   *    single-threaded recipient. Making this a resolvable thread id for both modes
-   *    (widen the writeThread seam to return the written note id) is tracked as a
-   *    follow-up (parachute-agent#124).
+   * The WRITTEN thread-note id — RESOLVABLE for BOTH modes (agent#124): an orchestrator can
+   * always pull the recipient's full thread record with `query-notes { id: source_thread }`,
+   * even on an error/empty/tool-only turn (the thread note is written BEFORE the outbound
+   * reply, so its id exists when there's no `source_message`).
+   *  - multi-threaded: the per-fire note id (`Threads/<safeChannel>/<uuid>`).
+   *  - single-threaded: the deterministic note id (`Threads/<safeChannel>/<safeName>`) — NOT
+   *    the per-turn correlation id (the pre-#124 bug: that correlation id wasn't the note leaf
+   *    for single-threaded, so it couldn't be resolved).
+   * The drain sources this from {@link WriteThread}'s returned id; if the seam can't surface
+   * one (no durable store) it falls back to the per-turn id (still a stable provenance token).
    */
   source_thread: string;
   /**
@@ -835,7 +844,7 @@ export class ProgrammaticAgentRegistry {
         // thread note captures the turn outcome, so a failed turn is still a queryable
         // `status:error` (single-threaded upserts the rolling thread; multi-threaded writes
         // a per-fire note).
-        await this.recordThread(handle, msg, "error", reason, startedAt, undefined, {
+        const threadNoteId = await this.recordThread(handle, msg, "error", reason, startedAt, undefined, {
           threadId: turnThreadId,
           phase: "end",
           // No `result` (the backend threw) → NO session to persist. We never write a
@@ -848,8 +857,10 @@ export class ProgrammaticAgentRegistry {
         // no-reply) — best-effort.
         await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, reason);
         // CALLBACK on the failure too — an orchestrator MUST learn its sub-task failed, not
-        // hang waiting forever. No outbound note was produced, so no `source_message`.
-        await this.maybeDeliverCallback(handle, msg, turnThreadId, "error");
+        // hang waiting forever. No outbound note was produced, so no `source_message`; the
+        // RESOLVABLE thread-note id (written above) is `source_thread` so the orchestrator can
+        // still pull the recipient's thread on a no-reply turn (agent#124).
+        await this.maybeDeliverCallback(handle, msg, turnThreadId, "error", undefined, threadNoteId);
         continue;
       }
 
@@ -863,7 +874,7 @@ export class ProgrammaticAgentRegistry {
         // BOTH modes record the failed turn (status:error) on the thread note so a failure
         // always leaves a queryable trace (single-threaded upserts the rolling thread,
         // marking it errored; multi-threaded writes a per-fire status:error note).
-        await this.recordThread(handle, msg, "error", result.error, startedAt, undefined, {
+        const threadNoteId = await this.recordThread(handle, msg, "error", result.error, startedAt, undefined, {
           threadId: turnThreadId,
           phase: "end",
           // Persist ONLY the session claude ECHOED (FIX 2). A turn can fail AFTER
@@ -878,8 +889,9 @@ export class ProgrammaticAgentRegistry {
         // no-reply) — best-effort.
         await this.postFailureNote(channel, msg.inReplyTo, turnThreadId, result.error);
         // CALLBACK on the failure-as-value too (status:error) — the orchestrator learns the
-        // sub-task failed and can react. No delivered reply, so no `source_message`.
-        await this.maybeDeliverCallback(handle, msg, turnThreadId, "error");
+        // sub-task failed and can react. No delivered reply, so no `source_message`; the
+        // RESOLVABLE thread-note id (written above) is `source_thread` (agent#124).
+        await this.maybeDeliverCallback(handle, msg, turnThreadId, "error", undefined, threadNoteId);
         continue;
       }
 
@@ -891,7 +903,11 @@ export class ProgrammaticAgentRegistry {
       // multi-threaded writes the per-fire note. Best-effort: a thread-note failure is
       // logged + the turn still resolves (we never re-run a `claude -p` turn — that would
       // burn quota for a duplicate).
-      await this.recordThread(handle, msg, "ok", result.reply ?? "", startedAt, result.usage, {
+      // Capture the WRITTEN thread-note id — the RESOLVABLE `source_thread` for the callback
+      // (agent#124). The same note id is reused for the outbound-failure re-record below
+      // (sameTurn → same note), so a callback on either terminal path points at a pullable
+      // thread record.
+      let threadNoteId = await this.recordThread(handle, msg, "ok", result.reply ?? "", startedAt, result.usage, {
         threadId: turnThreadId,
         phase: "end",
         // Persist the session claude ECHOED (FIX 2) so the next turn `--resume`s this
@@ -938,7 +954,9 @@ export class ProgrammaticAgentRegistry {
           // `sameTurn` so this updates the note the `ok` record above just wrote (one
           // note, no turn_count double-count) rather than minting a duplicate / advancing
           // the count (the FIX-1 re-record bug the reviewer caught).
-          await this.recordThread(
+          // Re-record returns the SAME note's id (sameTurn upsert / same per-fire note) — use
+          // it as the callback `source_thread` (agent#124), falling back to the ok-record id.
+          threadNoteId = (await this.recordThread(
             handle,
             msg,
             "error",
@@ -955,7 +973,7 @@ export class ProgrammaticAgentRegistry {
               // write failed. Only claude's echoed id (FIX 2), never the passed uuid.
               ...(result.sessionId ? { session: result.sessionId } : {}),
             },
-          );
+          )) ?? threadNoteId;
           this.emitTurnEvent(channel, {
             kind: "error",
             error: `reply produced but not saved: ${delivered.error}`,
@@ -963,8 +981,8 @@ export class ProgrammaticAgentRegistry {
           // CALLBACK as status:error — the reply was produced but NOT delivered, so the
           // turn did not truly succeed; the orchestrator must learn that. No `source_message`
           // (the outbound note never landed); the undelivered text lives in the error thread
-          // note for an operator to recover.
-          await this.maybeDeliverCallback(handle, msg, turnThreadId, "error");
+          // note for an operator to recover — pull it via the RESOLVABLE `source_thread`.
+          await this.maybeDeliverCallback(handle, msg, turnThreadId, "error", undefined, threadNoteId);
           continue;
         }
       }
@@ -976,8 +994,10 @@ export class ProgrammaticAgentRegistry {
       // (empty/tool-only turn → clean resolve, no note expected).
       this.emitTurnEvent(channel, { kind: "done", reply: result.reply ?? "" });
       // CALLBACK on success — the turn finished cleanly (status:ok). `sourceMessage` is the
-      // delivered reply note (when there was one) the orchestrator pulls the full result from.
-      await this.maybeDeliverCallback(handle, msg, turnThreadId, "ok", sourceMessage);
+      // delivered reply note (when there was one) the orchestrator pulls the full result from;
+      // `source_thread` (the WRITTEN thread-note id, agent#124) is the RESOLVABLE pull-link in
+      // both modes, including an empty/tool-only turn where there's no `sourceMessage`.
+      await this.maybeDeliverCallback(handle, msg, turnThreadId, "ok", sourceMessage, threadNoteId);
     }
   }
 
@@ -1013,6 +1033,7 @@ export class ProgrammaticAgentRegistry {
     turnThreadId: string,
     status: "ok" | "error",
     sourceMessage?: string,
+    sourceThreadId?: string,
   ): Promise<void> {
     // Guard 1 + 2: no sink, or this wasn't a delegated request → nothing to call back.
     if (!this.writeCallback) return;
@@ -1041,11 +1062,17 @@ export class ProgrammaticAgentRegistry {
     // source_message are echoed/included only when present. The daemon's WriteCallback
     // wiring writes this as a `#agent/message/inbound` note to `msg.replyTo` and — CRUCIALLY
     // — does NOT stamp a `reply_to` on it (the terminal-callback loop guard).
+    //
+    // `source_thread` is the WRITTEN thread-note id (agent#124) — RESOLVABLE for BOTH modes
+    // (`query-notes { id: source_thread }`), available even on an error/empty/tool-only turn
+    // (the thread note is written before the outbound). Fall back to the per-turn id only when
+    // the thread seam surfaced none (no durable store / a write failure) — still a stable
+    // provenance token, just not a pullable note.
     const meta: CallbackMeta = {
       callback: "true",
       status,
       source_channel: handle.channel,
-      source_thread: turnThreadId,
+      source_thread: sourceThreadId ?? turnThreadId,
       ...(sourceMessage ? { source_message: sourceMessage } : {}),
       ...(msg.correlationId ? { correlation_id: msg.correlationId } : {}),
       delegation_depth: String(incomingDepth + 1),
@@ -1071,6 +1098,11 @@ export class ProgrammaticAgentRegistry {
    * agent name (single-threaded's thread is "named after the definition"). Best-effort: a
    * write failure is LOGGED, never thrown out — a missing thread note must not strand the
    * queue, and the turn is never re-run (it would burn quota for a duplicate `claude -p`).
+   *
+   * RETURNS the WRITTEN thread-note id so the drain can use it as a RESOLVABLE
+   * `source_thread` on the agent-to-agent callback (agent#124), for BOTH modes. `undefined`
+   * when no sink is wired, the write failed, or the seam surfaced no id — the drain then
+   * falls back to the per-turn id.
    */
   private async recordThread(
     handle: ProgrammaticAgentHandle,
@@ -1080,8 +1112,8 @@ export class ProgrammaticAgentRegistry {
     startedAt: string,
     usage: ThreadNote["usage"],
     opts: { threadId?: string; sameTurn?: boolean; phase?: "start" | "end"; session?: string } = {},
-  ): Promise<void> {
-    if (!this.writeThread) return;
+  ): Promise<string | undefined> {
+    if (!this.writeThread) return undefined;
     const thread: ThreadNote = {
       channel: handle.channel,
       name: handle.spec.name,
@@ -1107,12 +1139,18 @@ export class ProgrammaticAgentRegistry {
       ...(opts.phase ? { phase: opts.phase } : {}),
     };
     try {
-      await this.writeThread(thread);
+      // The seam returns the WRITTEN note id (`{ id }`) for a durable transport; `void` for
+      // one with no store. Surface it so the drain can set a RESOLVABLE callback
+      // `source_thread` (agent#124). A missing id → undefined → the drain falls back to the
+      // per-turn id.
+      const written = await this.writeThread(thread);
+      return written?.id;
     } catch (err) {
       console.error(
         `parachute-agent: writing #agent/thread note for channel "${handle.channel}" failed ` +
           `(continuing): ${(err as Error).message}`,
       );
+      return undefined;
     }
   }