Merge branch 'structured-output-subagent-seam' into worktree-dynamic-workflows

# Conflicts: # examples/acp-agent/tests/snapshots/cancel/session.jsonl # examples/acp-agent/tests/snapshots/error-finish/session.jsonl # examples/acp-agent/tests/snapshots/fs-edit/session.jsonl # examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl # examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl # examples/acp-agent/tests/snapshots/fs-read/session.jsonl # examples/acp-agent/tests/snapshots/fs-terminal-card/session.jsonl # examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl # examples/acp-agent/tests/snapshots/fs-write/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl # examples/acp-agent/tests/snapshots/multi-turn/session.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl # examples/acp-agent/tests/snapshots/todo-plan/session.jsonl # examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl # examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl
2026-07-07 10:00:58 +08:00
parent 4641f1a851 8c8189844f
commit 10533da8bf
81 changed files with 2981 additions and 163 deletions
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -43,7 +43,7 @@ Compaction is serialized via a log-recorded lock: `compactRegion` refuses to sta

 ## Events

-The `compact/*` events extend `SessionEventMap` (merge-extensible) via declaration merging — they are session events, not cordis `Events`, and all three are log-only (no `surfaceOp`). Per-event payloads and semantics are in the generated [persistence log event catalog](../../../docs/persistence-catalog/log-events.md).
+The `compact/*` events extend `SessionEventMap` (merge-extensible) via declaration merging — they are session events, not cordis `Events`, and all three are log-only (no `surfaceOp`). Per-event payloads and semantics are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md).

 ## Implementing a backend

