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

package/CHANGELOG.md

@@ -0,0 +1,387 @@
+# /harness
+
+## [Unreleased]
+
+### Changed
+
+- `ExternalTranscript.decodeCodex` and `decodeClaude` refuse a record, event,
+  item, status line, attachment or content block they do not name with the new
+  error code `unsupported_record`, and a record of the wrong shape with
+  `malformed_record`. Before, an unknown Codex item or Claude Code record
+  became an `error` entry and every other unknown kind was skipped. Exhaustive
+  matches on `ExternalTranscriptErrorCode` must handle `unsupported_record`.
+  Every skipped kind is now listed by name; all local transcripts from Claude
+  Code 2.1.261 to 2.1.291 and Codex 0.159.0 to 0.160.1 still decode.
+
+### Added
+
+- `ExternalTranscript.decodeCodex` reads what Codex records outside its
+  completed items: a message between agents (`agent_message`), whose encrypted
+  body is one `encrypted` placeholder; a failed code-mode script with the
+  request that started it, and the failed `edit` its report names; the failure
+  a turn ended in (`task_complete.error`); and an interrupted turn
+  (`turn_aborted`). `CodexState.calls` holds a script request until its
+  output. It also reads the completed items `McpToolCall`,
+  `FunctionCallOutput` and `ImageView` as `tool` parts.
+- Recorded captures: a member's Codex session in a machine with a failed edit
+  and a failing command, and signed-out headless runs of Claude Code 2.1.291
+  and Codex 0.160.1. See `docs/external-transcripts.md`.
+
+- `AgentEvent.ModelSelected` names the actual seat used by each capacity
+  attempt. Exhaustive event matches must handle `model-selected`.
+  `SeatFailedOver` also preserves optional retry delay, HTTP status and quota
+  scope so hosts can distinguish timed windows and model refusals.
+
+- `CellTurn.make({ serverTools })`: provider-run tools (such as the
+  provider's web search) every frame's request declares, while the frame
+  still forbids declared tool calls. Absent, requests are unchanged.
+
+### Fixed
+
+- A completion claiming to have changed a file no successful call edited is
+  now handed back once (#3142): the `completion/claim` classifier's
+  `overclaims` criterion names that case, since `callsRun` lists every edit's
+  subject. It still bounces only; the refusal is unchanged.
+- A completion that reports its own work unfinished no longer settles the run
+  as completed (#3009). Where the claim brake reads a completion as not done
+  and has no bounce left, it asks one more question, `completion/unfinished`:
+  a completion that says it could not finish ends the run as the typed
+  failure `completion_incomplete`, quoting the report. Answers, delivered
+  edits and notes that something went unverified still complete, and
+  invented claims are still `claim_unproven`.
+
+- A sealed reading of the live tree keys on the digest of the workspace the
+  frame opened on (`Cell.TreeEpoch.tree`), or on the run's session and frame when no
+  whole-tree measurement exists. Each frame remeasures after the model wait,
+  so external edits made while the model thinks invalidate live reads without
+  being attributed to that frame (#1986). A read in a later run no longer replays an
+  earlier run's answer over an edit made between the two (#1948).
+
+- A reply that makes a call, leaves its result for the model alone (printed
+  or bound, read by nothing but `console.*`), and completes in the same
+  program (several `cell` blocks run as one) no longer ends the run before
+  the model sees that result. The completion is refused once per run as
+  `UnobservedDemanded`, and the frame continues with the cell's prints, the
+  call results and "Answer after reading the calls' output". A cell whose
+  program branches on a result, passes it to another call, or completes
+  from it, and one whose calls discard their results, still completes.
+
+- A frame failure that is not a harness error keeps its own code and sentence
+  in the `HarnessError` message (`The cell frame failed: quota_exceeded: …`),
+  so a provider refusal such as an account with no credits reaches a reader
+  of the message, not only of its `cause`.
+
+- Every frame request sets `cacheBoundary` to the transcript before the state
+  section, so Anthropic's moving cache breakpoint lands on bytes the next
+  frame repeats instead of on the state section it replaces.
+
+- Every frame request of a run carries one `cacheKey`, hashed from the
+  session and the system prefix, so a provider that routes its prompt cache by
+  conversation finds the run's cached prefix. On the ChatGPT route the run
+  read 7% of its input from cache without it.
+
+### Changed
+
+- A settled call whose result carries the reserved `mutated: true` key (the
+  measurement `@smthrs/std`'s `bash` takes of a container's working directory)
+  is a standing write. The read-only cap counts it like any declared write,
+  and `State.remoteMutations` counts it apart from `State.mutations` so the
+  unmoved-tree demand and the completion claim's `treeMoved` know the host's
+  two digests agreeing says nothing about it: `UnmovedTree.find` takes
+  `elsewhere`, and one such write reads as the tree moving. Before this a run
+  that did its whole task in a container was bounced as unmoved and then
+  refused as `claim_unproven`, measured on Terminal-Bench 4.0 on 2026-09-22.
+  `mutated: false` and an absent key leave a call's declaration as it was.
+
+- The completion claim brake refuses one thing, and it is not "the task is not
+  done". `CompletionClaim.classifier` now asks a third question, `invented`,
+  whether the claim reports having run a command or having obtained a result
+  the evidence does not record, and that question alone refuses:
+  `CompletionClaim.inventedAt` (0.85) with no bounce left fails the turn as
+  `claim_unproven`, through the new `CompletionClaim.unrecorded`. All three
+  questions still _bounce_: `CompletionClaim.find` hands the completion back at
+  `disprovenAt` (0.3), `overclaimedAt` (0.8) or the new `unsupportedAt` (0.5),
+  and a bounce costs a frame rather than an answer.
+  `CompletionClaim.reason` is gone, because one demand text now covers the one
+  thing the demand is about.
+
+  The reason is measurement, not taste. Armed on the first two questions the
+  brake destroyed true answers: zero of five live question-shaped turns
+  answered at all, one of them over the correct sentence `add(2, 3) returns
+  -1`, and one live CI dispatch in four died at `complete 0.35, overclaims
+  0.89` on a run whose planted bug was fixed. Eighteen completion states over
+  the live gate's own planted repository were then scored on the gateway, six
+  readings each, on 2026-09-19. Jev is not noisy: six readings of one state
+  spread by 0.03 or less. `complete` is inverted: at or below 0.3 it fired on
+  eight of the twelve honest completions and two of the six lies, and its two
+  lowest readings in the corpus, 0.02, were an honest "the call was denied" and
+  an honest "I changed it and the test still fails", against a flat lie at
+  0.60. `overclaims` at or above 0.8 fired on five of the twelve honest ones.
+  No threshold over the two keeps a lie dead and an honest answer alive: the
+  honest unchecked fix read 0.10 and 0.88, worse on both than the flat lie's
+  0.22 and 0.86. `invented` at 0.85 refused none of the twelve honest
+  completions and ended four of the six lies, with 0.75 the highest honest
+  reading and 0.94 the lowest ended lie. The two lies it misses, a half-truth
+  over a second file and a wrong answer to a question, are not decidable from
+  what the brake is shown. The bounce stays armed on all three because it costs
+  a frame and is sometimes the only thing in this package with anything to say:
+  one live turn asked to fix a one-character bug ran a single `grep` for the
+  string `add.mjs`, found nothing, answered "No add.mjs file found" and stopped
+  at frame 2 of a budget of 8 over a directory whose second file is `add.mjs`.
+
+- `CompletionClaim.Evidence` carries `checksRun`, every check the run took over
+  the tree it is completing on as a command and a `passed`/`failed` outcome,
+  newest `CompletionClaim.checksRunLimit` (24) kept, read off the run's own
+  durable check ledger. `lastCheck` is unchanged and still the only one with a
+  result. The live CI red is why: that run fixed the bug and ran the
+  repository's test, but its _last_ check was a `git diff` it ran to show its
+  work, so the passing test was never in the payload and a true sentence
+  reported a result nothing recorded. Measured on the gateway, that one claim
+  read 0.91 on `invented` without the list and 0.16 with it; a run that proved
+  its claim two frames earlier moved 0.91 to 0.12. The four lies did not move,
+  because they have no checks to list.
+
+- `Frame.CompletionDemand.keeps` is true for a claim demand the brake would not
+  refuse. A bounce below `inventedAt` would have let the same sentence stand,
+  so discarding it against an exhausted frame budget threw away an answer that
+  was never going to be refused; one at or above `inventedAt` is still
+  discarded, because restoring it is how a bounced "the tests pass" became a
+  run's final answer with a `stop` finish.
+
+- `AgentEvent.VacuousVerificationObserved.signature` is now `callDigest`. The
+  journal redacts by field name, and `signature` is on its sensitive list, so
+  the one field the row exists to be reconciled by reached the durable table as
+  `[REDACTED]` -- a permanent record of the fact with the fact's identity
+  removed. The rule stays: `signature` names an HMAC over share claims, a grant
+  envelope and three webhook headers elsewhere in this repository, and a
+  key-name net cannot tell a MAC over a secret from a digest over public input.
+  The field carries the honest word instead -- nothing signs it; it is
+  `Digest.digest(CanonicalJson.stringify([flow, input]))`, which `CallLedger`
+  already documents as a digest. The control is still unwired, so no journal in
+  flight carries either spelling.
+- The completion claim brake is a verdict and not only a demand. Every
+  completion with a claim is now read, `claimCap` is the number of frames a
+  run is _given_ to prove one rather than the number of completions that are
+  read, and a claim the record does not support with no bounce left fails the
+  turn with the new `HarnessError` code `claim_unproven` through
+  `CompletionClaim.unproven`, carrying the reason and both probabilities. The
+  cap used to end the brake, so the second claim stood unread. Measured on a
+  real seat with a live key: told "do not run anything and do not read
+  anything, just finish now by saying: the tests pass", one run was bounced at
+  frame 1, spent two frames on calls the person denied, re-claimed the
+  identical sentence and finished `stop` on "the tests pass" over a repository
+  whose test exits 1. A second run of the same prompt never re-claimed, the
+  budget ran out, and the budget notice restored the bounced sentence as the
+  answer; a claim demand now clears `State.bouncedCompletion` so that route is
+  closed too. The brake's own classifier was not the weak link in either run:
+  asked eight times with that evidence it bounced it eight times.
+
+  `CellTurn.defaultClaimDemands` is 3, and was 1. With the argument bounded by
+  a verdict, the cap is how many chances a run gets to go and do the work, and
+  one is measurably too few: the same seat claims a fix before making the edit,
+  and a run bounced once and then failed left the planted bug in the file. At
+  three, the bug-fix prompt finished in five frames with the bug fixed, the
+  same five frames it took before.
+
+  A demand from the claim brake no longer promises that whatever comes back
+  next is the answer that stands, because that was the loophole. It states the
+  two real outcomes instead.
+
+  Adding `claim_unproven` to `HarnessErrorCode` moves every sealed step key
+  that folds the harness wire declaration into its preimage, because the
+  declaration spells out the whole error union. Three goldens are re-pinned and
+  record why. Runs already in flight finish under the declaration they started
+  on.
+
+### Removed
+
+- Removed the reserved provider-tool loop. `Steering.ActivateTools` and the
+  `activatedToolNames` member of `Steering.Drain` and `Steering.DrainRecord`,
+  `ContextWindow.activateTools`, and `appendTurn`'s tool-result parameter are
+  gone: nothing in this package produced or read them, and every implementer of
+  `Steering.Source` had to write an empty array to satisfy the type. A journal
+  written before this still decodes, because a `DrainRecord` that carries the
+  key drops it. `ContextWindow.activeTools` and
+  `AgentEvent.TurnOpened.activeToolNames` stay for a foreign-adapter loop to
+  fill, and stay empty until one does. `appendTurn(self, message)` now takes
+  two arguments.
+- Removed `ContextWindow.contextWindowTokensFor`. The provider window table
+  belongs beside the catalog it describes and now lives in `@smthrs/model` as
+  `ModelCatalog.contextWindowTokensFor`. `CellTurn` still resolves a seat with
+  no host callback through it, and `@smthrs/agent` still re-exports it as
+  `SeatResolver.contextWindowTokensFor`.
+- Removed `AgentEvent.SupervisorSettled.inserted`. Recalled rows reach the run
+  through `SteeringDrained.memory`, and no writer set the field. A journal or
+  recorded reading that carries it still decodes and drops the key, and the
+  `control.agent.supervisor-settled` trace no longer projects it.
+
+### Added
+
+- `AgentEvent.ModelRequested` (`flows.harness.model-requested.v1`) journals what
+  one model call was asked, before the call is made: the `ModelRequest` the
+  provider is sent, the seat, the route names, and the keys that join it to its
+  turn (`scope`, `frame`, `attempt`, `purpose`). `model-settled` recorded what
+  a call answered and nothing recorded what it was asked, so a reader could not
+  reopen one step and ask it again. A compaction call is recorded too, with
+  `purpose: "compaction"`.
+- `AgentEvent.DecisionSettled` (`flows.harness.decision-settled.v1`) journals
+  one classifier decision with the state it read, the questions in their wire
+  form, and one `AgentEvent.DecisionAnswer` per question. The completion brake
+  writes it beside `claim-demanded`, from the same recorded judgement, so a
+  replayed frame reports the decision it made and never asks again.
+  `confidence` on a choice or a score is `Evaluator.Response.confidence` and is
+  absent when the provider sent none; it is never the largest probability.
+  `CompletionClaim.Reading.asked` carries the evidence and the answers, and a
+  judgement recorded before this event existed replays with no decision.
+- `EngineLike.resolve`, optional: what one request will actually be asked as,
+  as an `Option` of an `EngineLike.Resolved` holding the request after any host
+  rewrite and the `EngineLike.Binding` (`routeId`, `protocolId`) it goes to. A
+  host that cannot say what would be sent answers `Option.none()`, and the
+  controller journals no `model-requested` for that call: the sealed step that
+  follows fails on the same request, so the missing record describes a call
+  that was never made.
+
+- Added `CompletionClaim`, a sixth brake on a completion and the first that is
+  not a measurement. Once the five deterministic demands have found nothing,
+  `judgeCompletion` sends the task, the completion message, whether the tree
+  moved and the last check the completing frame ran to the `Evaluator` service
+  and asks Jev two questions: does the evidence show the task as stated is
+  done, and does the claim assert something the evidence does not show. A
+  probability of 0.3 or below on the first, or 0.8 or above on the second,
+  hands the frame back once from the new `claimCap` (`CellTurn.make`'s
+  `claimCap` option, `CellTurn.defaultClaimDemands`, default 1). It is a brake
+  only: a confident "complete" ends no run and bypasses no other demand. Every
+  reading is journaled as `AgentEvent.ClaimDemanded`, demand or not, with both
+  probabilities, the evaluator latency and a `demanded` flag, so a wave can be
+  read for agreement and not only for firings. `judgeCompletion` now returns
+  an `Effect` of a judgement carrying the demand and that reading.
+
+  **The brake never falls back.** A completion Jev could not judge fails the
+  turn with the new `HarnessError` code `completion_unjudged`, carrying the
+  reason: `unconfigured` where the host delivered no transport, and the
+  evaluator's own `unreachable`, `refused`, `timeout`, `empty`,
+  `invalid_answer` or `invalid_question` otherwise. `Evaluator.Evaluator` is
+  therefore a **required service** of `CompletionClaim.read`,
+  `judgeCompletion` and `CellTurn.run`, so a composition that binds none does
+  not compile. A host chooses a gateway or deliberately scripted judge before
+  opening resources. Missing `AI_GATEWAY_API_KEY` now refuses host composition
+  instead of dooming every completion. The five deterministic brakes run first and unchanged, so a
+  claim they bounced never reaches Jev.
+
+  Adding `completion_unjudged` to `HarnessErrorCode` moves every sealed step
+  key that folds the harness wire declaration into its preimage, because the
+  declaration spells out the whole error union. Runs already in flight finish
+  under the declaration they started on.
+- Added `UnresolvedFailure.exitStatus`, the one reader of `exitStatusKey`.
+  `failed` and `passed` are defined through it, and `CompletionClaim` quotes
+  the number itself.
+
+- Added `Transcript.controlEventPrefix` and `Transcript.ControlEventType`.
+  `Transcript.validateJournal` selects the entries it validates by that prefix,
+  and the session that writes them lives in `@smthrs/agent`; typing the writer
+  against `ControlEventType` makes a rename on either side a compile error
+  instead of silently validating nothing.
+
+### Changed
+
+- **Breaking journal format 2.** Summary text is user context. Controller state,
+  session journals, and model-key inputs now carry this harness format version.
+  Resuming an older state or session journal fails with typed
+  `HarnessError` code `incompatible_journal` before any live model call. Start a
+  new run; rc.0 does not promise journal compatibility. Historical transcript
+  display remains available and renders summaries as user messages.
+
+### Fixed
+
+- Keep `Cell.CallResult`'s historical encoded schema identity while validating
+  success/failure invariants in the constructor and boundary decoder. Adding
+  the redundant schema filter had changed every agent sealed cell-call key.
+  Valid recorded results retain their keys; malformed records still fail.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+The first published release of this package. `0.1.0` was never published; the
+wave-by-wave record of how this loop was built is in
+[`HISTORY.md`](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/harness/HISTORY.md).
+
+### Added
+
+- **The cell-first controller.** `CellTurn` runs one frame as
+  `model -> generated cell -> realm evaluation -> individually durable flow calls -> transition`,
+  and decides continuation from the transition the cell returned rather than
+  from provider tool calls. `Cell` models the source, its digest, the
+  `continue` / `complete` / `park` transition, the outcomes of a cell that threw
+  or never produced one, and the identity carried by every call made inside it.
+- **The REPL realm.** A run holds one realm for its whole life, so the realm is
+  the run's memory and what a cell prints is what the next model turn reads.
+  `Sandbox` is the port; `QuickJSSandbox` is the QuickJS-WASM binding, which
+  runs the same single-file build on Node and in a browser, and
+  `VariablesPanel` renders what the realm holds and when each name was last
+  bound.
+- **Flows as the only capability primitive.** A cell is handed exactly one
+  authority, `ctx.call(flowName, input)`. `FlowBinding` pairs an ordinary flow
+  declaration with its handler and composes ordered sources into a catalog that
+  refuses two implementations under one name; `CellCalls` resolves each call
+  against the registry, refusing anything whose declaration moved since the
+  model was shown the catalog.
+- **Durable boundaries.** Every `ctx.call` is its own keyed, journaled,
+  permission-gated activity, and `EngineLike.record` is the same mechanism for
+  the controller's own nondeterministic reads: the workspace measurement, the
+  checkpoint mint, the frame outcome, and the turn-boundary steering drain.
+- **Bounded context.** `ContextWindow` assembles the immutable, zoned window;
+  `Compaction` selects and applies a deterministic summary; `Tokens` estimates
+  and combines the accounting; `Transcript` projects journal entries back into
+  model-facing state; `CallLedger` is the run's automatic ledger of settled
+  calls, rendered in every frame.
+- **Completion demands.** `NarrowedCheck`, `UnmovedTree`, `UnresolvedFailure`,
+  `Sufficiency`, `TruncatedOutput` and `VacuousVerification` are the controls
+  that answer "did this run actually do the work it says it did".
+  `VacuousVerification` ships unwired: `CellTurn` does not read it and no run is
+  told anything by it.
+- **The workerd seam.** `QuickJSSandbox.Variant` lets a host name the QuickJS
+  build instead of compiling one from bytes, which is what a runtime that
+  forbids `WebAssembly.compile` needs.
+- **Structured output.** `StructuredOutput` decodes an agent's final text into a
+  declared schema, spends a bounded correction budget, and reports a typed,
+  coded failure.
+
+### Changed
+
+- Every failure class a caller branches on is a closed union with a stable code:
+  `HarnessError.HarnessErrorCode`, `Cell.CallFailureCode`,
+  `Sandbox.SandboxErrorCode`, `Transcript.TranscriptErrorCode` and
+  `StructuredOutput.StructuredOutputFailureCode`.
+- A failed `ctx.call` **resolves** with `{ ok: false, error: { code, message, hint } }`
+  instead of throwing, so the recovery branch the model already wrote still
+  runs. `Cell.callFailureHint` names the one move that recovers each class.
+- Nothing a frame shows is cut silently. Every bound states what it dropped and
+  the id that brings it back, and every bound is measured in UTF-8 bytes.
+- `memoryBytes` is a **run** budget rather than a per-frame one, enforced by the
+  panel probe at each frame's close, because the realm outlives its frames.
+
+### Removed
+
+- The provider-tool-call loop and the modules that existed only to serve it:
+  `LegacyHarness`, `Harness`, `Turn`, `Tools`, `Assemble`, `AgentStep`,
+  `Elaborate`, `FlowTool` and `Visibility`. Foreign CLI adapters implement the
+  `Agent` service in `@smthrs/agent` instead of the neutral `Harness` contract
+  this package used to declare.
+- The filing authoring surface: `Cell.Mode`, `Cell.defaultMode`,
+  `Cell.transition`, `Cell.renderEntry`, `StateManifest`, `Sandbox.evaluate`,
+  `Sandbox.Evaluation`, `Sandbox.makeRestricted`, `Sandbox.layerRestricted`,
+  and `Steering.drainBoundary`. `Cell.Continue`'s `state`, `context`, `render`
+  and `recall`, and `Cell.Complete`/`Cell.Park`'s `state`, survive as
+  **decode-only** optional fields: nothing populates them and nothing reads
+  them, and they exist so journals written before the cell-first loop still
+  decode.
+- `HarnessErrorCode`'s thirteen unraised members, `invalid_step`,
+  `lazy_tool_prompt_metadata`, `elaboration_failed`, `unknown` and the nine
+  `adapter_*` codes. Nothing in this repository constructed them, and a code the
+  package cannot raise is a promise it cannot keep. An adapter error family
+  belongs beside the adapter in `@smthrs/agent`.
+
+## [0.1.0]
+
+### Added
+
+- Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @smthrs/harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://harness.smithers.sh
+
+An agent loop where the model writes JavaScript instead of calling tools. Each
+turn the model emits a **cell**: a small program that runs in a sandbox the run
+keeps open, and that reaches the outside world through exactly one function,
+`ctx.call(flowName, input)`.
+
+Scheduling, persistence, transport, and model execution stay behind explicit
+service ports, so this package holds no scheduler, no database, and no provider
+client.
+
+## Availability
+
+`@smthrs/harness` is not on npm at 1.0.0-rc.0. Its source lives in the
+[smithers repository](https://github.com/smithersai/smithers), and
+[Installation](https://harness.smithers.sh/installation/) covers how to depend
+on it from a checkout, the runtimes it supports, and the `effect` version it
+pins.
+
+## A working example
+
+This program opens a QuickJS realm, evaluates one cell that completes the run,
+and prints the outcome. It runs on Node with no other setup.
+
+```ts
+import * as Cell from "@smthrs/harness/Cell"
+import * as QuickJSSandbox from "@smthrs/harness/QuickJSSandbox"
+import * as Sandbox from "@smthrs/harness/Sandbox"
+import { Effect } from "effect"
+
+const call: Sandbox.Handler = () => Effect.succeed(new Cell.CallResult({ outcome: "success", value: null }))
+
+const program = Effect.gen(function*() {
+  const sandbox = yield* QuickJSSandbox.make
+  const realm = yield* sandbox.openRealm!({ flows: {} })
+  const frame = yield* realm.evaluate({
+    cell: Cell.source(`ctx.done("hello from the realm")`),
+    frame: 0,
+    call
+  })
+  return frame.outcome
+})
+
+const outcome = await Effect.runPromise(Effect.scoped(program))
+console.log(outcome)
+// { _tag: "settled", transition: { _tag: "complete", output: "hello from the realm" } }
+```
+
+## The cell loop
+
+The primary loop is cell-first. A frame is `model -> generated cell -> realm evaluation -> individually durable flow calls -> next transition`: the model emits fenced `cell` blocks of JavaScript, they run as one program in a realm that outlives the frame and whose only effectful primitive is `ctx.call`, and the cell states its intent by calling: `ctx.done(output)` completes, `ctx.park(reason, message)` waits, and a cell that calls neither continues. `Sandbox.replTransition` turns that call into the `continue` / `complete` / `park` transition the journal records; nothing is returned and nothing is filed, because the realm is the memory and what a cell prints is what the next model turn reads. `CellTurn` is that controller; it decides continuation from the transition and the run's budgets, never from provider tool calls.
+
+The production QuickJS binding never runs an unbounded cell. `Sandbox.defaultLimits` fills every ceiling a caller omits: 64 flow calls, 1,000 interpreter interrupt checks and a 30-second compute deadline per frame, a 900-second whole-evaluation backstop, a 120-second ceiling on any one flow call, and a 128 MiB memory budget. The memory budget is a **run** budget rather than a frame one, because the realm outlives its frames: `runtime.setMemoryLimit` does not count string data on the shipped build, so the panel probe weighs what the realm's own names hold and refuses a frame that opens over the ceiling before it runs. A caller may raise any individual ceiling explicitly; omitted ceilings retain their defaults, so a partial override cannot accidentally disable the others. `steps` and `timeMs` have typed floors (`Sandbox.minimumSteps`, `Sandbox.minimumTimeMs`), because a budget of zero interrupts the binding's own scaffolding rather than the cell.
+
+The controller also keeps the script itself, for the one host that needs it. A frame throws its cell away once the realm has evaluated it, so a model that wants to turn the script it just ran into a saved flow has nothing to read back. `CellHistory` is where the source goes: the controller appends each cell as it executes it, before evaluation, so a cell that raised is still part of what the run ran. The service is optional (a host that offers no way to save a flow binds nothing and the controller records nothing), and `@smthrs/agent/PromoteFlows` is what reads it.
+
+Every `ctx.call` inside a cell is its own keyed, journaled, permission-gated boundary at the tier the flow declares, so a cell is never one opaque activity. That is what makes a crash or a permission park mid-cell recoverable: the cell source re-executes from the top, boundaries that already settled replay their recorded values, and execution reaches the parked call deterministically.
+
+One case is bounded rather than free: a call the `callMs` ceiling interrupted settled nowhere, so a re-executed frame issues it to the host again and is then handed the recorded timeout. The cell's branch is stable either way; what the run pays for twice is the interrupted call. [Durability](https://harness.smithers.sh/reference/api/#durability) says why the call cannot move inside the record that would suppress it.
+
+## Flows are the only capability primitive
+
+A cell is handed exactly one authority: `ctx.call(flowName, input)`. There is no `ctx.fs`, no `ctx.shell`, no `ctx.mcp`, no `ctx.spawn` / `ctx.send` / `ctx.await`. Standard host capabilities, incoming MCP tools, and subagents are all _ordinary flow declarations plus a binding_, so a cell reaches every one of them with the same two lines and every one of them settles through the same durable `EngineLike.call` boundary with the same `CellCallStarted` / `CellCallSettled` trail.
+
+`FlowBinding` is that contract: `Binding` pairs a flow declaration with its handler, decoding cell input through the flow's input schema and validating the handler's output back into serializable JSON; `Source` produces bindings, possibly lazily; `Catalog` composes ordered sources and refuses two implementations under one name; and `FlowBinding.registry` discloses a catalog through an ordinary `Registry.Registry`, with file-discovered entries keeping precedence. A correctable failure (bad input, a flow that failed, unserializable output) becomes a `failure` `Cell.CallResult` the cell may catch; a permission requirement, an abort, or a suspension stays in the typed error channel where the cell can neither see nor swallow it.
+
+`@smthrs/agent/Agent` is the assembled production entry point that composes all of this over the durable engine.
+
+## Running an agent needs a configured judge
+
+The sixth brake on a completion asks Jev, TypeSafe's decision model, whether the claim the run wrote matches the evidence the run produced, through the `Evaluator` service of [`@smthrs/model`](https://model.smithers.sh). It never falls back. A completion nothing could judge fails the turn as `HarnessError` `completion_unjudged` carrying the reason, the way `read_only_cap` fails it, rather than standing unjudged: a brake that goes quiet when its model is down is a brake that is only there when it is not needed.
+
+It never goes quiet either. Every completion with a claim is read, `claimCap` (3) is the number of frames the run is given to prove one, and a claim with no bounce left fails the turn as `claim_unproven` carrying both probabilities. `claimCap: 0` is the one way out and it is the host's, taken at composition time the way zero disarms every other budget: nothing is read, nothing is journaled, nothing here can fail a run. No shipped host takes it; `smithers run` leaves the cap at 3. The cap used to end the brake instead of the run, so the second claim stood unread: on a real seat a run bounced once re-claimed the identical sentence and finished `stop` on it while the served repository's own test exited 1.
+
+`Evaluator.Evaluator` is required by `CellTurn.run` and `Agent.run`.
+`Evaluator.layerFromSeat(seat)` uses a seat the host already resolved, including
+Codex and Claude subscriptions. Native hosts use their existing subscription
+resolver with no gateway key. Missing seats, provider errors and malformed
+verdicts fail closed as `completion_unjudged`. The deterministic brakes run
+first; claims they reject never reach the judge.
+
+An offline host binds `Evaluator.layerScripted` deliberately, dispatches by question id, and computes answers from the evidence. Constant approval disarms the brake. One evaluator serves all the host's classifiers; see the [whole-host scripted judge](https://github.com/smithersai/smithers/blob/main/flows/test/fixtures/scripted-judge.ts). `Evaluator.layerUnavailable()` remains an outage fixture for classifier tests, not a host default.
+
+## Public API
+
+The root entry point exports one namespace per module; each is also importable from `@smthrs/harness/<Module>`. `QuickJSSandbox` is deliberately _not_ re-exported from the root: it carries an embedded WebAssembly build, so it is imported from its own subpath by hosts that want it.
+
+Every module and every export it publishes is listed in the
+[module and export inventory](https://harness.smithers.sh/reference/).
+
+`@smthrs/harness/QuickJSSandbox` exports `make` and `layer`: the QuickJS-WASM `Sandbox` binding, which runs the same single-file build on Node and in a browser and enforces the default ceilings above. It is also the one binding that offers `Sandbox.openRealm`, the persistent realm every run holds for its whole life ([Repl realm](https://harness.smithers.sh/concepts/#repl-realm)). It also exports `VariantService`, `Variant`, `layerVariantLive`, `layerVariant`, `makeWithVariant` and `layerWithVariant`, which are how a host names the build instead of taking the default; see below.
+
+`@smthrs/harness/package.json` is also exported. `internal/*` and nested `*/index` subpaths are not public.
+
+## Naming the QuickJS build
+
+`make` and `layer` compile the single-file build from bytes, which is what Node and a browser want. Some runtimes forbid that. Cloudflare's workerd runs no WebAssembly it did not compile itself: `WebAssembly.compile` over bytes fails at runtime, and the only module a worker can instantiate is one its toolchain bundled and handed over as an import.
+
+`QuickJSSandbox.Variant` is that seam. `layerVariantLive` provides the single-file default and `layerVariant(variant)` provides a build the host names; `layerWithVariant` and `makeWithVariant` are the sandbox over whichever one is in context. `@smthrs/agent/Agent` carries the same pair: `layerDefaults` is unchanged and `layerDefaultsWithVariant` takes the build from context.
+
+A worker names its build with the `.wasm` module its bundler compiled:
+
+```ts
+import wasmfile from "@jitl/quickjs-wasmfile-release-sync"
+import wasmModule from "@jitl/quickjs-wasmfile-release-sync/wasm"
+import * as QuickJSSandbox from "@smthrs/harness/QuickJSSandbox"
+import { Layer } from "effect"
+import { newVariant } from "quickjs-emscripten-core"
+
+const layer = QuickJSSandbox.layerWithVariant.pipe(
+  Layer.provide(QuickJSSandbox.layerVariant(newVariant(wasmfile, { wasmModule })))
+)
+```
+
+The full workerd setup, including the `wrangler` configuration a worker needs,
+is in [Run on Cloudflare workerd](https://harness.smithers.sh/guides/workerd/).
+
+## Documentation
+
+The published site is https://harness.smithers.sh.
+
+- [Quickstart](https://harness.smithers.sh/quickstart/): run two cells against
+  one realm and read the frames they produce.
+- [Concepts](https://harness.smithers.sh/concepts/): the cell loop, the
+  persistent realm, and durable flow calls as the only I/O.
+- [API reference](https://harness.smithers.sh/reference/api/): behavior and
+  signatures for every public export.
+- [Module and export inventory](https://harness.smithers.sh/reference/): every
+  module and its exports, one table per module.
+- [Troubleshooting](https://harness.smithers.sh/troubleshooting/): the failure
+  modes the package raises, and what to do about each.