Merge remote-tracking branch 'origin/master' into session-surface

Reconciles the session-surface work (surfaceOp/sourceEventSeqs provenance as
the sole derivation path) with master's worktree-subagent series (fork-seed
boundary + out-of-process subagent backends).

Semantic reconciliations beyond the textual auto-merge:
- SQLite SCHEMA_VERSION: both sides bumped 2->3. Merged to a single v3 carrying
  BOTH column families — master's seed_length on `sessions` and surface's
  source_event_seqs/surface_op on `events`. writeRow + both INSERT sites bind
  the full set; the schema doc lists all three added columns as the v2->v3 gap.
- agent-loop runStep request: master's `sessionId: session.id` and surface's
  per-append surfaceOp/sourceEventSeqs coexist (different regions).
- Fork seed + surface: a fork seeds the child from the parent's LIVE events,
  which now carry surfaceOp, so the child's surface rebuilds correctly. Verified
  end-to-end — the subagent-fork replay recalls the inherited "SAFFRON" codeword
  through the seeded prefix.
- Subagent snapshot fixtures (recorded pre-surface) re-enriched via KEYLESS
  deterministic replay: only surfaceOp/sourceEventSeqs added onto existing
  recorded lines (matched by seq), no recorded value changed. Not re-recorded
  against the live API.

Gates: typecheck, test (1112), test:snapshot (14), doc-sync, lint, build,
hygiene all green.

packages/core/agent-loop/package.json

@@ -5,17 +5,19 @@
   "private": true,
   "type": "module",
   "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "types": "lib/types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
+      "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "lib",
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",

packages/core/agent-loop/src/index.ts

@@ -121,10 +121,6 @@ export class AgentLoop extends Service implements AgentFactory {
    * deliberate resume-or-create policy (resume the prior session if one exists,
    * else start fresh) or an explicit caller-chosen session id — revisit when the
    * UI/ACP path owns session selection.
-   *
-   * TODO(sub-agents): spawn/fork land here — accept a parent agent reference;
-   * fork seeds the new Session with the parent's event log, spawn starts
-   * fresh; the child is returned as a regular Agent handle.
    */
   create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent {
     this.assertAgentIdFree(id)
@@ -140,16 +136,22 @@ export class AgentLoop extends Service implements AgentFactory {
   /**
    * Programmatic factory create ({@link AgentFactory}): an agent on a
    * caller-supplied `sessionId` (NOT `${id}-session`), with optional session
-   * metadata (validated `cwd`, lineage). The ACP bridge uses this so the
-   * client-generated session id becomes the live/persisted session id. Returns
-   * an {@link AgentHandle} the owner disposes to tear down exactly this agent.
+   * metadata (validated `cwd`, lineage) and an optional `seed` event prefix. The
+   * ACP bridge uses this so the client-generated session id becomes the
+   * live/persisted session id; the in-process FORK subagent backend passes a
+   * `seed` (a balanced completed-turn prefix of the parent's log) so the child
+   * starts with the parent's context. Returns an {@link AgentHandle} the owner
+   * disposes to tear down exactly this agent.
    */
   createAgent(options: CreateAgentOptions): AgentHandle {
     // Check the agent id BEFORE preparing the session: register() would reject a
     // duplicate id only AFTER the session enters the store, leaving an orphaned
     // live session (and lazy persistence state) that blocks reuse of that id.
     this.assertAgentIdFree(options.agentId)
-    const session = this.ctx.sessions.prepare(options.sessionId, { meta: options.meta ?? {} })
+    const session = this.ctx.sessions.prepare(options.sessionId, {
+      ...options.seed !== undefined ? { seed: options.seed } : {},
+      meta: options.meta ?? {},
+    })
     return this.startOwned(options.agentId, options.agentOptions ?? {}, session)
   }
 
@@ -217,6 +219,9 @@ export class AgentLoop extends Service implements AgentFactory {
         createdAt: meta.createdAt,
         ...meta.cwd !== undefined ? { cwd: meta.cwd } : {},
         ...meta.parentSession !== undefined ? { parentSession: meta.parentSession } : {},
+        // Reconstruct the seed boundary from the persisted header, NOT from
+        // `events.length` (the resume seeds the WHOLE stored log).
+        ...meta.seedLength !== undefined ? { seedLength: meta.seedLength } : {},
       },
     })
     return this.startOwned(options.agentId, options.agentOptions ?? {}, session)

packages/core/agent-loop/src/loop.ts

@@ -570,6 +570,7 @@ async function runStep(
     messages: session.deriveMessages(),
     ...system ? { system } : {},
     ...assembly.tools.length > 0 ? { tools: assembly.tools } : {},
+    sessionId: session.id,
     signal,
   }
   request = await ctx.waterfall('agent/request', agent, turn, step, request, () => Promise.resolve(request))

packages/core/agent-loop/tests/resume.spec.ts

@@ -94,9 +94,9 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.fiber.dispose()
   })
 
-  it('resume of a forked session preserves the parentSession lineage in the header', async () => {
-    // Lifecycle 1: persist a FORKED session (carries parentSession in its
-    // header) by creating it with a complete-turn seed — the write path
+  it('resume of a forked session preserves the parentSession lineage and seed boundary in the header', async () => {
+    // Lifecycle 1: persist a FORKED session (carries parentSession + seedLength
+    // in its header) by creating it with a complete-turn seed — the write path
     // materializes the fork (header + seed) on disk.
     const seed: SessionEvent[] = [
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
@@ -104,12 +104,18 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ]
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const forked = ctx1.sessions.create(SessionId('forked-sess'), { seed, meta: { cwd: '/w', parentSession: SessionId('parent-sess') } })
+    const forked = ctx1.sessions.create(SessionId('forked-sess'), {
+      seed,
+      meta: { cwd: '/w', parentSession: SessionId('parent-sess'), seedLength: seed.length },
+    })
     await ctx1.parallel('session/flush', forked)
     await ctx1.fiber.dispose()
 
-    // Lifecycle 2: resume it; the parentSession header survives the round-trip
-    // (exercises resume's parentSession-present branch).
+    // Lifecycle 2: resume it; the parentSession + seedLength header survives the
+    // round-trip (exercises resume's parentSession- and seedLength-present
+    // branches). seedLength must come from the PERSISTED header, not from the
+    // resume seed length (which is the whole stored log, not the original
+    // boundary).
     const adapter2 = new MockAdapter([textResponse('b')])
     const ctx2 = new Context()
     await ctx2.plugin(LlmService)
@@ -123,6 +129,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const a2 = (await ctx2.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('forked-sess') })).agent as ReactLoopAgent
     expect(a2.session.header.parentSession).toBe('parent-sess')
     expect(a2.session.header.cwd).toBe('/w')
+    expect(a2.session.header.seedLength).toBe(seed.length)
     await ctx2.fiber.dispose()
   })
 

packages/core/agent-loop/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib/types"
   },
   "include": [
     "src"