Merge remote-tracking branch 'origin/worktree-agent-scope-design' into codex/package-readme-limitations-audit-20260712

# Conflicts:
#	packages/core/scope/README.md
#	packages/session-persistence/session-persistence-jsonl/README.md
#	packages/session-persistence/session-persistence-sqlite/README.md
#	packages/subagent/subagent-acp/README.md
#	packages/subagent/subagent-fork/README.md
#	packages/subagent/subagent-inprocess/README.md
#	packages/subagent/subagent/README.md
#	packages/subagent/tool-subagent/README.md
#	packages/support/invariants/README.md
#	packages/support/subagent-mock/README.md
#	packages/workflow/workflow-workerthread/README.md
#	packages/workflow/workflow/README.md

packages/session-persistence/session-persistence-jsonl/README.md

@@ -28,7 +28,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 ## Write path
 
-The plugin generalizes the example `session-jsonl.ts`: it subscribes to `session/created` (capture the header; persist a fork's seed once), `session/event` (snapshot each event when buffering — the live `session.events` object is mutable), and `session/flush`/dispose (drain the write-behind buffer through `append`). A per-session write cursor means a resumed session never re-appends already-stored events. Existing live sessions are seeded on plugin apply (HMR does not replay `session/created`). All backend operations for one session are serialized, and disposal awaits quiescence (every init + final drain) before returning, so no write lands after teardown.
+The plugin generalizes the example `session-jsonl.ts`: it subscribes to `session/created` (capture the header; persist a fork's seed once), `session/event` (copy each already-frozen event into the persistence-owned write-behind buffer), and `session/flush`/dispose (drain that buffer through `append`). A per-session write cursor means a resumed session never re-appends already-stored events. Existing live sessions are seeded on plugin apply (HMR does not replay `session/created`). All backend operations for one session are serialized, and disposal awaits quiescence (every init + final drain) before returning, so no write lands after teardown.
 
 ## Known Limitations and Deferred Work
 

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

@@ -4,7 +4,7 @@ import { appendFile, mkdtemp, mkdir, rm, readFile, writeFile, readdir, stat } fr
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { encodeSegment, logPath, scanLog, sessionDir } from '../src/format.ts'
 import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
@@ -13,6 +13,13 @@ import { runCoordinatorContract, type CoordinatorFixture } from '../../session-p
 let root: string
 const dirs: string[] = []
 
+type MutableSessionHeader = { -readonly [K in keyof SessionHeader]: SessionHeader[K] }
+
+/** Test-only mutable view used to verify that backends detach returned/caller metadata. */
+function mutableHeader(header: SessionHeader): MutableSessionHeader {
+  return header
+}
+
 async function freshRoot(): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-'))
   dirs.push(dir)
@@ -255,7 +262,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     const loaded = await ctx.sessionPersistence.load(m.id)
     // A consumer mutates the returned meta's cwd. The backend's stored pathing
     // metadata must be unaffected, so a later append still finds the right log.
-    loaded.meta.cwd = '/evil'
+    mutableHeader(loaded.meta).cwd = '/evil'
     await ctx.sessionPersistence.append(m.id, [
       { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
       { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
@@ -421,7 +428,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     const m = meta('create-snap', '/orig')
     const p = ctx.sessionPersistence.create(m)
     // Mutate the caller's meta object immediately after calling create.
-    m.cwd = '/mutated'
+    mutableHeader(m).cwd = '/mutated'
     await p
     await ctx.sessionPersistence.append(SessionId('create-snap'), oneTurnLog())
     // The log materialized under the ORIGINAL cwd, not the mutated one.

packages/session-persistence/session-persistence-sqlite/README.md

@@ -25,7 +25,7 @@ interface Config {
 
 ## Write path
 
-Like the JSONL backend, the plugin also installs the `session/event` → buffer → `session/flush` drain: it snapshots each event when buffered (the live `session.events` object is mutable), persists a fork's seed once on `session/created`, keeps a per-session write cursor so a resumed session never re-appends stored events, and seeds existing live sessions on apply (HMR does not replay `session/created`). Dispose awaits every in-flight init + final drain and then closes the database, so no write lands after teardown.
+Like the JSONL backend, the plugin also installs the `session/event` → buffer → `session/flush` drain: it copies each already-frozen event into a persistence-owned buffer, persists a fork's seed once on `session/created`, keeps a per-session write cursor so a resumed session never re-appends stored events, and seeds existing live sessions on apply (HMR does not replay `session/created`). Dispose awaits every in-flight init + final drain and then closes the database, so no write lands after teardown.
 
 ## Known Limitations and Deferred Work
 

packages/session-persistence/session-persistence/README.md

@@ -17,7 +17,7 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 
 - **Append-only; a crashed turn is closed, not truncated.** Committed events (at or below a flushed `turn/end`) are never rewritten. A crash can leave an unclosed final turn whose events are real and possibly large; `load` preserves them and durably appends synthetic closers (an error `tool/result` per unanswered `tool-call`, then `step/end?`+`turn/end {interrupted}`) to balance the log and keep the rehydrated history a valid provider transcript. Only a never-fully-written torn tail fragment is discarded.
 - **Contiguous seq.** `load` rejects a `seq` gap/parse error in the MIDDLE of the log; `append`'s first `seq` must equal the stored next-seq.
-- **JSON-serializable data.** `append` rejects non-serializable `event.data`; backends snapshot each event when buffering (the live `session.events` object is mutable).
+- **JSON-serializable data.** `append` materializes each direct/replay batch through the shared one-pass lossless-JSON boundary. Live `Session` events are already deep-frozen, but the write coordinator still copies each event into a persistence-owned buffer.
 - **Durability.** `append` returns only once the batch is durable.
 
 ## The write coordinator

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -25,9 +25,9 @@
  */
 
 import { Context } from 'cordis'
-import { interruptedTurnClosers, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session'
+import { interruptedTurnClosers, SESSION_FORMAT_VERSION, snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
-import { assertSerializable, seedCoversPrefix } from './index.ts'
+import { seedCoversPrefix } from './index.ts'
 
 /**
  * A stored session's durable prefix as read back from a backend: its
@@ -186,14 +186,18 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register a new session's metadata (lazy: no physical write until the first
    * {@link append}). Rejects if the id is already tracked or already persisted.
-   * @param meta - the immutable header (id, version, cwd, lineage) to record; snapshotted at call time.
+   * @param meta - the header (id, version, cwd, lineage) to record; materialized
+   *   as a detached lossless-JSON snapshot at call time.
    */
   create(meta: SessionHeader): Promise<void> {
     // Snapshot the metadata at call time: the op runs later (behind the
     // per-session chain) and the snapshot is stored as the lazy state, so keeping
     // the caller's object by reference would let a later mutation of `id`/`cwd`
     // register under one key but materialize under a different path/header.
-    const snapshot: SessionHeader = { ...meta }
+    const snapshot = snapshotJsonValue(meta)
+    if (snapshot === undefined) {
+      return Promise.reject(new TypeError('session metadata must be losslessly JSON-serializable'))
+    }
     return this.serialize(snapshot.id, () => this.createCore(snapshot))
   }
 
@@ -212,23 +216,25 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     this.states.set(meta.id, { meta, cursor: 0, materialized: false })
   }
 
-  // `async` so the synchronous validate/clone below reject (not throw) per the
-  // Promise<void> contract — callers use `await expect(...).rejects`.
+  // `async` so synchronous materialization failures below reject (not throw) per
+  // the Promise<void> contract — callers use `await expect(...).rejects`.
   /**
    * Durably persist a batch of events. Honors the append-only and contiguous-seq
    * contracts; rejects non-JSON-serializable `event.data`.
    * @param id - the session the batch belongs to.
-   * @param events - the contiguous batch to persist, in seq order; deep-cloned at call time.
+   * @param events - the contiguous batch to persist, in seq order; materialized
+   *   as a detached lossless-JSON snapshot at call time.
    */
   async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    // Validate serializability BEFORE cloning so a bad event surfaces the typed
-    // error rather than an opaque DataCloneError from structuredClone.
-    assertSerializable(events)
-    // Deep-snapshot the batch HERE, before the op waits behind the per-session
-    // chain: a caller that mutates a live array (e.g. session.events) — or an
-    // event inside it — before the op runs would otherwise have those changes
-    // persisted. The clone is taken synchronously (at call time).
-    const batch = events.map(e => structuredClone(e))
+    // Validate and deep-snapshot the complete batch HERE, in one traversal,
+    // before the op waits behind the per-session chain. A check followed by
+    // structuredClone would reread accessors and could sanitize an exotic value
+    // into an apparently valid record; the single-pass materializer makes the
+    // checked value exactly the value persisted.
+    const batch = snapshotJsonValue(events)
+    if (batch === undefined) {
+      throw new TypeError('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
+    }
     return this.serialize(id, () => this.appendCore(id, batch))
   }
 
@@ -338,9 +344,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     // promise so flush/dispose can await it (onCreated is async).
     ctx.on('session/created', (session) => { void this.initFor(session) })
 
-    // Snapshot + buffer every event (the live object is mutable; clone so a later
-    // in-place mutation cannot rewrite a buffered event). Serializability is
-    // guaranteed at the source (Session.append), so structuredClone is safe.
+    // Session emits an owned frozen event. Keep a persistence-owned copy anyway
+    // so the write-behind queue owns exactly the record it will flush rather than
+    // retaining a product-layer record by identity. Serializability is guaranteed
+    // at the source, so structuredClone is safe.
     ctx.on('session/event', (session, event) => {
       let buffer = this.buffers.get(session)
       if (!buffer) this.buffers.set(session, buffer = [])
@@ -391,8 +398,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const existing = this.inits.get(session)
     if (existing) return existing
     // Snapshot the seed SYNCHRONOUSLY — initFor runs inside the `session/created`
-    // emit, before any later `append` adds non-seed events. A clone freezes it
-    // against later mutation of the live event objects.
+    // emit, before any later append invalidates the public array snapshot. Events
+    // are already frozen; cloning gives persistence independent ownership.
     const seed = session.events.map(e => structuredClone(e))
     const p = this.onCreated(session, seed)
     // Attach a no-op rejection handler so a failing init does not surface as an

packages/session-persistence/session-persistence/src/index.ts

@@ -22,7 +22,7 @@
  */
 
 import { Context, Service } from 'cordis'
-import { isJsonValue } from '@deepseek-ai/dsh-session'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 
 // Re-export the metadata vocabulary so consumers import it from the seam.
@@ -58,16 +58,16 @@ export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly
 }
 
 /**
- * Reject non-JSON-serializable event data before a backend serializes a batch.
- * Live session appends already enforce this; persistence append paths also
- * accept replay/fork batches that may bypass a live session instance.
- * @param events - the batch to validate; throws naming the offending event's type and seq.
+ * Reject a batch that is not wholly losslessly JSON-serializable. Live session
+ * appends already enforce this; persistence append paths also accept replay or
+ * direct batches that may bypass a live session instance. Validation uses the
+ * same one-pass materializer as the coordinator, so getters are read once.
+ * @param events - the complete event batch to validate.
  */
 export function assertSerializable(events: readonly SessionEvent[]): void {
-  for (const event of events) {
-    if (!isJsonValue(event.data)) {
-      throw new Error(`event "${event.type}" carries non-JSON-serializable data (seq ${event.seq})`)
-    }
+  const snapshot = snapshotJsonValue(events)
+  if (snapshot === undefined) {
+    throw new Error('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
   }
 }
 
@@ -90,11 +90,11 @@ export function assertSerializable(events: readonly SessionEvent[]): void {
  *   {@link load} rejects a parse error or a `seq` gap in the COMMITTED region
  *   (unloadable); {@link append}'s first event `seq` MUST equal the backend's
  *   stored next-seq (after `load` has balanced any interrupted turn).
- * - **JSON-serializable data.** `SessionEventMap` is merge-extensible and
- *   `event.data` is typed only as `SessionEventMap[K]`, so {@link append}
- *   REJECTS non-JSON-serializable data with an error naming the offending
- *   event type. A backend snapshots (serializes/clones) each event when it
- *   buffers, since `session.events` hands out the live mutable object.
+ * - **JSON-serializable events.** `SessionEventMap` is merge-extensible, so
+ *   {@link append} materializes each complete batch through the shared
+ *   lossless-JSON boundary before buffering it. The public `session.events`
+ *   view is immutable, but persistence still snapshots direct/replay callers at
+ *   this independent trust boundary.
  * - **Durability.** {@link append} returns only once the batch is durable
  *   (the file backend fsyncs; a DB commits). {@link create} MAY defer the
  *   physical write until the first {@link append} (lazy materialization).

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

@@ -245,7 +245,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           const events = [
             { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: bad } },
           ] as unknown as SessionEvent[]
-          await expect(persistence.append(mi.id, events)).rejects.toThrow(/user\/message/)
+          await expect(persistence.append(mi.id, events)).rejects.toThrow(/losslessly JSON-serializable/)
         }
       } finally {
         await dispose()

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

@@ -143,14 +143,15 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
-    it('snapshot-on-buffer: mutating an event after session/event does not corrupt the persisted copy', async () => {
+    it('source-frozen events cannot be mutated after buffering and persist unchanged', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
         const session = ctx.sessions.create(SessionId('mutate'), { meta: { cwd: WORK } })
         const ev = session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-        // Mutate the live event object AFTER it was buffered by session/event.
-        ;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
+        expect(() => {
+          ;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
+        }).toThrow(TypeError)
         session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
         session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
         await ctx.parallel('session/flush', session)

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

@@ -158,6 +158,17 @@ describe('SessionPersistence service registration', () => {
     expect(loaded.events).toHaveLength(6)
     await fiber.dispose()
   })
+
+  it('rejects non-JSON session metadata before registering lazy state', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence)
+    const invalid = { ...meta('invalid-meta'), createdAt: 1n as unknown as number }
+
+    await expect(ctx.sessionPersistence.create(invalid))
+      .rejects.toThrow('session metadata must be losslessly JSON-serializable')
+    await fiber.dispose()
+  })
 })
 
 describe('shared persistence helpers', () => {
@@ -187,10 +198,10 @@ describe('shared persistence helpers', () => {
     expect(() => { assertSerializable(oneTurnLog()) }).not.toThrow()
   })
 
-  it('rejects non-JSON-serializable event data with type and seq context', () => {
+  it('rejects a batch containing non-JSON-serializable event data', () => {
     const bad = [
       { type: 'user/message', seq: 0, time: 1, data: { content: 1n } },
     ] as unknown as SessionEvent[]
-    expect(() => { assertSerializable(bad) }).toThrow(/"user\/message".*seq 0/)
+    expect(() => { assertSerializable(bad) }).toThrow(/batch is not losslessly JSON-serializable/)
   })
 })