--- a/packages/core/agent-core/tests/gen-config-catalog.spec.ts
+++ b/packages/core/agent-core/tests/gen-config-catalog.spec.ts
@@ -0,0 +1,458 @@
+/**
+ * Negative-path tests for the config catalog generator (`scripts/gen-config-catalog.ts`).
+ *
+ * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
+ * the freshness half is exercised by `pnpm run verify-config-catalog` in CI.
+ * What a freshness diff CANNOT prove is that the generator REJECTS malformed
+ * source the way it promises to — an unclassifiable package, an undocumented
+ * config field, a schema key the config type does not declare, or a referenced
+ * type name that resolves nowhere. These tests drive `collectConfigCatalog()`
+ * against synthetic fixture packages to prove each guard fires (and that
+ * well-formed packages classify and extract correctly), mirroring the
+ * negative tests for gen-cordis-catalog. The spec lives in this package
+ * because agent-core is the config-composition plugin (its schema is the
+ * intersection of its children's), the shape the generator's cross-package
+ * folding exists for.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectConfigCatalog, render } from '../../../../scripts/gen-config-catalog.ts'
+
+/** Write one fixture package (package.json + src files) under a scan root. */
+function writePkg(root: string, dir: string, name: string, files: Record<string, string>): void {
+  const pkgDir = join(root, 'packages', dir)
+  mkdirSync(join(pkgDir, 'src'), { recursive: true })
+  writeFileSync(join(pkgDir, 'package.json'), JSON.stringify({ name }))
+  for (const [rel, text] of Object.entries(files)) writeFileSync(join(pkgDir, rel), text)
+}
+
+const roots: string[] = []
+const makeRoot = (): string => {
+  const root = mkdtempSync(join(tmpdir(), 'config-catalog-'))
+  roots.push(root)
+  return root
+}
+/** One-package fixture: the common case. */
+const make = (files: Record<string, string>, name = '@fix/one'): string => {
+  const root = makeRoot()
+  writePkg(root, 'group/one', name, files)
+  return root
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+const DOCUMENTED_CONFIG = `/** Fixture config. */
+export interface Config {
+  /** A knob. */
+  knob?: string
+}
+`
+
+describe('gen-config-catalog classification', () => {
+  it('classifies an apply plugin with a config parameter and extracts the paste', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+export const inject = ['tools']
+${DOCUMENTED_CONFIG}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]).toMatchObject({ pkg: '@fix/one', kind: 'config', configTypeName: 'Config', inject: ['tools'] })
+    expect(entries[0]?.pastes?.[0]?.text).toContain('/** A knob. */')
+  })
+
+  it('classifies a default service class, reading its constructor and static inject', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+/** Fixture service. */
+export default class Fix {
+  static inject = ['llm']
+  static Config = z.object({ knob: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    }))
+    expect(entries[0]).toMatchObject({ kind: 'config', className: 'Fix', inject: ['llm'], schemaKeys: ['knob'] })
+  })
+
+  it('classifies an abstract default class as a seam', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'export default abstract class FixSeam { abstract run(): void }\n',
+    }))
+    expect(entries[0]).toMatchObject({ kind: 'seam', className: 'FixSeam' })
+  })
+
+  it('classifies a plugin whose apply takes no config as no-config', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'import type { Context } from \'cordis\'\n/** Load. */\nexport function apply(ctx: Context): void {}\n',
+    }))
+    expect(entries[0]?.kind).toBe('no-config')
+  })
+
+  it('classifies a module with neither default export nor apply as a library', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'export const helper = 1\n',
+    }))
+    expect(entries[0]?.kind).toBe('library')
+  })
+
+  it('hard-errors on a package with no entry file', () => {
+    const root = makeRoot()
+    mkdirSync(join(root, 'packages', 'group', 'one'), { recursive: true })
+    writeFileSync(join(root, 'packages', 'group', 'one', 'package.json'), JSON.stringify({ name: '@fix/one' }))
+    expect(() => collectConfigCatalog(root)).toThrow(/entry .* is missing or unreadable/)
+  })
+
+  it('hard-errors on a package.json without a name', () => {
+    const root = makeRoot()
+    mkdirSync(join(root, 'packages', 'group', 'one', 'src'), { recursive: true })
+    writeFileSync(join(root, 'packages', 'group', 'one', 'package.json'), '{}')
+    expect(() => collectConfigCatalog(root)).toThrow(/has no "name"/)
+  })
+})
+
+describe('gen-config-catalog config extraction guards', () => {
+  it('hard-errors on a config field with no JSDoc prose', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+export interface Config {
+  knob?: string
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config field 'Config\.knob' .* has no JSDoc prose/)
+  })
+
+  it('hard-errors on an undocumented field nested in a type literal', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: {
+    id: string
+  }[]
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config field 'Config\.entries\.id' .* has no JSDoc prose/)
+  })
+
+  it('pastes a package-local type transitively and records external refs', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { Mode } from './types.ts'
+import type { Remote } from '@fix/dep'
+/** Fixture config. */
+export interface Config {
+  /** The mode. */
+  mode?: Mode
+  /** The remote. */
+  remote?: Remote
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+      'src/types.ts': '/** Fixture mode. */\nexport type Mode = \'a\' | \'b\'\n',
+    }))
+    expect(entries[0]?.pastes?.map(p => p.source)).toEqual([
+      'packages/group/one/src/index.ts:5',
+      'packages/group/one/src/types.ts:2',
+    ])
+    expect(entries[0]?.refs).toEqual([{ alias: 'Remote', imported: 'Remote', specifier: '@fix/dep' }])
+  })
+
+  it('hard-errors on a referenced type name that resolves nowhere', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture config. */
+export interface Config {
+  /** The ghost. */
+  ghost?: Ghost
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/references 'Ghost' .* neither declared in the package, imported, nor a known global/)
+  })
+
+  it('hard-errors on a config type imported from another package', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { Config } from '@fix/dep'
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config type 'Config' is imported from '@fix\/dep'/)
+  })
+
+  it('hard-errors when one name resolves to two different declarations across the closure', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { A } from './a.ts'
+import type { B } from './b.ts'
+/** Fixture config. */
+export interface Config {
+  /** A. */
+  a?: A
+  /** B. */
+  b?: B
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+      'src/a.ts': '/** First Option. */\nexport interface Option {\n  /** X. */\n  x?: string\n}\n/** A. */\nexport interface A {\n  /** O. */\n  o?: Option\n}\n',
+      'src/b.ts': '/** Second Option. */\nexport interface Option {\n  /** Y. */\n  y?: string\n}\n/** B. */\nexport interface B {\n  /** O. */\n  o?: Option\n}\n',
+    }))).toThrow(/type name 'Option' resolves to two different declarations/)
+  })
+})
+
+describe('gen-config-catalog schema cross-check', () => {
+  it('accepts a chained schema whose keys all appear on the config type', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+export const Config: z<Config> = z.object({ knob: z.string() }).default({})
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries[0]?.schemaKeys).toEqual(['knob'])
+  })
+
+  it('hard-errors on a schema key the config type does not declare', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+export const Config: z<Config> = z.object({ knob: z.string(), hidden: z.number() })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/schema validates key 'hidden' but config type 'Config' declares no such member/)
+  })
+
+  it('hard-errors on a NESTED schema key the config type does not declare', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: {
+    /** Id. */
+    id: string
+  }[]
+}
+export const Config: z<Config> = z.object({ entries: z.array(z.object({ id: z.string(), ghost: z.string() })) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/schema validates key 'entries\[\]\.ghost'/)
+  })
+
+  it('resolves nested keys through a workspace-imported intersection part (re-export chains included)', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/dep', '@fix/dep', {
+      'src/index.ts': 'export * from \'./types.ts\'\n',
+      'src/types.ts': '/** Shared options. */\nexport interface Opts {\n  /** Model. */\n  model?: string\n}\n',
+    })
+    writePkg(root, 'group/one', '@fix/one', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Opts } from '@fix/dep'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: (Opts & {
+    /** Id. */
+    id: string
+  })[]
+}
+export const Config: z<Config> = z.object({ entries: z.array(z.object({ id: z.string(), model: z.string() })) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).not.toThrow()
+  })
+
+  it('resolves nested keys through a Partial<> wrapper', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Caps. */
+export interface Caps {
+  /** X. */
+  x?: boolean
+}
+/** Fixture config. */
+export interface Config {
+  /** Capabilities. */
+  capabilities?: Partial<Caps>
+}
+export const Config: z<Config> = z.object({ capabilities: z.object({ x: z.boolean() }) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).not.toThrow()
+  })
+
+  it('leaves a nested key under an external (unresolvable) type unreported', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { External } from 'some-external-pkg'
+/** Fixture config. */
+export interface Config {
+  /** Options. */
+  options?: External
+}
+export const Config: z<Config> = z.object({ options: z.object({ whatever: z.string() }) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).not.toThrow()
+  })
+
+  it('folds an intersected workspace schema into the subset check', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Leaf knob. */
+  leaf?: string
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ leaf: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf from '@fix/leaf'
+/** Bundle config. */
+export interface Config {
+  /** Forwarded leaf knob. */
+  leaf?: string
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    const entries = collectConfigCatalog(root)
+    expect(entries.find(e => e.pkg === '@fix/bundle')?.schemaComposes).toEqual(['@fix/leaf'])
+  })
+
+  it('resolves composed nested keys through an indexed-access forwarder', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Agents. */
+  agents: {
+    /** Id. */
+    id: string
+  }[]
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ agents: z.array(z.object({ id: z.string() })) }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf, { type Config as LeafConfig } from '@fix/leaf'
+/** Bundle config forwarding the leaf's agents list. */
+export interface Config {
+  /** Forwarded agents list. */
+  agents?: LeafConfig['agents']
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).not.toThrow()
+  })
+
+  it('hard-errors when an intersected schema key is missing from the bundle config type', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Leaf knob. */
+  leaf?: string
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ leaf: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf from '@fix/leaf'
+/** Bundle config that forgot to declare the forwarded field. */
+export interface Config {
+  /** Unrelated. */
+  other?: string
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).toThrow(/schema validates key 'leaf' but config type 'Config' declares no such member/)
+  })
+})
+
+describe('gen-config-catalog render', () => {
+  it('renders sections, fences, and the terse classification lists', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/one', '@fix/one', {
+      'src/index.ts': `import type { Context } from 'cordis'
+${DOCUMENTED_CONFIG}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    writePkg(root, 'group/lib', '@fix/lib', { 'src/index.ts': 'export const helper = 1\n' })
+    writePkg(root, 'group/seam', '@fix/seam', {
+      'src/index.ts': 'export default abstract class Seam { abstract run(): void }\n',
+    })
+    const page = render(collectConfigCatalog(root))
+    expect(page).toContain('## `@fix/one`')
+    expect(page).toContain('```ts config-catalog')
+    expect(page).toContain('/** A knob. */')
+    expect(page).toContain('- `@fix/lib` ([`packages/group/lib/src/index.ts`](../packages/group/lib/src/index.ts))')
+    expect(page).toContain('- `@fix/seam` — abstract `Seam`')
+  })
+})
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -32,6 +32,7 @@ declare module 'cordis' {
 export interface Config {
  /** Agents created from configuration at startup. */
  agents: (AgentOptions & {
+    /** Agent id to register under; also seeds the fresh per-run session id (`${id}-session-<uuid>`). */
    id: AgentId
    /**
     * If set, the config agent RESUMES this persisted session id instead of
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -54,7 +54,7 @@ The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`)

 ### Session event vocabulary (`types.ts`)

-The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog/log-events.md). Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
+The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.

 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, the hook bridges' `hook/*`); merged members appear in the same catalog.

--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -8,7 +8,7 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex

 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. Disposed with the calling fiber.
 - `ctx.tools.get(name: string): ToolDefinition | undefined`
- `ctx.tools.schemas(): ToolSchema[]` Schemas of all registered tools (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog/tools.md](../../../docs/tool-catalog/tools.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
+- `ctx.tools.schemas(): ToolSchema[]` Schemas of all registered tools (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.execute(exec: ToolExecution): Promise<ToolExecutionResult>` Execute one tool call through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline.

 ### Injected services
--- a/packages/hooks/README.md
+++ b/packages/hooks/README.md
@@ -4,7 +4,7 @@ The hooks subsystem lets users extend the agent at lifecycle points the way Clau

 | Package | Role | Shape |
 |---|---|---|
-| `hook-protocol/` | Shared wire-protocol core: matcher primitive, exit-code/stdout codec, `runHook` (via `ctx.bash`), most-restrictive merge, `hook/*` session events | library (no plugin) |
+| `hook-protocol/` | Shared wire-protocol core: matcher primitive, exit-code/stdout codec, `runHook` (via `ctx.bash`), most-restrictive merge, `hook/*` session events, detached-run quiescence | library (no plugin) |
 | `hooks-claude/` | Bridge for a Claude Code `hooks.json` / settings | plugin |
 | `hooks-codex/` | Bridge for a Codex `hooks.json` | plugin |

--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -13,6 +13,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 | Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto a seam-specific typed Decision |
 | Merge N hooks | `mergeHookOutputs(outputs)` → most-restrictive `MergedHookOutcome` | — |
 | Durable record | `appendHookInvoked` / `appendHookResult` (`hook/*` session events; the result's `decision`/`stderrSummary` derive from the `HookOutput` here) | calls them around each invocation |
+| Detached-run quiescence | `createDetachedRuns()` — track fire-and-forget run chains; `drain()` aborts, then awaits them | passes `signal` to each detached `runHook`, registers `drain` as its effect disposer |

 ## Primitives

@@ -20,10 +21,11 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 - **`runHook(bash, hook, options, now)`** — serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** — the exit-code + structured-stdout codec. Exit `0` → parse JSON stdout (lenient: non-JSON is left for the bridge); exit `2` → blocking error, `stderr` is the block reason (surfaced as `decision: 'block'`); other → non-blocking error. `hookSpecificOutput.permissionDecision` (allow/deny/ask) overrides a legacy top-level `decision`; `additionalContext`/`updatedInput`/`systemMessage`/`continue`/`stopReason` are parsed too. The schemas key the `hookSpecificOutput` block by `hookEventName`, so passing `expectedEventName` (the firing event) DISCARDS a block whose `hookEventName` names a different event — or omits it entirely — its event-scoped fields don't take effect (a `PreToolUse` block on a `Stop` hook is malformed, and so is a discriminator-less block that would otherwise apply to any event), while the event-agnostic top-level fields still apply. Pure and total.
 - **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
+- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no seam awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).

 ## `hook/*` session events

-Declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT a `SurfaceEventType`, no `surfaceOp`): `hook/invoked` (a hook command ran) and `hook/result` (its outcome, paired by `handlerId`, with `appendHookResult` owning the decision rule). Payloads and per-event JSDoc are in the generated [persistence log event catalog](../../../docs/persistence-catalog/log-events.md); `stderrSummary` is truncated to the record's `stderrSummaryMaxChars` (the bridge's config, reference default `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500; omitted when empty).
+Declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT a `SurfaceEventType`, no `surfaceOp`): `hook/invoked` (a hook command ran) and `hook/result` (its outcome, paired by `handlerId`, with `appendHookResult` owning the decision rule). Payloads and per-event JSDoc are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md); `stderrSummary` is truncated to the record's `stderrSummaryMaxChars` (the bridge's config, reference default `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500; omitted when empty).

 Like every event they must sit inside an open turn. The mid-turn points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/`Stop`) fire inside the loop's open turn by construction; `SessionStart` gets no `hook/*` record (its injected `context/message` is the durable evidence) — see the hooks RFC.

--- a/packages/hooks/hook-protocol/src/detached.ts
+++ b/packages/hooks/hook-protocol/src/detached.ts
@@ -0,0 +1,71 @@
+/**
+ * Quiescence tracking for a bridge's DETACHED hook runs. The waterfall-shaped
+ * hook points (`UserPromptSubmit`, `PreToolUse`, …) are awaited by their seams,
+ * but the emit-shaped points (`SessionStart`, `SubagentStart`, `SubagentStop`)
+ * run fire-and-forget: no seam awaits them, so without tracking a bridge's
+ * disposal could strand a live hook process and let a late continuation fire
+ * into a disposed context (docs/defensive-patterns.md: dispose must reach
+ * quiescence). A bridge creates one tracker in `apply()`, passes
+ * {@link DetachedRuns.signal} to each detached {@link runHook} call, wraps the
+ * full run chain (the hook run PLUS its `.then` continuation) in
+ * {@link DetachedRuns.track}, and registers {@link DetachedRuns.drain} as its
+ * disposer.
+ *
+ * @module @deepseek-ai/dsh-hook-protocol/detached
+ */
+
+/** In-flight registry for one bridge's detached hook runs; see the module doc for the wiring contract. */
+export interface DetachedRuns {
+  /**
+   * The abort signal every tracked run must hand to {@link runHook} (via its
+   * `signal` option). {@link drain} fires it so a still-running hook process is
+   * killed rather than awaited out to its timeout (default 10 minutes).
+   */
+  readonly signal: AbortSignal
+  /**
+   * Register one detached run until it settles. Pass the FULL chain — the hook
+   * run and its continuation/error handler — so {@link drain} waits for the
+   * side effects (an inject, a warn), not just the process exit. A rejected
+   * chain is absorbed here (settlement bookkeeping only), but rejection
+   * handling is still the caller's job: an untracked `.catch` is what turns a
+   * failure into a logged warning instead of silence.
+   * @param run - the detached run chain to hold until settled.
+   */
+  track(run: Promise<unknown>): void
+  /**
+   * Abort {@link signal}, then resolve once every tracked chain has settled —
+   * including chains tracked while the drain is in progress. The bridge
+   * registers this as its effect disposer; cordis awaits it, so
+   * `fiber.dispose()` resolving means the bridge's detached work is quiescent.
+   * A run tracked AFTER drain resolves is not awaited by anyone — by then the
+   * bridge's listeners are disposed, so nothing can start one.
+   * @returns resolves when all tracked runs have settled.
+   */
+  drain(): Promise<void>
+}
+
+/**
+ * Create a {@link DetachedRuns} tracker (one per bridge `apply()`); settled
+ * runs are pruned so a long-lived session does not accumulate them.
+ * @returns the tracker.
+ */
+export function createDetachedRuns(): DetachedRuns {
+  const inflight = new Set<Promise<unknown>>()
+  const controller = new AbortController()
+  return {
+    signal: controller.signal,
+    track(run: Promise<unknown>): void {
+      inflight.add(run)
+      const settled = (): void => { inflight.delete(run) }
+      void run.then(settled, settled)
+    },
+    async drain(): Promise<void> {
+      controller.abort(new Error('hook bridge disposed'))
+      // Re-check after each wave: a chain can be tracked while a prior wave is
+      // settling; loop until the registry is observed empty.
+      while (inflight.size > 0) {
+        await Promise.allSettled([...inflight])
+      }
+    },
+  }
+}
--- a/packages/hooks/hook-protocol/src/index.ts
+++ b/packages/hooks/hook-protocol/src/index.ts
@@ -15,6 +15,8 @@
 *   session-event helpers (declaration-merged into `SessionEventMap`);
 *   `appendHookResult` derives the durable `decision`/`stderrSummary` from the
 *   {@link HookOutput} so the shared event's semantics live in one place.
+ * - {@link createDetachedRuns} — quiescence tracking for the fire-and-forget
+ *   hook points: disposal aborts and drains a bridge's detached runs.
 *
 * Each bridge owns what genuinely DIFFERS: building the per-event stdin payload
 * (CC vs Codex field sets), the dialect's env/substitution, and mapping the
@@ -38,3 +40,5 @@ export { mergeHookOutputs } from './merge.ts'
 export type { MergedDecision, MergedHookOutcome } from './merge.ts'
 export { appendHookInvoked, appendHookResult, DEFAULT_STDERR_SUMMARY_MAX_CHARS, summarizeStderr } from './events.ts'
 export type { HookInvocation, HookResultRecord } from './events.ts'
+export { createDetachedRuns } from './detached.ts'
+export type { DetachedRuns } from './detached.ts'
--- a/packages/hooks/hook-protocol/tests/detached.spec.ts
+++ b/packages/hooks/hook-protocol/tests/detached.spec.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { createDetachedRuns } from '@deepseek-ai/dsh-hook-protocol'
+
+/** A promise settled from outside, so a test controls exactly when a tracked run finishes. */
+function deferred(): { promise: Promise<void>; resolve: () => void; reject: (error: Error) => void } {
+  let resolve!: () => void
+  let reject!: (error: Error) => void
+  const promise = new Promise<void>((res, rej) => { resolve = res; reject = rej })
+  return { promise, resolve, reject }
+}
+
+describe('createDetachedRuns', () => {
+  it('starts with an unfired signal; drain fires it (so still-running hook processes get killed)', async () => {
+    const detached = createDetachedRuns()
+    expect(detached.signal.aborted).toBe(false)
+    await detached.drain()
+    expect(detached.signal.aborted).toBe(true)
+    expect(String(detached.signal.reason)).toContain('hook bridge disposed')
+  })
+
+  it('drain with nothing tracked resolves immediately', async () => {
+    await expect(createDetachedRuns().drain()).resolves.toBeUndefined()
+  })
+
+  it('drain waits for a tracked run to settle', async () => {
+    const detached = createDetachedRuns()
+    const run = deferred()
+    detached.track(run.promise)
+    let drained = false
+    const draining = detached.drain().then(() => { drained = true })
+    // Give the drain every chance to (wrongly) resolve before the run settles.
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(drained).toBe(false)
+    run.resolve()
+    await draining
+    expect(drained).toBe(true)
+  })
+
+  it('drain waits for a run tracked WHILE a prior wave was settling', async () => {
+    const detached = createDetachedRuns()
+    const first = deferred()
+    const second = deferred()
+    detached.track(first.promise)
+    // The late run enters the registry from the first run's own continuation —
+    // after drain() snapshotted its first wave.
+    void first.promise.then(() => { detached.track(second.promise) })
+    let drained = false
+    const draining = detached.drain().then(() => { drained = true })
+    first.resolve()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(drained).toBe(false)
+    second.resolve()
+    await draining
+    expect(drained).toBe(true)
+  })
+
+  it('a rejected tracked run is absorbed by the settlement bookkeeping (drain still resolves)', async () => {
+    const detached = createDetachedRuns()
+    const run = deferred()
+    detached.track(run.promise)
+    // The caller-side handler every bridge attaches; the tracker's own
+    // bookkeeping must not depend on it, but an UNHANDLED rejection would fail
+    // the test run, which is exactly the guarantee under test.
+    run.promise.catch(() => {})
+    run.reject(new Error('hook run boom'))
+    await expect(detached.drain()).resolves.toBeUndefined()
+  })
+})
--- a/packages/hooks/hooks-claude/README.md
+++ b/packages/hooks/hooks-claude/README.md
@@ -42,6 +42,8 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco
 | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into the live child |
 | `SubagentStop` | `subagent/end` (emit) | observe-only |

+The three emit points run detached — no seam awaits a `SessionStart`/`SubagentStart`/`SubagentStop` hook. Each run chain is tracked, and disposing the bridge aborts still-running hook processes, then drains the continuations before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
+
 The matcher subject is the tool name (`PreToolUse`/`PostToolUse`), the session source (`SessionStart`), or a constant `agent_type` of `general-purpose` (`SubagentStart`/`SubagentStop` — the harness subagent seam carries no per-kind label, so the bridge reports Claude Code's own Task-tool default; a default/`*`/empty `agent_type` matcher fires, a specific-kind matcher does not); `UserPromptSubmit`/`Stop` ignore matchers. Multiple file-configured hooks on one point run **serially, in config order**, and fold most-restrictively (`deny > ask > allow`, see `dsh-hook-protocol`); serial keeps each hook's `hook/invoked`/`hook/result` pair adjacent in the log, and the fold is order-independent for the decision (see the RFC's "run serially, not concurrently" note).

 ## Context source
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -31,6 +31,7 @@ import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionRes
 import {
  appendHookInvoked,
  appendHookResult,
+  createDetachedRuns,
  DEFAULT_HOOK_TIMEOUT_MS,
  DEFAULT_STDERR_SUMMARY_MAX_CHARS,
  matchesMatcher,
@@ -128,6 +129,14 @@ export function apply(ctx: Context, config: Config): void {
    return
  }

+  // --- The emit-shaped points (SessionStart, SubagentStart, SubagentStop) run
+  // detached — no seam awaits them — so every run chain is tracked and disposal
+  // aborts still-running hook processes, then drains the continuations
+  // (docs/defensive-patterns.md: dispose must reach quiescence). After the parse
+  // gate: a bridge that registered nothing has nothing to drain. ---
+  const detached = createDetachedRuns()
+  ctx.effect(() => () => detached.drain(), 'hooks-claude: drain detached hook runs')
+
  /**
   * Run every command hook configured for `point` whose matcher selects
   * `matchQuery`, with the per-event `payload` on stdin, and fold the results.
@@ -237,14 +246,14 @@ export function apply(ctx: Context, config: Config): void {
  // to the interception seams; today the contract is "injected as soon as the
  // hook resolves", not "before the first request". ---
  ctx.on('agent/session-start', (agent, source) => {
-    void runPoint('SessionStart', source, sessionStartPayload(agent, source), { agent })
+    detached.track(runPoint('SessionStart', source, sessionStartPayload(agent, source), { agent, signal: detached.signal })
      .then((merged) => {
        const context = contextFrom(merged)
        if (context) agent.inject(context.content, { source: context.source })
      })
      .catch((error: unknown) => {
        ctx.logger.warn(`hooks-claude: SessionStart hook failed: ${String(error)}`)
-      })
+      }))
  })

  // --- UserPromptSubmit → PromptDecision. The prompt text is the payload; no
@@ -330,12 +339,12 @@ export function apply(ctx: Context, config: Config): void {
  // a specific-kind matcher does not (documented in the RFC). ---
  ctx.on('subagent/start', (info) => {
    const child = ctx.get('agents')?.get(info.id)
-    void runPoint('SubagentStart', SUBAGENT_TYPE, subagentPayload('SubagentStart', info, child), { ...child ? { agent: child } : {} })
+    detached.track(runPoint('SubagentStart', SUBAGENT_TYPE, subagentPayload('SubagentStart', info, child), { ...child ? { agent: child } : {}, signal: detached.signal })
      .then((merged) => {
        const context = contextFrom(merged)
        if (context && child) child.inject(context.content, { source: context.source })
      })
-      .catch((error: unknown) => { ctx.logger.warn(`hooks-claude: SubagentStart hook failed: ${String(error)}`) })
+      .catch((error: unknown) => { ctx.logger.warn(`hooks-claude: SubagentStart hook failed: ${String(error)}`) }))
  })
  ctx.on('subagent/end', (info) => {
    // Look up the child (still recoverable: `subagent/end` fires from the
@@ -343,9 +352,10 @@ export function apply(ctx: Context, config: Config): void {
    // disposes it) so the hook runs in the child's cwd, not the server default.
    // No `.then`/inject follows (SubagentStop only observes), and no `turn` is
    // passed (so no `hook/*` log records), so runPoint has nothing that can
-    // reject — no `.catch` is needed. Fire-and-forget.
+    // reject — no `.catch` is needed (the tracker's settlement bookkeeping
+    // would absorb one anyway).
    const child = ctx.get('agents')?.get(info.id)
-    void runPoint('SubagentStop', SUBAGENT_TYPE, subagentPayload('SubagentStop', info, child), { ...child ? { agent: child } : {} })
+    detached.track(runPoint('SubagentStop', SUBAGENT_TYPE, subagentPayload('SubagentStop', info, child), { ...child ? { agent: child } : {}, signal: detached.signal }))
  })
 }

--- a/packages/hooks/hooks-claude/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-claude/tests/bridge.spec.ts
@@ -1,8 +1,8 @@
-import { afterEach, describe, expect, it } from 'vitest'
-import { mkdtempSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { Context } from 'cordis'
+import { Context, type Fiber } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { type SessionEvent } from '@deepseek-ai/dsh-session'
@@ -39,6 +39,11 @@ function writeConfig(hooks: unknown, scripts: Record<string, string> = {}): stri
 }

 async function harness(configDir: string, adapter: MockAdapter): Promise<Context> {
+  return (await harnessWithFiber(configDir, adapter)).ctx
+}
+
+/** {@link harness}, also exposing the bridge's fiber for tests that dispose it. */
+async function harnessWithFiber(configDir: string, adapter: MockAdapter): Promise<{ ctx: Context; hooks: Fiber }> {
  const ctx = new Context()
  await ctx.plugin(LlmService)
  await ctx.plugin(SessionStore)
@@ -47,9 +52,9 @@ async function harness(configDir: string, adapter: MockAdapter): Promise<Context
  await ctx.plugin(AgentRegistry)
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
-  await ctx.plugin(HooksClaude, { configPath: join(configDir, 'hooks.json') })
+  const hooks = await ctx.plugin(HooksClaude, { configPath: join(configDir, 'hooks.json') })
  ctx.llm.registerAdapter(['mock'], adapter)
-  return ctx
+  return { ctx, hooks }
 }

 function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
@@ -285,19 +290,59 @@ describe('hooks-claude bridge — SubagentStart / SubagentStop (observe)', () =>
    } }))

    const adapter = new MockAdapter([])
-    const ctx = await harness(dir, adapter)
+    const { ctx, hooks } = await harnessWithFiber(dir, adapter)
    // Drive the observe-only lifecycle events directly (no real child needed — the
-    // bridge just listens). The agents registry is absent here, so SubagentStart's
+    // bridge just listens). No child agent is registered, so SubagentStart's
    // child lookup yields undefined and it simply runs the hook.
    ctx.emit('subagent/start', { provider: 'inproc', id: AgentId('child-1') })
    ctx.emit('subagent/end', { provider: 'inproc', id: AgentId('child-1'), stopReason: 'completed', lastAssistantMessage: [{ type: 'text', text: 'done' }] })

    // Both hooks run async (detached .then); poll for their marker files rather
    // than a fixed sleep that flakes under load.
-    const { existsSync } = await import('node:fs')
    await waitFor(() => existsSync(startMarker) && existsSync(stopMarker))
    expect(existsSync(startMarker)).toBe(true)
    expect(existsSync(stopMarker)).toBe(true)
+    // The markers prove the hook PROCESSES ran, not that the detached `.then`
+    // continuations did (`touch` lands before the process exits). Dispose drains
+    // them, so the no-context arm of the SubagentStart continuation — covered
+    // only here — executes before this file's coverage snapshot instead of
+    // racing it (the arm went uncovered on a loaded CI runner and failed the
+    // per-file 100% branch gate).
+    await hooks.dispose()
+  })
+
+  it('disposing the bridge aborts a still-running hook and drains to quiescence', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const pidFile = join(dir, 'pid')
+    const marker = join(dir, 'started')
+    const slowHook = join(dir, 'slow.sh')
+    // Record the hook shell's PID and touch the marker FIRST so the test can
+    // tell "the hook is genuinely mid-run", then sleep far past the suite
+    // timeout. Dispose must KILL the process (the tracker's abort signal), not
+    // await its exit or its 10-minute default hook timeout.
+    writeFileSync(slowHook, `#!/usr/bin/env bash\necho $$ > "${pidFile}"\ntouch "${marker}"\nsleep 30\n`)
+    chmodSync(slowHook, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: {
+      SubagentStart: [{ hooks: [{ type: 'command', command: slowHook }] }],
+    } }))
+
+    const { ctx, hooks } = await harnessWithFiber(dir, new MockAdapter([]))
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    ctx.emit('subagent/start', { provider: 'inproc', id: AgentId('child-1') })
+    await waitFor(() => existsSync(marker))
+    const pid = Number(readFileSync(pidFile, 'utf8').trim())
+    await hooks.dispose()
+    // Quiescence, not just promptness: the drain resolves only after the run
+    // settled, and the run settles only after the killed process was reaped —
+    // so by the time dispose returns, the PID must be GONE (kill(pid, 0)
+    // throws ESRCH). An untracked fire-and-forget regression would leave the
+    // process alive (or unreaped) and fail this deterministically.
+    expect(() => process.kill(pid, 0)).toThrow()
+    // The aborted run resolves as a non-blocking error (runHook never rejects),
+    // so the drained continuation must NOT have logged a failure.
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('SubagentStart hook failed'))
  })
 })

