docs(readme): rewrite README + add runnable examples by drewstone · Pull Request #5 · tangle-network/agent-runtime

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

drewstone · 2026-05-09T00:03:39Z

Summary

Replace the broken getBox -> sandboxId README snippet with a self-contained examples/sandbox-stream-backend/ whose sandboxClient and sandboxId are visibly defined inline — fixes the "where does sandboxId come from?" reader confusion
Restructure README.md around TOC / Overview / Install / Getting started / entry-point picker, mirroring the docs pattern in agent-eval
Ship six runnable examples in examples/: basic-task, with-knowledge-readiness, sanitized-telemetry, sse-stream, sandbox-stream-backend, openai-stream-backend — five run with no creds; the OpenAI one needs OPENAI_API_KEY

Test plan

pnpm typecheck
All five synthetic examples run end-to-end with pnpm tsx examples/<name>/<name>.ts and produce coherent output (status / SSE stream / readiness scoring / sanitized vs verbose telemetry)
openai-stream-backend exits with a clear message when creds are absent

Remove the broken `getBox -> sandboxId` snippet and replace it with a self-contained sandbox-stream-backend example whose `sandboxClient` and `sandboxId` are visibly defined inline. Restructure README around TOC / Overview / Install / Getting started / entry-point picker / examples, and ship six runnable examples covering basic-task, knowledge readiness, sanitized telemetry, SSE serialization, the sandbox stream backend, and the OpenAI-compatible stream backend.

…ehavior (#65) Investigation surfaced two doc inaccuracies the freshly-merged spec doc inherited from my own assumption rather than measurement: 1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the spec claimed. Updated header table + invariant #5 accordingly. 2. The spec read as fully shipped end-to-end. Added an Implementation status table making the per-layer reality explicit: - agent-runtime emits all six headers (this is the work that shipped in #64). - tangle-router enforces depth + forwards auth (already live). - cli-bridge forwards authorization to sandbox backends (already live); does not enforce depth locally — inherits via router. - agent-gateway middleware: NOT YET. Deferred to a real consumer. No code changes. The agent-runtime headers builders and emitters are already correct (they emit the header; refusal is the gateway's job). The doc was the only thing out of step.

…-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.

@experimental

…r runLoop (backend-blind) (#150) * feat(loops): opt-in session continuation + checkpoint-fork lineage (backend-blind) Two @experimental, default-OFF seams on runLoop so a loop can CONTINUE a sandbox session across iterations (same box + sessionId, no prompt-text replay) and FORK fanout branches from a parent checkpoint (shared context prefix) — both behind a capability probe so the kernel asks 'can I fork?' (client.criuStatus) and never names Docker/Firecracker, degrading to fresh boxes when CRIU is absent. - sandbox-capabilities.ts: memoized, fail-closed criuStatus probe -> {canFork}. - sandbox-lineage.ts: createSandboxLineage owns box+session handles with start/continue/fork/teardown; reuses the kernel's acquireSandbox / buildBackendOptions / deleteBoxSafe; fail-loud if the probe says canFork but the box has no fork(). - run-loop.ts: RunLoopOptions.lineage (sessionContinuity / forkFanout); refine continues, fanout forks-once, else fresh-through-lineage. Default OFF is byte-identical to today, so random@k stays N independent fresh boxes (the compute-control invariant). Rejects lineage + onWorkerBox (both own boxes). - 7 new unit tests (continuation reuses session; fork when canFork; fresh fallback; default-off invariant). Full suite 621 pass, typecheck clean. * fix(loops): address PR #150 review — bound forks, prune lineage, fail-loud session continuity Resolve all six findings from the review (none blocked landing; #1 gated enabling, #3/#4 wanted documenting). Lineage remains default-OFF and byte-identical to the fresh-box path when both flags are unset. - #1 sessionContinuity silent no-op: `continue` now asserts the session is still known to the sandbox via `box.session(id).status()` before streaming. A `null` (platform never honored the client-minted id, or it was reaped) raises a ValidationError, which executeIteration now propagates as a hard structural failure instead of degrading to a soft empty iteration — so a non-honoring platform errors loudly rather than running contextless turns. - #2 unbounded fork creation: `fork` provisions child boxes through `mapWithConcurrency` bounded by the loop's `maxConcurrency`, not a single `Promise.all` over all N branches. - #3 fork ignores per-branch specs: documented on `fork` and `LoopLineageOptions.forkFanout` that a real CRIU fork inherits the parent image/profile (per-branch specs apply only on the degraded fresh path). - #4 lineage holds every box to loop end: kernel prunes boxes no future round can descend from after each round, gated on a kernel-inferred (monotonic) branch point — skipped when the driver authors its own `parentIndex`. The unprunable case is documented as the box ceiling. - #5 abort during fork: documented the SDK's signal-less fork; abort is now checked per branch (between bounded waves) + an abort-under-lineage test. - #6 export order: alphabetized the loops barrel. Adds `mapWithConcurrency` util and six lineage tests (session-liveness pass/ fail, bounded-fork peak, mid-loop prune, no-prune-under-authored-parent, abort-under-lineage). 627 tests pass, typecheck + biome clean.