Merge remote-tracking branch 'origin/master' into codex/agent-session-jsonl-location

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/bash.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
#	docs/rfc/implemented/feature/2026-06-30-hook-bridges.md
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
#	examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
#	examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
#	examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
#	examples/acp-agent/tests/snapshots/skill-load/session.jsonl
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl
#	packages/bash/bash-local/README.md
#	packages/bash/bash-local/src/run.ts
#	packages/bash/bash-local/tests/run.spec.ts
#	packages/bash/bash/README.md
#	packages/bash/tool-bash/README.md
#	packages/bash/tool-bash/src/index.ts
#	packages/bash/tool-bash/tests/tools.spec.ts
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/agent-core/src/index.ts
#	packages/session-persistence/session-persistence-jsonl/src/index.ts
#	packages/session-persistence/session-persistence-sqlite/src/index.ts
#	packages/session-persistence/session-persistence/README.md
#	packages/session-persistence/session-persistence/src/index.ts
#	packages/ui/acp-agent/README.md
#	packages/ui/stdio-agent/README.md

packages/session-persistence/session-persistence/tests/contract.ts

@@ -43,15 +43,9 @@ export function oneTurnLog(): SessionEvent[] {
 }
 
 /**
- * Append a whole event log to a LIVE session, event by event, forwarding the
- * surface metadata each event already carries. A bare `append(e.type, e.data)`
- * over a `SessionEvent[]` widens the type argument to the union, where the
- * typed overload's mandatory-marker rule collapses to optional — and `append`'s
- * runtime guard then rejects a surface-eligible event with no marker. This
- * helper forwards the `surfaceOp`/`sourceEventSeqs` VERBATIM from the source
- * event (it does not synthesize a default), so a well-formed recorded log
- * round-trips through a live session intact and a fixture that forgot a marker
- * still trips the guard.
+ * Append recorded events to a live session while forwarding surface metadata verbatim. The broad
+ * `SessionEvent` union makes the typed marker optional, but the runtime guard must still reject a
+ * surface event whose fixture omitted it; this helper never synthesizes a default.
  */
 export function appendLog(session: Session, events: readonly SessionEvent[]): void {
   for (const e of events) {
@@ -222,10 +216,10 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
     it('append rejects non-JSON-serializable event data, naming the event type', async () => {
       const { persistence, dispose } = await make()
       try {
-        // Every value `isJsonValue` rejects must be rejected by the backend, not
-        // just BigInt — otherwise a backend could pass this contract while still
-        // accepting values that corrupt the durable round-trip. Each is a
-        // plugin-added `extra` field on a single user/message (seq 0).
+        // Every value `isJsonValue` rejects must be rejected by the backend, not just BigInt —
+        // otherwise a backend could pass this contract while still accepting values that
+        // corrupt the durable round-trip. Each value is carried in a plugin-added field on one
+        // user message so the contract covers the complete JSON-value boundary.
         const cyclic: Record<string, unknown> = { type: 'text', text: 'x' }
         cyclic['self'] = cyclic
         const badValues: unknown[] = [

packages/session-persistence/session-persistence/tests/coordinator-contract.ts

@@ -1,28 +1,11 @@
 /**
- * Reusable ORCHESTRATION suite for any backend that composes a
- * {@link PersistenceCoordinator}. Where {@link runPersistenceContract} (in
- * contract.ts) pins the public read/write SEMANTICS, this suite pins the
- * coordinator's WRITE-PATH ORCHESTRATION — the behavior that is identical across
- * every first-party backend because it lives in the shared coordinator, not in
- * the storage primitives: the `session/created` → `session/event` →
- * `session/flush` → dispose drain, lazy materialization, fork-seed persistence,
- * the four `onCreated` adoption cases (new / HMR-adopt / collision /
- * ownerless-claim), crash-tail repair on load, and dispose-time quiescence.
- *
- * A backend imports {@link runCoordinatorContract} and calls it with a
- * {@link CoordinatorFixture} factory that knows how to (a) mount the REAL
- * backend plugin on a {@link Context} over a SHARED storage scope (so HMR/reload
- * tests can dispose one instance and mount another over the same bytes/rows),
- * and (b) inject a never-committed torn tail for one session
- * ({@link CoordinatorFixture.corruptTail}) so the through-coordinator torn-tail
- * repair branch is exercised against real storage. The suite drives everything
- * through the PUBLIC {@link SessionPersistence} API + the cordis SessionStore
- * write path — never the storage primitives directly — so it runs unchanged for
- * every backend (memory / jsonl / sqlite).
- *
- * Each scenario lives here once and runs once per backend through the fixture;
- * the per-backend specs keep ONLY their storage-mechanics tests.
+ * Shared write-path orchestration contract for backends using {@link PersistenceCoordinator}.
+ * Unlike the public storage-semantics suite in `contract.ts`, it covers SessionStore event wiring,
+ * lazy creation, fork seed persistence, four adoption/collision cases, crash-tail repair, reload,
+ * flush, and disposal quiescence through public APIs rather than storage primitives.
  *
+ * Each real backend supplies a shared storage scope and optional torn-tail injector; backend specs
+ * retain only storage-mechanics tests, while these scenarios run once per backend.
  * @module @deepseek-ai/dsh-session-persistence/tests/coordinator-contract
  */
 
@@ -39,25 +22,12 @@ import { meta, oneTurnLog, appendLog } from './contract.ts'
  * the suite mounts/disposes backend instances on it and cleans it up at the end.
  */
 export interface CoordinatorFixture {
-  /**
-   * Mount the REAL backend plugin (via `ctx.plugin`, the Loader path) on `ctx`,
-   * over THIS fixture's shared storage scope. Returns the plugin fiber so the
-   * suite can dispose a single instance (HMR/reload) while the storage — and any
-   * still-live session in another fiber — survives. The caller has already
-   * mounted `SessionStore` on `ctx`.
-   */
+  /** Mount the real backend through `ctx.plugin` over shared storage and return only that fiber. */
   mount: (ctx: Context) => Promise<Fiber>
 
   /**
-   * Inject a NEVER-COMMITTED torn tail into the backend's storage for `id` at
-   * the given `cwd` (the cwd the session was created with): a half-written
-   * record past the committed region (JSONL: a partial line with no newline;
-   * SQLite: a row with invalid `data` JSON past the committed seq). This drives
-   * the coordinator's `loadCore` `tornMarker !== undefined` → `commitRepair`
-   * branch against real storage.
-   *
-   * OMITTED by a backend that structurally has no torn tails (memory): the
-   * torn-tail scenario then self-skips (asserted explicitly in the suite).
+   * Inject a never-committed partial record after the durable region so `loadCore` reaches
+   * `commitRepair`. Omit only when the backend structurally cannot produce torn tails.
    */
   corruptTail?: (id: SessionId, cwd: string | undefined) => Promise<void>
 
@@ -124,10 +94,9 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
     })
 
     it('round-trips the seed boundary (seedLength) through persistence', async () => {
-      // A forked child records how many leading events were inherited via the
-      // seed; the boundary must survive a reload (so a resume/replay can tell the
-      // inherited prefix from the child's own events). Both backends carry it on
-      // the header — JSONL on the header line, SQLite in the seed_length column.
+      // A forked child records how many leading events were inherited via the seed; the
+      // boundary must survive a reload (so a resume/replay can tell the inherited prefix from
+      // the child's own events). JSONL stores it in the header; SQLite uses `seed_length`.
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
@@ -213,10 +182,10 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
     })
 
     it('resume: a re-created session seeded with the loaded log does not re-append its seed and continues the seq', async () => {
+      // Separate backend lifecycles distinguish persisted-seed adoption from an in-memory continuation.
       const fix = await makeFixture()
       const first = await freshCtx(fix)
       try {
-        // First lifecycle: persist a session through the store.
         const s1 = first.ctx.sessions.create(SessionId('resumed'), { meta: { cwd: WORK } })
         send(s1, oneTurnLog())
         await first.ctx.parallel('session/flush', s1)
@@ -224,9 +193,6 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         await first.fiber.dispose()
       }
 
-      // Second lifecycle: a NEW backend instance + a session re-created with the
-      // same id SEEDED with the loaded events. onCreated adopts the stored log
-      // (does not re-persist the seed); a new turn appends at seq 6.
       const second = await freshCtx(fix)
       try {
         const loaded = await second.ctx.sessionPersistence.load(SessionId('resumed'))
@@ -237,7 +203,6 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         await second.ctx.parallel('session/flush', s2)
 
         const reloaded = await second.ctx.sessionPersistence.load(SessionId('resumed'))
-        // 6 original + 2 new, contiguous, no duplicated seed.
         expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
       } finally {
         await second.fiber.dispose()
@@ -304,10 +269,9 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
         await ctx.parallel('session/flush', session)
 
-        // Hot-reload: dispose instance 1, mount instance 2 over the SAME storage
-        // while the session stays live. Instance 2 has an empty states map but the
-        // log is materialized and is a prefix of the live events — it must ADOPT
-        // (not reject). A second turn appended after reload then persists.
+        // Hot-reload: dispose instance 1, mount instance 2 over the same storage while the
+        // session stays live. The new instance has no coordinator state but must adopt the
+        // materialized prefix, then persist another turn rather than rejecting it as a collision.
         await backend1.dispose()
         await fix.mount(ctx)
         session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -399,9 +363,9 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
         await first.fiber.dispose()
       }
 
-      // A FRESH backend + a NEW live session with the same id but NO explicit
-      // resume. onCreated treats it as new; create() rejects because a log already
-      // exists. The rejection surfaces via the init promise (flush awaits it).
+      // A fresh backend + a NEW live session with the same id but NO explicit resume. onCreated
+      // treats it as new; create() rejects because a log already exists, and `flush()` surfaces
+      // that initialization rejection.
       const second = await freshCtx(fix)
       try {
         const s2 = second.ctx.sessions.create(SessionId('collide'), { meta: { cwd: WORK } })

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -16,18 +16,10 @@ type MemoryStore = Map<string, { meta: SessionHeader; events: SessionEvent[] }>
 interface MemoryConfig { store?: MemoryStore }
 
 /**
- * A trivial in-memory {@link SessionPersistence} that composes a
- * {@link PersistenceCoordinator} over a dependency-free `Map`-backed
- * {@link PersistenceBackend}. It is BOTH the coordinator's reference vehicle
- * (the simplest possible storage — a `Map<id, {meta, events}>` with no torn
- * tails, so `tornMarker` is always undefined) and the cover for the abstract
- * base's constructor + service registration. The real durable backends are
- * `@deepseek-ai/dsh-session-persistence-jsonl` / `-sqlite`.
- *
- * The store can be supplied via config so two backend instances share one Map —
- * the in-RAM analogue of two backends over the same file/db, which the
- * coordinator orchestration suite's HMR/reload tests need (a fresh instance with
- * an empty in-memory states map adopting an already-materialized session).
+ * Reference {@link PersistenceCoordinator} vehicle and abstract-service coverage, backed by a
+ * dependency-free map with atomic writes and no torn-tail marker. Supplying the map lets multiple
+ * instances share materialized sessions, the in-memory analogue of reload over one file/database;
+ * durable behavior is covered by the JSONL and SQLite backends.
  */
 class MemoryPersistence extends SessionPersistence implements PersistenceBackend<never> {
   static inject = ['sessions']
@@ -92,8 +84,7 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     }
     const existing = this.store.get(m.id)
     if (!existing) {
-      // First batch: `_isMaterialized` is false (the coordinator only omits
-      // materialization on the first batch); writing the entry IS the materialization.
+      // The coordinator sends the first batch for materialization; later batches append.
       this.store.set(m.id, { meta: structuredClone(m), events: structuredClone(events) as SessionEvent[] })
     } else {
       existing.events.push(...structuredClone(events) as SessionEvent[])
@@ -126,12 +117,8 @@ runPersistenceContract('memory', async () => {
   }
 })
 
-// Run the shared coordinator orchestration suite against the in-memory backend.
-// A per-fixture Map is the shared "storage", so two mounted instances see the
-// same materialized sessions (HMR/reload). `corruptTail` is OMITTED: a Map store
-// writes atomically in RAM and has no torn tails, so the suite's torn-tail test
-// self-skips (and asserts the omission). The real torn-tail repair branch is
-// covered by the jsonl/sqlite fixtures, which CAN inject one.
+// Each fixture shares one map across mounts. No `corruptTail` is supplied because map writes are
+// atomic; the suite asserts that skip while JSONL and SQLite cover the repair branch.
 runCoordinatorContract('memory', async (): Promise<CoordinatorFixture> => {
   const store: MemoryStore = new Map()
   return {