--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -48,6 +48,8 @@ The hooks themselves run in the agent's session workspace: for the agent-scoped

 A tool call's payload carries the real `tool_name` (the same value the matcher tests) and Codex's `tool_input: { command }` shape (the `command` arg when present, else `''`). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`) or the session source (`SessionStart`); `UserPromptSubmit`/`Stop` ignore matchers.

+`SessionStart` — the one emit point — runs detached; each run chain is tracked, and disposing the bridge aborts a still-running hook process, then drains the continuation before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
+
 ## Context source

 Injected context carries an explicit `{ kind: 'plugin', plugin: 'hooks-codex' }` source (`agent.inject()` would otherwise default it to `{ kind: 'user' }`).
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -24,6 +24,7 @@ import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionRes
 import {
  appendHookInvoked,
  appendHookResult,
+  createDetachedRuns,
  DEFAULT_HOOK_TIMEOUT_MS,
  DEFAULT_STDERR_SUMMARY_MAX_CHARS,
  matchesMatcher,
@@ -97,6 +98,12 @@ export function apply(ctx: Context, config: Config): void {

  const model = config.model ?? ''

+  // SessionStart is the one emit-shaped (detached) point Codex has: track its
+  // run chains so disposal aborts a still-running hook process and drains the
+  // continuation (docs/defensive-patterns.md: dispose must reach quiescence).
+  const detached = createDetachedRuns()
+  ctx.effect(() => () => detached.drain(), 'hooks-codex: drain detached hook runs')
+
  async function runPoint(
    point: string,
    matchQuery: string,
@@ -189,12 +196,12 @@ export function apply(ctx: Context, config: Config): void {
  // the model (a slow hook can miss the first request). Gating is a deferred
  // loop-level change; the contract is "injected as soon as the hook resolves".
  ctx.on('agent/session-start', (agent, source) => {
-    void runPoint('SessionStart', source, { ...base(agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true })
+    detached.track(runPoint('SessionStart', source, { ...base(agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true, signal: detached.signal })
      .then((merged) => {
        const context = contextFrom(merged)
        if (context) agent.inject(context.content, { source: context.source })
      })
-      .catch((error: unknown) => { ctx.logger.warn(`hooks-codex: SessionStart hook failed: ${String(error)}`) })
+      .catch((error: unknown) => { ctx.logger.warn(`hooks-codex: SessionStart hook failed: ${String(error)}`) }))
  })

  // UserPromptSubmit → PromptDecision. Codex can only BLOCK (no allow/ask).
--- a/packages/hooks/hooks-codex/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-codex/tests/bridge.spec.ts
@@ -1,5 +1,5 @@
-import { afterEach, describe, expect, it } from 'vitest'
-import { mkdtempSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
@@ -62,6 +62,15 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
 }
 function events(agent: ReactLoopAgent): SessionEvent[] { return [...agent.session.events] }

+/** Poll `predicate` until true or the deadline passes (detached hook effects can't be awaited directly). */
+async function waitFor(predicate: () => boolean, timeout = 5000, interval = 10): Promise<void> {
+  const deadline = Date.now() + timeout
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error('waitFor: condition not met before deadline')
+    await new Promise(r => setTimeout(r, interval))
+  }
+}
+
 describe('hooks-codex bridge', () => {
  it('a PreToolUse hook (exit 2) denies a tool the regex matcher matches as a substring', async () => {
    const dir = configDir()
@@ -159,6 +168,43 @@ describe('hooks-codex bridge', () => {
    expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false) // no hook ran
  })

+  it('disposing the bridge aborts a still-running SessionStart hook and drains to quiescence', async () => {
+    const dir = configDir()
+    const pidFile = join(dir, 'pid')
+    const marker = join(dir, 'started')
+    // Record the hook shell's PID and touch the marker FIRST so the test can
+    // tell "the hook is genuinely mid-run", then sleep far past the suite
+    // timeout. Dispose must KILL the process (the tracker's abort signal wired
+    // through this bridge's runPoint), not await its exit.
+    const slow = script(dir, 'slow.sh', `#!/usr/bin/env bash\necho $$ > "${pidFile}"\ntouch "${marker}"\nsleep 30\n`)
+    writeHooks(dir, { SessionStart: [{ hooks: [{ type: 'command', command: slow }] }] })
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+    const fiber = await ctx.plugin(HooksCodex, { configPath: join(dir, 'hooks.json'), model: 'm' })
+    ctx.llm.registerAdapter(['mock'], new MockAdapter([]))
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) // fires agent/session-start
+    await waitFor(() => existsSync(marker))
+    const pid = Number(readFileSync(pidFile, 'utf8').trim())
+    await fiber.dispose()
+    // Quiescence, not just promptness: the drain resolves only after the run
+    // settled, and the run settles only after the killed process was reaped —
+    // so by the time dispose returns, the PID must be GONE (kill(pid, 0)
+    // throws ESRCH). An untracked fire-and-forget regression would leave the
+    // process alive (or unreaped) and fail this deterministically.
+    expect(() => process.kill(pid, 0)).toThrow()
+    // The aborted run resolves as a non-blocking error (runHook never rejects),
+    // so the drained continuation must NOT have logged a failure.
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('SessionStart hook failed'))
+  })
+
  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/apply', () => {
    expect('default' in HooksCodex).toBe(false)
    expect(HooksCodex.name).toBe('hooks-codex')
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -6,7 +6,7 @@ Its consumer is the ACP snapshot harness in `examples/acp-agent`, which loads th

 ## How the fixture works

