@smthrs/harness 0.0.0-stage → 1.0.0-rc.4

package/docs/concepts.md

@@ -0,0 +1,238 @@
+---
+title: "Concepts"
+description: "The mental models behind @smthrs/harness: cells, the persistent realm, durable flow calls as the only I/O, and the design decisions each module enforces."
+---
+
+This page states the designs `@smthrs/harness` is built on: what each one
+decides, and which module holds you to the decision. Three mental models
+organize all of them: the cell, the persistent realm, and the durable flow
+call.
+
+## The cell loop
+
+A run of the built-in agent is a sequence of frames. One frame is:
+
+```text
+model -> generated cell -> realm evaluation -> individually durable flow calls -> next transition
+```
+
+The model's whole answer is text, and the harness recovers a program from it:
+every fenced `cell` block of the reply, joined in order into one JavaScript
+program. That program is the cell. It runs inside a realm the run keeps, and
+it states how the run should proceed by calling: `ctx.done(output)` completes
+the run, `ctx.park(reason, message)` waits durably, and a cell that calls
+neither continues to the next frame. `Sandbox.replTransition` builds the
+`Cell.Transition` the journal records from that call.
+
+The loop is cell-first rather than tool-call-first. The controller seals every
+model request with `tools: []` and `toolChoice: "none"`, so continuation never
+comes from provider plumbing: it comes from the transition the cell settled
+and the budgets the run declared. A model that wants to read a file, run a
+command, or ask a human writes JavaScript that awaits `ctx.call`, the same two
+lines for every capability, and the harness turns each call into its own
+durable boundary.
+
+Four actors share the frame, and the package draws a hard line between them.
+The model authors cells. The realm evaluates them. The controller (`CellTurn`)
+decides what the transition means and what the next frame shows. The engine
+(`EngineLike`) owns everything durable: sealed model steps, flow-call
+settlements, journaled records, workspace measurement, checkpoints, and
+suspension. The package is the translation between the four; scheduling,
+persistence, transport, and model execution stay behind the ports.
+
+A frame lookup writes an empty attempt marker when no terminal record exists.
+Evaluation then runs outside the record activity, and its result is written
+to the next slot. Replay skips existing empty markers before reconstructing
+the terminal frame. An attempt that parks or is interrupted leaves a marker
+and can resume its calls without an enclosing frame activity.
+
+A whole-frame timeout records the last dispatched and last delivered bridge
+ordinals with the frame outcome. Replay reads that record before evaluating
+the cell, reconstructs the settled prefix, and interrupts the bridge at the
+recorded cutoff. Calls and checkpoints beyond that cutoff cannot run, and
+JavaScript awaiting the interrupted bridge receives the same teardown as the
+original attempt. Settled calls in this prefix use their recorded results,
+including per-call timeouts. A limit rejection without a recorded frontier
+still decodes for inspection, but replay fails with `incompatible_journal`
+before evaluating it. A binding must return the frontier to resume such a
+frame safely.
+
+## Repl realm
+
+A run holds **one** realm for its whole life. The realm is the run's memory:
+names bound by frame 3 are still bound in frame 9, so a cell reads what earlier
+cells built instead of re-deriving it, and nothing is filed on the way out. What
+the next model turn reads is what the frame printed.
+
+Consequences the code enforces:
+
+- `Sandbox.Realm` is acquired once and scoped to the run, not to a frame.
+  `QuickJSSandbox.openRealm` is the only implementation that offers one.
+- The per-frame budgets (`steps`, `timeMs`, `totalMs`) reset at each frame; the
+  memory budget cannot, so `memoryBytes` is a **run** budget enforced by the
+  panel probe at each frame's close.
+- The realm is sealed per frame, not per run: `ctx.done` / `ctx.park` latch for
+  the frame they were called in and the host clears the latch as the next frame
+  opens.
+- `VariablesPanel` exists because the value is still there under the name the
+  panel prints. The panel measures each name cheaply rather than serializing it.
+
+Enforced by `Sandbox`, `QuickJSSandbox`, and `VariablesPanel`.
+
+## Durable cell loop
+
+A frame is `model -> cell -> realm evaluation -> durable flow calls ->
+transition`. Every `ctx.call` is its own keyed, journaled, permission-gated
+boundary. On a compatible journal, a crash or a permission park mid-cell
+re-executes source from the top and replays settled calls. This requires the
+same controller format, declarations, and deterministic cell computation;
+changing key material can turn a replay into a fresh call.
+
+Harness journal format 2 changes summaries to user context. The agent session
+checks persisted trace versions before opening model or cell boundaries, and
+`CellTurn.run` rejects controller state decoded from an older format with typed
+`HarnessError` code `incompatible_journal`. Start a new run for old journals;
+rc.0 has no compatibility promise. Transcript projection is for display and
+normalizes historical summary text to user messages; it does not authorize
+resuming a historical run. The session trace is best-effort telemetry, while
+the engine's sealed steps and recorded boundaries provide durable replay.
+
+The controller's own reads of the world go through `EngineLike.record` for the
+same reason. `(name, identity)` together key a record, and the controller folds
+each boundary's purpose into its identity so it is correct even under an engine
+that keys on identity alone.
+
+Enforced by `CellTurn`, `Cell`, and `EngineLike`.
+
+## Agent cell context
+
+What a cell can see and reach, and nothing else:
+
+- `ctx.call(flowName, input)` is the only authority. There is no `ctx.fs`, no
+  `ctx.shell`, no `ctx.mcp`, no `ctx.spawn`.
+- `ctx.flows` is the catalog, projected from the registry through
+  `Cell.FlowProjection`, so the shape a cell reads is the shape the schema
+  declares.
+- `ctx.done`, `ctx.park` and `ctx.justify` are how a cell states its intent.
+- `ctx.checkpoint()` mints a read-only view of the tree; a mint settles on the
+  call channel and spends the call budget.
+
+Enforced by the `QuickJSSandbox` realm prelude and the `Cell` contract.
+
+## Flow registry
+
+A cell may call only what the registry disclosed to it, and it must call the
+declaration it was shown. `Cell.declarationDigest` is `@smthrs/registry`'s
+`Descriptor.declarationDigest`, the one declaration identity for
+`FlowDescriptor`; it hashes the complete material declaration, `Cell.CallIdentity` folds that digest into every call's identity,
+and `CellCalls.make` re-derives it at the boundary: an entry that moved between
+the frame that showed the catalog and the boundary that runs the call is refused
+with `declaration_changed` rather than dispatched to a body the model never saw.
+
+An executable binding answers before a discovered implementation, because a
+binding is the implementation of the declaration it projected.
+
+Enforced by `CellCalls`, `FlowBinding`, and `Cell`.
+
+## Context window
+
+The context assembled for one model request is immutable, provider-neutral, and
+zoned, so a provider's prefix cache covers the stable span. Segments carry their
+own digest and estimated token count, computed once at construction; the arrays
+are frozen so a mutation cannot invalidate a cached digest silently.
+
+The volatile block, the frame's state section, is a user message after the
+transcript rather than inside the system context, so the whole stable span is
+byte-identical for the life of a run. Each frame's section stays in the window
+once written, and a later section lists only the calls settled since the last
+one, so every request is the previous request, its reply, and new messages.
+The newest section is read just before the frame's asks, or last when there
+are none.
+
+Compaction summaries are rendered as user messages, including summaries read
+from older journal records. This keeps every compacted request anchored by a
+leading user turn on providers that reject assistant-first conversations.
+The settlement records the retained suffix's message count so transcript
+projection replaces only the summarized prefix. Repeated compactions apply in
+journal order. Legacy settlements without a count replace all earlier messages.
+
+Enforced by `ContextWindow`, `Tokens`, and `Compaction`.
+
+## Structured output
+
+A boundary that must produce a typed value decodes the original `ctx.done`
+value against the declared schema. String answers can use JSON text extraction
+when the schema requires another type. Older text-only completions retain text
+decoding. The boundary spends a bounded number of correction re-prompts,
+and then fails with a typed, coded failure rather than prose. The failure names
+the schema digest, the candidate digest, the corrections spent, the budget, and
+a bounded list of `{ path, message }` issues, so two identical-looking refusals
+are distinguishable and a consumer branches on `code`.
+
+Enforced by `StructuredOutput`.
+
+## Notification queue
+
+Human steering reaches a run only at safe turn boundaries. The durable queue
+decides which notifications a boundary may deliver; the harness folds what it
+promoted into inserts and seat changes, journals the drain as a record so a
+resumed run does not drain an already-drained queue, and never lets an
+un-actionable steer look delivered.
+
+Steering is considered after raised and rejected cells as well as successful
+transitions. A completion is an idle boundary: queued follow-ups can keep the
+run going. When the frame budget is exhausted, undeliverable notifications stay
+pending in the durable queue for the host to carry forward.
+
+Pending steering detected after the model returns holds the proposed cell until
+another model frame consumes the instruction. If no frame remains, the run fails
+with `engine_failed` and leaves the instruction pending, including when the
+proposed cell would have parked. If the drain finds nothing left to deliver,
+the proposed cell can execute.
+
+Enforced by `Notifications` and `Steering`.
+
+An outside-change note names changed files as untrusted data. Re-read those files
+before editing or writing; after a `stale_read` refusal, read again before retrying.
+Outside-change delivery stays disabled until authenticated watcher ingestion,
+durable delivery to the pinned coding run, and machine stale-write enforcement
+are available.
+
+Reserved `outside_change` payloads fail queue admission with
+`NotificationError.code = "notification_refused"`. They never enter the journal;
+other steers at the same boundary still deliver and replay.
+
+## Step keys and the model layer
+
+A sealed model step is keyed on the exact wire request plus the declared key
+material. Anything that says _how long the caller will wait_ rather than _what
+the model was asked_ is deliberately not key material: a step keyed on a budget
+would miss its cache the moment a host retuned it. `SealedModelStep.modelCallMs`
+is the example, and it travels on the step so the number the controller journals
+as armed is the number the engine enforces.
+
+Enforced by `EngineLike`, with the request shape owned by [`@smthrs/model`](/api/model).
+
+## Child plans and the splice boundary
+
+`Plan.Batch` describes children in source order; `EngineLike.splice` is the one
+boundary that turns a batch into running children and streams their progress
+back. The harness translates and never schedules.
+
+Enforced by `Plan` and `EngineLike`.
+
+## Model authoring surface
+
+The cell contract is the text the model is taught with, and its size is a cost
+the run pays every frame. The package pins a token ceiling on the rendered
+contract, so growing it is a deliberate act with a number attached.
+
+The `jev` teaching is a section of its own, rendered between the environment
+facts and the catalog only when the catalog binds `jev`. It carries the
+thresholds a cell acts on (a boolean at probability 0.8, a choice or score at
+the provider's confidence 0.7) and one worked example that the package runs
+verbatim. It is constant for a run, so the cached prefix holds.
+
+Enforced by `CellTurn.teach`, which renders the contract and the callable-flow
+catalog into the prefix zone of a `ContextWindow`, where every transition
+preserves them.

package/docs/external-transcripts.md

@@ -0,0 +1,245 @@
+# External transcripts
+
+A person runs Codex or Claude Code in a branch terminal with their own login.
+`ExternalTranscript` from `@smthrs/harness` decodes the transcript file that
+agent writes into ordered, read-only entries, so the branch conversation can
+show the session (mvp.md M-38). The module has two decoders and nothing else:
+
+```ts
+import { ExternalTranscript } from "@smthrs/harness"
+
+ExternalTranscript.decodeCodex(state, chunk) // rollout-*.jsonl under $CODEX_HOME/sessions
+ExternalTranscript.decodeClaude(state, chunk) // <session>.jsonl under ~/.claude/projects/<project>
+```
+
+Each returns `Result<Decoded<State>, ExternalTranscriptError>`: the entries the
+chunk completed and the state to pass with the next chunk. Both are pure. They
+read no file, clock, network or process, register no importer and publish
+nothing. The reference for every type is [api.md](api.md#externaltranscript).
+
+## Machine side
+
+The bytes a decoder gets are one line of one file, framed in the member's
+machine by `smithers-machined` (spec §9.6.6). No decoder runs there.
+
+```
+member's terminal session        root broker                     daemon (uid 19998)
+┌────────────────────┐ kernel  ┌─────────────────────┐  list   ┌────────────────────┐
+│ codex / claude     │─facts──▶│ discovery           │◀────────│ pump, 4 passes/s   │
+│ (member's uid)     │         │ resolver (owner uid)│ socket  │ one reader/source  │──▶ outbox ──▶ variant 5
+└────────────────────┘         │ reader (owner uid) ─┼────────▶│ checkpoint/source  │
+                               └─────────────────────┘         └────────────────────┘
+```
+
+- **Which process is an agent.** A process in a roster member's own terminal
+  session, with every uid the member's, whose executable is `codex`, `claude`
+  or `claude/versions/<release>`, whose agent home is beneath the member's home
+  (`CODEX_HOME` or `CLAUDE_CONFIG_DIR` is honored only there), and which is
+  linked to exactly one transcript: the rollout a Codex process holds open, or
+  the session a Claude Code process names in `sessions/<pid>.json`. A coding
+  run's session is the factory's and is never read.
+- **Who reads.** Root reads kernel facts about processes and opens no home. A
+  child running as the member answers which file is the transcript and which
+  release wrote it; another tails that one file beneath the member's agent
+  root without following a link. The profile is `<family>/<major.minor>` of
+  that release.
+- **Participants and sources.** A participant is one agent process. A source
+  is one file of that process. `/clear` in Claude Code starts a new source of
+  the same participant. A record's identity is its source, generation and byte
+  range, so a replay after a reconnect or a restart is the same record.
+- **Stopping.** A record the host refuses stops its source for the life of the
+  process. A removed member's readers are killed with their sessions.
+
+## Host caller
+
+```
+machine (member's uid)                 host                         PostgreSQL
+┌──────────────────────┐   record    ┌──────────────────────┐
+│ owner-uid reader     │──variant 5─▶│ backend ingest       │
+│ frames whole lines   │   (bytes)   │  registry binding ───┼──▶ who owns it
+└──────────────────────┘             │  POST /v1/transcript/│
+                                     │       normalize ─────┼─▶ model-host: decodeCodex / decodeClaude
+                                     │  entries + checkpoint│
+                                     │  + receipt, one tx ──┼──▶ chat_turns, machine_event_receipts
+                                     └──────────────────────┘
+```
+
+The install-shipped caller is `apps/model-host/src/transcript.ts`, served at
+`POST /v1/transcript/normalize` behind the host bearer. The backend sends one
+framed record, the profile the registry pinned, the registry's owner,
+participant and session, and the decoder state from the previous committed
+receipt. The host decodes that one record and returns drafts and the next
+state. It keeps no state between requests.
+
+```ts
+const result = profile.startsWith("codex-rollout/")
+  ? ExternalTranscript.decodeCodex(state ?? ExternalTranscript.codexStart, record + "\n")
+  : ExternalTranscript.decodeClaude(state ?? ExternalTranscript.claudeStart, record + "\n")
+if (Result.isFailure(result)) {
+  // Refuse the request with result.failure.code. The backend commits no entry and does not advance the receipt.
+} else {
+  // Stamp each entry with the registry's owner and participant, then return result.success.state as the checkpoint.
+}
+```
+
+Rules the caller keeps:
+
+- **Identity comes from the registry.** An entry's `role` says whether the
+  owner or the agent side authored it. The caller maps `user` to the
+  registered owner and `assistant` to the registered agent participant. A
+  name, session or role written in a transcript confers nothing; the decoded
+  `session_id` is the agent's own id and never selects a member or a branch.
+- **One record per call, in order, per source.** A failed decode returns no
+  entries from its chunk, so a caller that sends one record keeps every entry
+  before the refused one.
+- **The state is the checkpoint.** It is plain JSON, held tool requests
+  included. Decoding the same record from the same state yields the same
+  entries and `source_id`s, so a replay after a crash is idempotent.
+- **A refusal stops that source.** The caller shows the import as stopped and
+  never retries under a newer profile.
+- **Nothing decoded runs.** A command, a patch or a script in an entry is
+  text. No prompt is queued, no model is called and no run is created.
+
+T-AGT-02 owns discovery, the owner-uid reader, framing, the receipt
+transaction and publication. T-AGT-03 owns the conversation view.
+
+## Why two decoders and no framework
+
+`Transcript.projectResult` projects harness journal entries into model
+messages; it does not parse another agent's JSONL.
+`GatewayProjection.transcript` needs an executable `runId`, so feeding it an
+external record would invent a run. `EntryRowCard` and `CardPrimitives.Actor`
+describe presentation and participants; neither decodes a source record. The
+smallest missing piece is one decoder per format. There is no adapter
+interface: two callers of two functions do not need one.
+
+## Profiles
+
+Neither format carries a schema version, so the profile is the CLI release
+line that wrote the record.
+
+| Agent       | Profile                       | Named by                               | Releases read                 |
+| ----------- | ----------------------------- | -------------------------------------- | ----------------------------- |
+| Codex       | `codex-rollout/<major.minor>` | `session_meta.payload.cli_version`     | `codexReleases`: 0.159, 0.160 |
+| Claude Code | `claude-code/<major.minor>`   | `version` on every conversation record | `claudeReleases`: 2.1         |
+
+| Error code            | When                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `missing_version`     | A Codex row before `session_meta`; a Claude Code conversation record with no `version`     |
+| `unsupported_version` | A release outside the lists above, or none                                                 |
+| `unsupported_record`  | A complete record, event, item, status line, attachment or block of a kind not named below |
+| `malformed_record`    | A complete line that is not a JSON record, or a named kind in another shape                |
+
+An incomplete last line is not an error: it waits in `state.pending` for its
+newline.
+
+## Mapping: Codex
+
+| Source                                                                                                 | Entry                                                                                                       |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `event_msg` `item_completed` `UserMessage`                                                             | The owner's `prompt`                                                                                        |
+| `item_completed` `AgentMessage`                                                                        | `text`, `final` for the turn's answer; `encrypted` when the body is ciphertext                              |
+| `item_completed` `Reasoning`                                                                           | `reasoning` when Codex wrote a summary; otherwise nothing                                                   |
+| `item_completed` `CommandExecution`                                                                    | `tool`: command, `reads` labels, status, exit code, output, duration                                        |
+| `item_completed` `FileChange`                                                                          | `edit`: each file's unified diff, `applied` or `failed`                                                     |
+| `item_completed` `Extension` (web search)                                                              | `search`                                                                                                    |
+| `item_completed` `SubAgentActivity`, `CollabAgentToolCall`                                             | `helper`                                                                                                    |
+| `item_completed` `McpToolCall`, `FunctionCallOutput`, `ImageView`                                      | `tool`                                                                                                      |
+| `item_completed` `ContextCompaction`                                                                   | `compaction`                                                                                                |
+| `event_msg` `thread_goal_updated`                                                                      | The owner's `goal`, once per objective and status                                                           |
+| `event_msg` `task_complete` with `error`                                                               | `error` with Codex's message (usage limit, capacity, a refused request)                                     |
+| `event_msg` `turn_aborted`, `error`                                                                    | `error` with the reason or message                                                                          |
+| `response_item` `agent_message` with `encrypted_content`                                               | One `encrypted` placeholder for the whole body, header included                                             |
+| `response_item` `agent_message`, readable                                                              | The agent side's `text`                                                                                     |
+| `response_item` `custom_tool_call`                                                                     | Held in `state.calls` until its output; no entry                                                            |
+| `response_item` `custom_tool_call_output` reporting a failed script                                    | Failed `tool` with the requested script as its command; plus a failed `edit` for a patch that did not apply |
+| `response_item` `custom_tool_call_output`, script completed or still running                           | Nothing: its completed items already say it                                                                 |
+| `response_item` `message`, `reasoning`, `function_call`, `function_call_output`                        | Skipped by name: the model-facing copy                                                                      |
+| `event_msg` `task_started`, `token_count`, `thread_settings_applied`, `task_complete` without `error`  | Skipped by name                                                                                             |
+| `session_meta`                                                                                         | Selects the profile and session                                                                             |
+| `turn_context`, `world_state`, `token_usage_record`, `compacted`, `inter_agent_communication_metadata` | Skipped by name                                                                                             |
+| Anything else                                                                                          | `unsupported_record`                                                                                        |
+
+Codex encrypts every `response_item` `reasoning` body. Reasoning is not a
+message: without a summary it has nothing to show, like Claude Code's
+signature-only thinking, and it is skipped. A failed edit's diff is empty
+because the report names a file and no change; the patch the agent asked for
+stays in the failed `tool`'s command. An edit is what the agent reported, never
+an observed write.
+
+## Mapping: Claude Code
+
+| Source                                                                                                                                                                                                        | Entry                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `user` text the owner wrote (`origin` `human` or none)                                                                                                                                                        | `prompt`; a slash command reads `/<name> <args>`, a shell command `!<command>`        |
+| `user` `[Request interrupted by user…]`                                                                                                                                                                       | `error` with that text                                                                |
+| `user` `isMeta`, `isCompactSummary`, another origin, local command output                                                                                                                                     | Nothing: skill bodies, summaries, task notifications, peer messages                   |
+| `assistant` `text`                                                                                                                                                                                            | `text`, `final` when `stop_reason` is `end_turn`                                      |
+| `assistant` `thinking` with a body                                                                                                                                                                            | `reasoning`                                                                           |
+| `assistant` empty `thinking`, `redacted_thinking`, `fallback`                                                                                                                                                 | Nothing                                                                               |
+| `assistant` with `isApiErrorMessage`                                                                                                                                                                          | `error` with Claude Code's message                                                    |
+| `assistant` `tool_use`                                                                                                                                                                                        | Held in `state.calls` until its result; no entry                                      |
+| `user` `tool_result` for `Bash` and any other tool                                                                                                                                                            | `tool`: command, `ok` or `error`, exit code, output, duration                         |
+| `tool_result` for `Read`, `Grep`, `Glob`, `LS`                                                                                                                                                                | `tool` with a `reads` label                                                           |
+| `tool_result` for `Edit`, `Write`, `MultiEdit`, `NotebookEdit`                                                                                                                                                | `edit`: reported hunks, or the requested change; `failed` when the result is an error |
+| `tool_result` for `WebSearch`, `WebFetch`                                                                                                                                                                     | `search`                                                                              |
+| `tool_result` for `Agent`, `Task`                                                                                                                                                                             | `helper`                                                                              |
+| `system` `compact_boundary`                                                                                                                                                                                   | `compaction`                                                                          |
+| `system` `turn_duration`, `informational`, `stop_hook_summary`, `away_summary`, `api_error`, `local_command`, `scheduled_task_fire`, `agents_killed`, `model_refusal_fallback`                                | Skipped by name: status lines                                                         |
+| `attachment` `queued_command` the owner typed                                                                                                                                                                 | `prompt`                                                                              |
+| `attachment` of the 44 named context types                                                                                                                                                                    | Skipped by name: context for the model                                                |
+| `mode`, `permission-mode`, `atis-latch`, `last-prompt`, `ai-title`, `custom-title`, `agent-name`, `queue-operation`, `file-history-snapshot`, `file-history-delta`, `cost-state`, `pr-link`, `bridge-session` | Skipped by name: bookkeeping                                                          |
+| `isSidechain` records                                                                                                                                                                                         | Nothing: a subagent's own transcript                                                  |
+| Anything else                                                                                                                                                                                                 | `unsupported_record`                                                                  |
+
+A tool call becomes one entry at its result's record, so two calls issued
+together appear in the order their results arrive. A call whose result has
+not arrived stays in `state.calls` and has no entry yet.
+
+## Evidence
+
+`test/fixtures/external/manifest.json` lists five captures. Each directory has
+the transcript the CLI wrote, the committed `expected.json` and a `MANIFEST.md`
+with the capture procedure, record shapes and redactions.
+
+| Capture                      | Release | Where                                      | Covers                                                                                                |
+| ---------------------------- | ------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `codex-0.160`                | 0.160.0 | Maintainer's interactive session, macOS    | Two turns, commands, searches, edits, helpers, an encrypted message body, a goal                      |
+| `codex-machine-0.160`        | 0.160.0 | Unprivileged member in a microVM, Mac mini | Applied edits, a failed edit, a command that exited 7                                                 |
+| `codex-signed-out-0.160`     | 0.160.1 | `codex exec` in an empty temporary home    | A turn that ended in a failure Codex reported                                                         |
+| `claude-code-2.1`            | 2.1.277 | Maintainer's interactive session, macOS    | Turns, commands, searches, applied and failed edits, an interruption, a usage-limit error, compaction |
+| `claude-code-signed-out-2.1` | 2.1.291 | `claude -p` in an empty temporary home     | An authentication error Claude Code reported                                                          |
+
+Tests compare decoder output with the committed files and never regenerate
+them. Every capture is replayed whole, from every split at a record boundary
+and one record at a time from a state restored from JSON. Rows a test builds
+by hand are labeled constructed and are not golden evidence.
+
+The named kinds come from every transcript on the capture machine: 4,309
+Claude Code files from 2.1.261 to 2.1.291 and 1,029 Codex rollouts from
+0.159.0 to 0.160.1 decode with no tagged error (2026-10-08).
+
+`test/ExternalTranscript.live.test.ts` runs the installed `claude` and `codex`
+in empty temporary homes, lets each write its own transcript and decodes it as
+a tail would. It reaches the network, so it runs only with
+`SMITHERS_REAL_AGENT_CLI=1`.
+
+## Limits
+
+- A member's Claude Code session captured inside a machine, with tool calls
+  and edits, is pending on the reference Mac mini. The Claude Code captures
+  here ran on a maintainer's Mac.
+- A release line outside the lists is refused. Reading a new line means
+  capturing a session, adding its `major.minor` and naming any new kinds.
+- The machine side has run on an arm64 Linux kernel with stand-in agent
+  processes, not yet in a microVM with the real CLIs.
+- Claude Code started through a Node launcher is not found: its executable is
+  `node`. The native install is.
+- A byte that is not UTF-8, or a NUL, reaches a decoder as `?`, one byte for
+  one, and an empty line as leading whitespace of the next record. Neither
+  stops a source.
+- A line over 1 MiB stops its source in the machine. No entry says so yet.
+- An agent process is a participant of its entries but is not yet in
+  presence; that needs a wire addition too.
+- smithers-38 has not signed off the exports or the §21.1 evidence.
+- No §21.1 benchmark hot path changes: decoding is linear in the bytes given.

package/docs/guides/bind-flows.md

@@ -0,0 +1,167 @@
+---
+title: "Expose flows to cells"
+description: "How to pair a flow declaration with its handler using FlowBinding, compose bindings into a catalog, disclose them through a registry, and resolve ctx.call with CellCalls."
+sidebar:
+  order: 2
+---
+
+A cell's only authority is `ctx.call(flowName, input)`, so every capability an
+agent can reach has to arrive as an ordinary flow declaration plus the code
+that runs it. Standard host capabilities, incoming MCP tools, and subagents
+all take this one shape. `FlowBinding` pairs the two halves; `CellCalls`
+resolves a call name against the registry and dispatches to the body the
+declaration names.
+
+## Bind one flow
+
+`FlowBinding.make` takes a flow declaration and a handler:
+
+```ts
+import * as FlowBinding from "@smthrs/harness/FlowBinding"
+import { Effect, Schema } from "effect"
+
+const echo = FlowBinding.make({
+  flow: {
+    name: "echo",
+    description: "Echo one string back.",
+    input: Schema.Struct({ text: Schema.String }),
+    output: Schema.Struct({ text: Schema.String, length: Schema.Number }),
+    capabilities: [],
+    effects: { reads: [], writes: [], mode: "hermetic", onConflict: "serialize", tier: "sealed" }
+  },
+  handler: (input) => Effect.succeed({ text: input.text, length: input.text.length })
+})
+```
+
+The declaration is the `FlowBinding.Declared` shape plus `input` and `output`
+schemas; the `Flow.make` declarations of [`@smthrs/core`](/api/core) satisfy
+it as-is. The handler receives the decoded input and the `Cell.Call` itself,
+because a handler that opens a durable boundary of its own needs
+`call.identity` as a replay-stable name for it.
+
+A binding is `{ descriptor, run }`:
+
+- `descriptor` is an ordinary `FlowDescriptor` from
+  [`@smthrs/registry`](/api/registry), projected by
+  `FlowBinding.descriptorOf`. `make` derives the body's content digest from
+  the handler source and renders both schemas as inline JSON Schema documents,
+  which is what puts a parameter schema beside the flow in `ctx.flows`.
+- `run` decodes the call's input through the input schema, executes the
+  handler, and validates the handler's output back into serializable JSON.
+
+A handler with remaining service requirements produces a `Binding<R>`; close
+them with `FlowBinding.provide(binding, context)` before composing.
+
+## How a call settles
+
+Inside `run`, every failure lands where the cell contract says it must:
+
+- Input the schema rejects settles as a resolved `invalid_input` failure
+  without running the handler. For struct inputs, a failed decode retries once
+  with `null` omitted only from declared optional fields that reject it on the
+  encoded side. Schema-valid nulls remain present; the full schema validates
+  the retry. If it still fails, the original rejection is reported.
+  The encoded input must be a struct-like object; unions of structs and
+  records get no null-omission retry.
+- An ordinary handler failure settles as a resolved `flow_failed` with the
+  opaque message `Flow <name> failed.` No raw error message, object, or cause
+  enters the call result or its journal record.
+- Output the output schema rejects, or that is not serializable, settles as
+  `flow_failed` naming which.
+- Existing `HarnessError` values pass through the error channel unchanged,
+  preserving their code and identity.
+- `PermissionRequired` and `PermissionDenied` become `HarnessError` values
+  with code `suspended`, so a cell cannot ignore its own permission park.
+  Interruptions are never caught.
+
+A binding can opt safe details into the public failure using
+`publicError: (error: E) => string | undefined`. Select only fields approved
+for cells and journals, for example a public status code. The returned text
+is bounded before it enters the call result. Returning `undefined`, throwing,
+or returning a non-string at runtime uses the opaque default. Harness and
+permission errors bypass this renderer.
+
+Raw diagnostics remain in the host handler. Inspect them there, for example
+with `Effect.tapError`, and redact credentials before logging or persisting
+anything. `publicError` is an explicit disclosure decision, not a sanitizer;
+forward `message` only for error classes the host authored with model-facing
+text; never forward messages of transport, SDK, OS, or unknown errors,
+headers, URLs, or serialized causes.
+
+## Compose a catalog
+
+`FlowBinding.Source` produces bindings, possibly effectfully, so a lazily
+connected server or a plugin contributes without being resolved at import
+time. `FlowBinding.source(name, bindings)` lifts a fixed list into one.
+`FlowBinding.catalog` resolves ordered sources into one
+`FlowBinding.Catalog`:
+
+```ts
+const catalog = await Effect.runPromise(
+  FlowBinding.catalog([FlowBinding.source("standard", [echo])])
+)
+```
+
+A catalog refuses two implementations under one name: `catalogResult` fails
+with a `HarnessError` of code `assembly_failed`, because one descriptor
+dispatched to another implementation is how a call runs the wrong body. An
+unnamed binding fails the same way with its own message.
+`FlowBinding.empty()` is the empty catalog.
+
+## Disclose through a registry
+
+`FlowBinding.registry(base, catalog)` discloses a catalog's descriptors
+through an existing `Registry.Registry`:
+
+- File-discovered entries keep their names: a binding whose name a discovery
+  source already found is not disclosed, and the shadowed binding is reported
+  as an ordinary `duplicate_name` warning. Discovery precedence stays exactly
+  where discovery put it.
+- `list`, `visible`, `getOption`, and `get` answer from both sources; body
+  loading, prompt rendering, and refresh pass through to the base registry.
+
+## Resolve calls with CellCalls
+
+`CellCalls.make` turns a call name into the body that answers it:
+
+```ts
+import * as CellCalls from "@smthrs/harness/CellCalls"
+
+const resolver = CellCalls.make({
+  registry,
+  catalog,
+  implementations: new Map(),
+  prompt: runMarkdownFlow
+})
+```
+
+The resolver's `run` has exactly the shape a durable host's call runner
+consumes, so the host wires it in behind `EngineLike.call`. Resolution works
+in this order:
+
+1. The registry must know the name, or the call settles `unknown_flow`.
+2. The descriptor must be model-invocable, or the call settles
+   `capability_refused`.
+3. The descriptor's declaration digest must equal the digest folded into the
+   call's identity, or the call settles `declaration_changed`. The registry is
+   refreshable, and this check is what keeps a call bound to the declaration
+   the agent was shown.
+4. An executable binding answers first, after an identity check that the
+   binding's declaration is the disclosed one. A markdown flow renders against
+   the call's arguments and runs through the `CellCalls.PromptRunner` the host
+   supplied, or settles `unimplemented` when the host runs none. Anything else
+   dispatches to the host's `Implementation` for the name, or settles
+   `unimplemented`.
+
+Every refusal is a `failure` `Cell.CallResult` that resolves in the cell as
+`{ ok: false, error }`. Inspect `.ok === false` and `.error.code` to recover;
+ordinary refusals do not throw.
+
+## Next steps
+
+- To run cells against the bound catalog, see
+  [Run cells in a persistent realm](./run-cells.md).
+- To wire the resolver into the controller's durable call boundary, see
+  [Drive the cell loop](./drive-the-loop.md).
+- For the contract details, see [`FlowBinding`](../api.md#flowbinding) and
+  [`CellCalls`](../api.md#cellcalls) in the API reference.