-The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each `stream()` call's chunk sequence (one model call per loop step). Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record.
+The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each `stream()` call's chunk sequence (one model call per loop step). Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness pins that content in one scenario and scrubs the rest); replay is indifferent — derivation reads only `assistant/chunk` events and the line-0 session header.

 Two failure modes are not reconstructable from `assistant/chunk` alone — a pure throw before any chunk (e.g. an HTTP 401, where the log holds only a `turn/end {error}` and no chunks) and a cancel/hang (timing, not chunk content). A scenario that needs those supplies an optional sidecar (`<scenario>/replay.override.json`: a `ReplayEntry[]`) that REPLACES the derived script.

--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -12,7 +12,11 @@
 * `(turn, step)` reconstructs each `stream()` call's chunk sequence (one model
 * call per loop step — see packages/core/agent-loop/src/loop.ts). Recording is
 * therefore "run the real agent once and harvest the `.jsonl`", done by the
- * snapshot harness — this plugin does not record.
+ * snapshot harness — this plugin does not record. A fixture may carry its
+ * `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness
+ * pins that content in one scenario and scrubs the rest); replay is
+ * indifferent — derivation reads ONLY `assistant/chunk` events and the line-0
+ * session header.
 *
 * A NESTED-agent scenario records more than one log: the parent plus one per
 * in-process subagent (each subagent runs as its own {@link Session} on the same