@archmax-ai/harness 0.8.0 → 1.0.0

package/skills/archmax-harness/references/{hook-and-test-scripts.md → code-state-and-test-scripts.md}

@@ -1,28 +1,29 @@
-# Hook scripts & cases — full reference
+# Code-state scripts & cases — full reference
 
 The complete contract and worked examples for the two authored surfaces this
 reference covers:
 
-1. **Lifecycle hook scripts** (`workflows/<slug>/hooks/*.js` — beside the spec
-   that wires them, on the **authoring plane**) — deterministic `before`/`after`
-   gates, **hand-authored** `.js` files. `workflow.yaml` wires
-   `{ script: hooks/<name>.js }`: the path is **workflow-relative** and confined
-   to that workflow's `hooks/` directory, so it resolves to
-   `workflows/<slug>/hooks/<name>.js`. An absolute path, a `..` climb, or a path
-   outside `hooks/` is a load error and a `validate` error. They run in the
-   QuickJS sandbox: plain JavaScript with **top-level `await`**, no State APIs, no
-   filesystem beyond the `tools.*` bridge.
-
-   **A hook script is not a runtime script.** The runtime runs a hook; the agent
-   runs an `archmax_run` source. The two live in different places on purpose —
-   hooks in `workflows/<slug>/hooks/`, runtime scripts in
-   `skills/<capability>/scripts/` — and the classes cannot meet: the agent
+1. **Code-state scripts** (`workflows/<slug>/scripts/*.js` — beside the spec
+   that wires them, on the **authoring plane**) — the scripts a `type: code`
+   state runs, **hand-authored** `.js` files. `workflow.yaml` wires
+   `script: scripts/<name>.js` on the code state: the path is
+   **workflow-relative**, confined to that workflow's `scripts/` directory and
+   ends in `.js` or `.mjs`, so it resolves to `workflows/<slug>/scripts/<name>.js`.
+   An absolute path, a `..` segment, or a path outside `scripts/` is a load error
+   and a `validate` error. They run in the QuickJS sandbox: plain JavaScript with
+   **top-level `await`**, no Node APIs, no filesystem beyond the `tools.*` bridge.
+
+   **A code-state script is not an agent's script.** The runtime runs a code
+   state; the agent runs an `archmax_run` source. The two live in different places
+   on purpose — code-state scripts in `workflows/<slug>/scripts/`, runtime scripts
+   in `skills/<capability>/scripts/` — and the classes cannot meet: the agent
    cannot read `workflows/**` at all, and `archmax_run` is confined to skill
    bundles by a non-overridable kernel rule (`script.skill-only`). An agent that
-   could execute its own guard could probe it for a bypass, which is the whole
-   reason for the split. A hook's source also never reaches the model: not in a
-   prompt, not in an event, not in a session artifact — a veto reports its
-   verdict and reason, never its code.
+   could execute or read the check that judges its work could probe it for a
+   bypass, which is the whole reason for the split. A code-state script's source
+   never reaches the model: not in a prompt, not in an event, not in a session
+   artifact — the next state reads the reason the script passed to
+   `archmax_advance`, never its code.
 2. **Cases** (`workflows/<name>/tests/*.test.yaml`) — declarative
    YAML documents run by `archmax test` and interpreted **host-side**: no
    sandbox executes a case. Suite config is the `tests:` block in
@@ -32,23 +33,24 @@ Sandbox scripts are self-contained: the only permitted imports are **typed
 `@archmax-ai/harness/*` carriers** (stripped before evaluation — see
 [Typed imports](#typed-imports)); importing from any other specifier is an
 **error**. Each sandbox context gets its own globals — nothing leaks between
-them (`SANDBOX_CONTRACT.context` is `"lifecycle-hook"` for a hook, or `"ptc"`
-for the agent's own `archmax_eval`/`archmax_run` code, which gets **no** hook
-vocabulary at all; `SANDBOX_CONTRACT.version` is `2`).
+them (`SANDBOX_CONTRACT.context` is `"code"` for a code-state script, or `"ptc"`
+for the agent's own `archmax_eval`/`archmax_run` code, which gets **no**
+`defineCodeState`; `SANDBOX_CONTRACT.version` is `3`).
 
 ## Contents
 
 - [Typed imports](#typed-imports)
-- [Part 1 — Lifecycle hook scripts](#part-1--lifecycle-hook-scripts)
+- [Part 1 — Code-state scripts and agent scripts](#part-1--code-state-scripts-and-agent-scripts)
   - [Authoring model: hand-authored](#authoring-model-hand-authored)
-  - [The hook contract](#the-hook-contract)
+  - [The code-state script contract](#the-code-state-script-contract)
   - [Governance of `tools.*` calls](#governance-of-tools-calls)
   - [`archmax_run` scripts: the `args` contract](#archmax_run-scripts-the-args-contract)
   - [Scripts and sub-workflow fan-out](#scripts-and-sub-workflow-fan-out)
-  - [Worked example: a `before` gate](#worked-example-a-before-gate)
-  - [Worked example: an `after` policy check](#worked-example-an-after-policy-check)
-  - [When to use a grading rubric instead](#when-to-use-a-grading-rubric-instead)
-- [Part 2 — Cases (declarative YAML)](#part-2--cases-cases-declarative-yaml)
+  - [Worked example: a check in front of a state](#worked-example-a-check-in-front-of-a-state)
+  - [Worked example: a check behind a state](#worked-example-a-check-behind-a-state)
+  - [Worked example: approve, then end](#worked-example-approve-then-end)
+  - [When to use a grader state instead](#when-to-use-a-grader-state-instead)
+- [Part 2 — Cases (declarative YAML)](#part-2--cases-declarative-yaml)
   - [Layout and the prose rules](#layout-and-the-prose-rules)
   - [Suite config: the `tests:` block](#suite-config-the-tests-block)
   - [Top-level keys](#top-level-keys)
@@ -60,7 +62,7 @@ vocabulary at all; `SANDBOX_CONTRACT.version` is `2`).
   - [File fixtures: `from:` references](#file-fixtures-from-references)
   - [Settle the mocking depth before writing a case](#settle-the-mocking-depth-before-writing-a-case)
   - [Worked example: happy path + grade](#worked-example-happy-path--grade)
-  - [Worked example: veto, leak check, `noTraversal`](#worked-example-veto-leak-check-notraversal)
+  - [Worked example: declined at entry, leak check](#worked-example-declined-at-entry-leak-check)
   - [Worked example: mocking tool results](#worked-example-mocking-tool-results)
   - [Worked example: human-in-the-loop decisions (refine loop)](#worked-example-human-in-the-loop-decisions-refine-loop)
   - [Worked example: triggered start + fixture file](#worked-example-triggered-start--fixture-file)
@@ -70,182 +72,292 @@ vocabulary at all; `SANDBOX_CONTRACT.version` is `2`).
 
 ## Typed imports
 
-A hook script may open with a **typed import** — a type carrier that gives IDE
-completion for the hook input and the verdict helpers, and is **stripped before
-QuickJS evaluation** (the runtime implementation is an identity):
+A code-state script may open with a **typed import** — a type carrier that gives
+IDE completion for the state's input, and is **stripped before QuickJS
+evaluation** (the runtime implementation is an identity):
 
 ```js
-import { ok, veto, correct } from "@archmax-ai/harness/sandbox";
 /** … */
-export default async function hook({ state, variables, messages, tools }) {
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+export default defineCodeState(async ({ state, trigger, variables, tools }) => {
   /* ... */
-}
+});
 ```
 
-Importing from any **non-`@archmax-ai/harness/*`** specifier is an **error** — sandbox
-scripts are self-contained. **Bare-globals authoring** (no import) is equally
-valid: `ok`, `veto`, `correct` and `defineHook` are prelude globals.
+The same subpath types the input and the history (`CodeStateInput`,
+`CodeStateArgs`, `CodeStateFn`, `SandboxTools`, `SessionHistory`,
+`HistoryMessage`, `TrailStep`). Importing from any
+**non-`@archmax-ai/harness/*`** specifier is an **error** — sandbox scripts are
+self-contained. **Bare-globals authoring** (no import) is equally valid:
+`defineCodeState` is a prelude global, and a plain
+`export default async function ({ tools }) { … }` registers the same way.
 
 ---
 
-## Part 1 — Lifecycle hook scripts
+## Part 1 — Code-state scripts and agent scripts
 
 ### Authoring model: hand-authored
 
-A script hook references an **ordinary hand-authored** `.js` file. You DESIGN
-AND WRITE the script directly — there is no generation step. `workflow.yaml`
-only wires the hook, one or a list run in order (the first veto stops the list):
+A code state references an **ordinary hand-authored** `.js` file. You DESIGN AND
+WRITE the script directly — there is no generation step. `workflow.yaml` only
+wires it: the state's type, its script, and its transitions, which are where the
+script may send the session:
 
 ```yaml
 states:
-  identify-case:
+  screen-request:
+    type: code
+    script: scripts/screen-request.js
     triggers:
       manual:
-    before:
-      - script: hooks/check-requester.js
-      - script: hooks/check-tenancy.js
+    skills:
+      allow: [order-data]        # the script reads the order records: granted here
+    on_error: escalation         # where a failure of the script routes
+    transitions:
+      - to: identify-case
+        description: The requester is known and asks only about their own company's orders.
+      - to: decline
+        description: The request names no known requester, or reaches for another company's orders.
 ```
 
-A hook script **MUST** open with a leading JSDoc block — a title line, a blank
-line, and a description of what the check does _and how_: the inputs it reads,
-the sequence of checks, and the condition producing **each** verdict. It is the
-only human-facing contract the file has (admin UIs display it instead of the
-code), and it is what a reviewer refines when the gate is wrong. No
-`@specification` tag, no `// archmax:generated` marker, no generation semantics.
-See [SKILL.md → Code files are description-first](../SKILL.md#code-files-are-description-first).
-
-The `specification` sidecar in `workflow.yaml` is **not a recognized key**:
-`{ script: x.js, specification: … }` is a malformed two-key hook and a
-validation **error**.
-
-- `archmax validate` reports a hook-script problem only when the script **file
-  is missing** or it has a **foreign (non-`@archmax-ai/harness/*`) import**. It does
-  **not** check the JSDoc block on any script — the header is an authoring
-  standard you uphold yourself. (Cases are YAML; there `archmax validate`
-  **errors** on a missing `description` instead.)
-- The runtime never generates scripts: a missing script file at run time
-  errors and vetoes (fail-closed).
-
-### The hook contract
-
-A hook is a **default-export function**. The runtime calls it with **one
-object** and reads its **return value** as the verdict:
+`script` is **required** on a code state and **refused** on every other type
+(both load errors). A code state makes no model call, so `instructions`, `model`,
+`budget`, `evidence` and `approvers` on one are `validate` errors: say what the
+script does in its JSDoc block, and in the state's `summary`.
+
+A code-state script **MUST** open with a leading JSDoc block — a title line, a
+blank line, and a description of what the script does _and how_: the inputs it
+reads, the sequence of checks, and **where it sends the session in each case**
+(each `archmax_advance` target and why, each `archmax_raise` code). It is the only
+human-facing contract the file has (admin UIs display it instead of the code), and
+it is what a reviewer refines when the check is wrong. No `@specification` tag, no
+`// archmax:generated` marker, no generation semantics. See
+[SKILL.md → Workspace layout](../SKILL.md#workspace-layout-complete--nothing-else-exists).
+
+- `archmax validate` reports a code-state script problem when the script **file
+  is missing** from `scripts/` or it has a **foreign (non-`@archmax-ai/harness/*`)
+  import**. It does **not** check the JSDoc block on any script — the header is
+  an authoring standard you uphold yourself. (Cases are YAML; there
+  `archmax validate` **errors** on a missing `description` instead.)
+- The runtime never generates scripts: a missing script file at run time fails
+  the state (fail-closed), routed through its `on_error`.
+
+### The code-state script contract
+
+When the session's position reaches a code state — the agent's `archmax_advance`
+into it, another automated state's advance, a human decision, an `on_error`
+route, a turn that opens there, an `archmax_reset` back to it — the runtime runs
+its script **in place of the next model call**. The agent's model is not called
+while the session stands in a code state, so a chain of code states makes no
+model call at all. The script's **default export** is called with **one object**,
+and the script **moves the session itself**:
 
 ```js
 /**
- * Requester gate — reject a run whose requester is not a known customer.
+ * Requester screen — reject a request whose requester is not a known customer.
  *
- * Reads the first user message from `messages`, extracts the first email
- * address in it, loads skills/order-data/assets/orders.json through the tool
- * bridge, and looks the address up against every order's `email`.
+ * Reads the first user message from the session's history, extracts the first
+ * email address in it, loads skills/order-data/assets/orders.json (this state
+ * enables `order-data`), and looks the address up against every order's `email`.
  *
- * Vetoes when the request carries no email address, and when the address
- * matches no order — each with a reason naming what was missing. Otherwise ok.
+ * Advances to decline when the request carries no email address, and when the
+ * address matches no order — each with a reason naming what was missing — and
+ * otherwise to identify-case.
  */
-export default async function hook({ state, phase, trigger, variables, messages, tools }) {
-  const orders = JSON.parse(await tools.readFile({ file_path: "skills/order-data/assets/orders.json" }));
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+export default defineCodeState(async ({ tools }) => {
+  const { messages } = JSON.parse(await tools.archmax_get_history());
+  const orders = JSON.parse(await tools.read_file({ file_path: "skills/order-data/assets/orders.json" }));
   const request = messages.find((m) => m.role === "user")?.text ?? "";
   const email = request.match(/[\w.+-]+@[\w.-]+/)?.[0];
-  if (!email) return veto("No email address found in your request.");
-  if (!orders.some((o) => o.email === email)) return veto(`"${email}" is not in the order database.`);
+  if (!email) return tools.archmax_advance({ to: "decline", reason: "No email address found in the request." });
+  if (!orders.some((o) => o.email === email)) {
+    return tools.archmax_advance({ to: "decline", reason: `"${email}" is not in the order database.` });
+  }
   console.log(`Allowed: ${email}`);
-  return ok();
-}
+  await tools.archmax_advance({ to: "identify-case", reason: `${email} is a known requester.` });
+});
 ```
 
-**The input** (`HookInput` in `@archmax-ai/harness/sandbox`; the same fields minus
-`tools` are also the global `args`):
+**The input** (`CodeStateInput` in `@archmax-ai/harness/sandbox`; the same fields
+minus `tools` are also the global `args`):
 
 | Field | Meaning |
 | --- | --- |
-| `state`, `phase` | The state whose hook is running; `"before"` or `"after"`. |
-| `trigger` | The trigger **id string** the run started from. It carries no payload — the run's input is in `variables`. |
-| `variables` | The run's variables as a plain `name → value` map, including the built-in `trigger`. Structured values are present whole (`variables.order.items[0].sku`). **Read-only**: assigning changes nothing, and the variable tools are absent from `tools.*` — a hook that could write variables would be editing the governance inputs of the state it judges. |
-| `messages` | The recent transcript (last 24 messages), newest last, as `{ role, text, toolCalls? }`. `role` is `user`, `assistant`, `tool` (with `tool: <name>`), `system`, or **`runtime`** — a note the runtime wrote (an arrival, a decision, an error route, a completion check; `note` names the kind). A hook that reacts to narration matches `role === "runtime"`, never a `[bracket]` prefix in a user message. |
-| `from`, `to`, `reason` | Present on `after` hooks: the transition the agent is attempting (`reason` is the agent's `archmax_advance` reason). |
-| `tools` | The privileged tool-call bridge (async), camelCased: `await tools.readFile({ file_path: "skills/order-data/assets/orders.json" })` → file text, or the binary notice for a binary file (see below). See [Governance](#governance-of-tools-calls). |
+| `state` | The code state's own slug. |
+| `trigger?` | The id **string** of the trigger the turn carries. It carries no payload — the session's input is in `variables`. |
+| `variables` | The session's variables as a plain `name → value` map, including the built-in `trigger`. Structured values are present whole (`variables.order.items[0].sku`). **Read-only**: assigning changes nothing. Write with `tools.archmax_set_variables`, which holds locks, `title` and typed returns exactly as the agent's call does. |
+| `tools` | **Exactly this state's tool surface** (async): its grants (the workflow-wide grant included), the host's essential tools, and its controls. A tool answers to its own name (`tools.read_file`, `tools["archmax_workflow_enrich-order"]`) and to its camelCased key (`tools.readFile`); `Object.keys(tools)` lists the camelCased keys. A call with no argument passes `{}` (`tools.archmax_get_history()`, `tools.ls()`). **A name outside the surface is `undefined`.** See [Governance](#governance-of-tools-calls). |
+
+**The session's history** is not part of the input: the script reads it the way
+a grader does, with `archmax_get_history` (`SessionHistory`):
+
+```js
+const { messages, trail } = JSON.parse(await tools.archmax_get_history());
+```
+
+It is the session as it stood when the state was entered, built from the
+checkpointed session (never a summarized request), whole and oldest first,
+across every turn:
+
+| Field | Meaning |
+| --- | --- |
+| `messages` | The transcript as `{ role, text, toolCalls?, tool?, id?, note? }`. `role` is `user`, `assistant`, `tool`, `system`, or **`runtime`** — a note the runtime wrote (an arrival, a decision, an error route, an automated state's move; `note` names the kind). An `assistant` entry lists the calls it made in `toolCalls`, as `{ id?, name, args }`; the `tool` entry answering one carries the tool's name in `tool`, the call's `id`, and the **result in `text`**, as the tool returned it (`JSON.parse` it when the tool returns JSON; a failed or refused call's `text` is the error). A script that reacts to narration matches `role === "runtime"`, never a `[bracket]` prefix in a user message. Not windowed: the sandbox's `maxResultChars` and `memoryLimitBytes` bound it. |
+| `trail` | The trail as `{ to, kind, reason?, workflow?, status?, ts }`. `kind` is `trigger`, `agent`, `human`, `grader`, `code`, `sub-workflow`, `reset` or `on_error`. Count earlier rounds here: `trail.filter((s) => s.kind === "code" && s.to === "refund-request").length`. |
+
+Only what the transcript holds is there: a call a script made through `tools.*`
+(an agent's `archmax_run`, or a code state's own) is not, and neither is a
+grader's.
+
+**What a code state checks.** The conversation is the model's memory, not
+evidence: a code state checks the session's records — `variables`, files, and
+the tool results the history carries as the tools returned them. Check a result
+itself, never a copy the model wrote into a variable, a file or its reply, and
+never call a tool again just to see its result (for a host whose tools reach an
+external system, that is a second action). To read a result, find the call in an
+`assistant` entry's `toolCalls`, then the `tool` entry with the same `id`:
+
+```js
+/**
+ * Status check — the recorded status must be the one get_order returned.
+ *
+ * Finds the last get_order call in the session's history and the tool message
+ * answering it, and reads scratchpad/status.json ({ status }), which the agent
+ * wrote. Advances to notify-customer when the recorded status is the returned
+ * one; otherwise back to look-up-order, with the status to record, or with a
+ * request to look the order up when no get_order call has a readable result.
+ */
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+export default defineCodeState(async ({ tools }) => {
+  const { messages } = JSON.parse(await tools.archmax_get_history());
+  const call = messages.flatMap((m) => m.toolCalls ?? []).findLast((c) => c.name === "get_order");
+  const answer = call && messages.find((m) => m.role === "tool" && m.id === call.id);
+  let order;
+  try {
+    order = JSON.parse(answer.text);
+  } catch {
+    return tools.archmax_advance({ to: "look-up-order", reason: "Look the order up with get_order first." });
+  }
+  const recorded = JSON.parse(await tools.read_file({ file_path: "scratchpad/status.json" }));
+  if (recorded.status !== order.status) {
+    return tools.archmax_advance({
+      to: "look-up-order",
+      reason: `Order ${call.args.id} is ${order.status}: record that status exactly.`,
+    });
+  }
+  await tools.archmax_advance({ to: "notify-customer", reason: `The recorded status ${order.status} is get_order's.` });
+});
+```
+
+The history spans every turn and every entry into a state, so where only the
+latest round counts, take the last match, as above. What a later state or turn
+needs from the conversation (the person's words, a decision) is still best
+stored in a variable or a file by the state that has it, so no check has to
+search the transcript for it.
+
+**The controls** on `tools`:
+
+| Control | Effect |
+| --- | --- |
+| `archmax_advance({ to, reason, evidence? })` | Records the move along one of the state's transitions. Checked **at the call**: an undeclared `to` or an unmet `requires` rejects naming the valid targets or the missing variable, and the script may catch it and decide otherwise. `evidence` is accepted only into a human state. The `reason` is what the next state reads. Absent in a terminal state. |
+| `archmax_raise({ code, reason })` | Records the end of the session as **failed**, with the code and reason as its outcome's `exit`. |
+| `archmax_get_variables({ name?, path? })` / `archmax_set_variables({ variables, lock? })` | Read and write the session's variables, as the agent's calls do. A write is visible to the script's later calls, so a script can set what `requires` asks for and then advance. |
+| `archmax_get_history()` | Resolves to the session's history as JSON text, `{ messages, trail }` (above). |
+
+These are a grader's controls too: both automated types get the same set. There
+is no `archmax_wait` and no `archmax_reset`: a code state cannot park, since a
+script frame is not durable. To hand work to a person, advance into a human state.
 
-**The verdict** — the three helpers are globals:
+**How the run settles** — exactly one outcome:
 
-| Return | Effect |
+| The run… | Outcome |
 | --- | --- |
-| `ok()` (or nothing) | Proceed. |
-| `veto(reason)` | Block. `before`: entry to the state (for a start state, the whole run). `after`: the `archmax_advance` transition, or the completion of a terminal state. The reason is shown to the agent — make it precise and actionable. |
-| `correct(reason)` | **`after` hooks only**: the agent gets another attempt with the reason as correction, bounded by the hook-level `max_iterations` sidecar (`after: { script: hooks/review.js, max_iterations: 2 }`; default 0 — a `correct` with no budget is a hard veto). The budget is counted per hook, so a passing sibling hook does not reset it, and a `correct` refused on a spent budget consumes nothing. A `before` `correct` is treated as a veto and is a validation error. |
-| `false` | A veto (`"precondition not met"`) — the shorthand for `return isAuthorized(x)`. |
-| any other object | A **veto**, with the object's keys named in the reason. A hook's return value *is* its verdict, so a misspelled `verdict` or a shape like `{ ok: false, reason }` is a verdict got wrong; reading it as `ok` would silently permit what the hook meant to block. |
-| `true`, a number, a string | Proceed — a non-object says nothing about the verdict, including a bare body's incidental completion value. |
-
-A hook that **throws** — or whose file is missing — **vetoes** with the error
-as the reason (fail-closed). Parse JSON defensively (`try`/`catch`) and turn
-malformed inputs into a `veto` with a good message instead of letting them
-throw; conversely, if a failure should *not* block, catch it and return `ok()`.
-
-Other globals: `console.log(...)` (captured into the trail; shown in verbose
-runs), and `defineHook(fn)`, an alias
-for `export default fn`. A file with **no default export** is evaluated as a
-plain script and its **completion value** is the verdict, so a short gate can be
-`orders.length ? ok() : veto("no orders")` on its last line.
-
-`${{…}}` does not apply inside a hook: the runtime substitutes references in the
-arguments the *model* writes. A hook already has the values in `variables` and
-composes strings in JavaScript, so `${{…}}` text in a hook's `tools.*` call is
+| called `archmax_advance` and finished cleanly | **advanced**: the session moves. The trail records `{ to, kind: "code", reason }`, and a runtime note carries the reason to the next state: `[code] '<state>' moved the run to '<to>': <reason>. You are now in '<to>'.` Into a human state the session parks after the one reply-only handoff message. Into another automated state, that state runs next, still with no model call. |
+| called `archmax_raise` | **raised**: the session ends `failed` — no `on_error`, no `returns` check, nothing further runs in the turn. |
+| finished without either, in a **terminal** state | **completed**: the session completes, held to the trigger's `returns`. |
+| threw, timed out, could not be read, imported a foreign module, or — in a **non-terminal** state — finished without either call | **failed**: routed through the state's `on_error`, else the session ends rejected. Finishing undecided fails with `code state '<slug>' finished without calling archmax_advance or archmax_raise`. |
+
+Three rules hold the outcomes apart:
+
+- **The return value is not read.** Returning `false`, a string or an object does
+  nothing; there is no verdict to return. Only the controls decide.
+- **One decision per run.** The first accepted `archmax_advance` or `archmax_raise`
+  is the state's decision, and every later one is refused (it rejects).
+- **The decision takes effect when the script finishes.** A script that advances
+  and then throws **fails**, and the session does not move. A raise wins over a
+  later error.
+
+So parse defensively where malformed input should *send the work back*, and let a
+genuine infrastructure failure (an unreadable database) throw, so the state fails
+closed through its `on_error`.
+
+Other globals: `console.log(...)` (each line a `code-output` event, which the CLI's
+state flow prints under the state), and `defineCodeState(fn)`, an alias for
+`export default fn`. A file with **no default export** is evaluated as a plain
+script: it reads the input from the global `args` and calls the global `tools`.
+**Each run starts clean**: a fresh REPL every time the state is entered, shared
+with neither the agent's `archmax_eval` nor another code state. The script is one
+evaluation, so `settings.timeoutMs` (default 15000), `memoryLimitBytes`,
+`maxPtcCalls` and `maxResultChars` bound it whole, and a cancelled turn stops it at
+once.
+
+`${{…}}` does not apply inside a script: the runtime substitutes references in the
+arguments a *model* writes. A script already has the values in `variables` and
+composes strings in JavaScript, so `${{…}}` text in a script's `tools.*` call is
 ordinary data.
 
 ### Governance of `tools.*` calls
 
 Every `tools.*` call is checked by the decision kernel at the moment it runs —
 the same kernel, with the same rules, that governs a tool call the model makes
-directly. What differs is only _whose authority_ the script runs on:
-
-| Script kind                                     | The state's own governance (`tools.allow`, `tools.forbid`, `skills.*`, `mounts.*`) | Safety rules, workflow-wide `forbid_always`, the workflow's mount grants, consumer rules |
-| ----------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
-| Lifecycle hook (`before:`/`after:`)             | **Not applied** — a gate must read evidence the state never grants, and a state's denial does not reach it either | Applied |
-| `archmax_run` script (the model chose to run it) | **Applied** — it runs on the model's authority                          | Applied |
-
-A hook runs on **runtime authority**: outside the active state's tool surface in
-*both* directions. So a hook may
-`await tools.readFile({ file_path: "skills/order-data/assets/orders.json" })`
-even in a state whose `allow` list never mentions `read_file`, one that enables
-no skill at all, and one whose `tools.forbid` names the very tool it calls — while
-the workflow's `tools.forbid_always`, `skills.forbid_always` and
-`mounts.forbid_always` bind it like anything else, and no script of either kind
-may write into the read-only authored zone.
-
-Mounts are held to the **workflow's** grants, taken across every state. A hook
-reads a governed mount that `mounts.allow_always` or any state's `mounts.allow`
-names, even in a state that enables none, and writes one only where a grant of
-the workflow asks `access: read_write`. A governed mount no grant of the workflow
-names is refused (`mount.not-allowed`). That includes a mount in the table only
-because a child workflow grants it. So grant a mount the hook needs:
+directly. There is no runtime authority for scripts: **both kinds are governed
+against the state they run in.**
+
+| Script kind | Governed against | Must be granted there |
+| --- | --- | --- |
+| Code-state script (`type: code`) | its own code state: `tools.allow`/`forbid`, `skills.*`, `mounts.*`, plus `allow_always`, `forbid_always`, safety rules, consumer rules | every tool, skill and governed mount it uses |
+| `archmax_run` / `archmax_eval` script (the model chose to run it) | the agent's active state, exactly as the model's own calls | every tool it calls |
+
+So a code state that reads `skills/order-data/assets/orders.json` enables
+`order-data` in its own `skills.allow`, and one that calls a host tool names it in
+its own `tools.allow`. A tool another state grants is `undefined` on its `tools`;
+a bare `forbid` entry removes a tool from it, and a guarded one (`{ tool:
+write_file, paths: [...] }`) refuses the matching calls. A grant on a code state
+naming `write_todos`, `archmax_eval`, `archmax_run`, `archmax_wait` or
+`archmax_reset` is a `validate` error: no automated state is offered them, and
+the same tools in the workflow's `allow_always` are left out of its surface.
+
+Mounts work the same way: a governed mount is reachable from a code state only
+when `mounts.allow_always` or that state's own `mounts.allow` grants it, and
+writable only where the grant asks `access: read_write`:
 
 ```js
-// workflow.yaml: states.review.mounts.allow: [contracts]
-// A before hook on any state of this workflow may then read it:
-const policy = await tools.readFile({ file_path: "contracts/policy.md" });
+// workflow.yaml: states.check-contract.mounts.allow: [contracts]
+const policy = await tools.read_file({ file_path: "contracts/policy.md" });
 ```
 
 Neither kind may **read** the authoring plane at all. A `tools.*` call naming
-`workflows/**` is blocked (`zone.governance-plane`) with a
-diagnostic naming the prefix — a hook cannot read its own spec, a sibling's, or
-the criteria of the rubric declared in it. There is no `task()` in any sandbox
-context: a script that wants a model verdict gets a `rubric` hook declared beside
-it
-instead.
-
-A refused call **throws** inside the script, carrying the governance reason.
+`workflows/**` is blocked (`zone.governance-plane`) with a diagnostic naming the
+prefix — a script cannot read its own spec, a sibling's, or a grader's
+criteria. There is no `task()` in any sandbox context and no `tools.task`: work
+that needs a model's judgment is a grader state on the graph.
+
+A refused call **rejects** inside the script, carrying the governance reason.
 The underlying tool never runs whether or not you catch it:
 
 ```js
 try {
-  await tools.writeFile({ file_path: "scratchpad/report.md", content: body });
+  await tools.write_file({ file_path: "scratchpad/report.md", content: body });
 } catch (err) {
   console.log(`could not write the report: ${err.message}`);
 }
 ```
 
 A **binary file** is not a refusal and does not throw: reads are text only, so
-`tools.readFile` on an image, audio, video, PDF or PowerPoint file, or on any
+`tools.read_file` on an image, audio, video, PDF or PowerPoint file, or on any
 file whose content holds a NUL byte (an archive, an Office document), resolves to
 the notice `Error: '<path>' is a binary file (<type>, <size>) and was not read;
 read_file returns text files only.` instead of content — an image too, even when
@@ -256,28 +368,27 @@ an `Error: …` string the same way. A script that parses what it read checks
 first:
 
 ```js
-const text = await tools.readFile({ file_path: "scratchpad/upload.json" });
+const text = await tools.read_file({ file_path: "scratchpad/upload.json" });
 const upload = text.startsWith("Error:") ? null : JSON.parse(text);
 ```
 
 To **duplicate, move or delete** a file — a template, an image, a `.docx` —
-call `tools.copyFile({ source, destination, overwrite? })`,
-`tools.moveFile({ source, destination, overwrite? })` or
-`tools.removeFile({ file_path })` instead of reading and writing it back. The
-bytes move, binary files included, with no `readFile` line limit, and each
+call `tools.copy_file({ source, destination, overwrite? })`,
+`tools.move_file({ source, destination, overwrite? })` or
+`tools.remove_file({ file_path })` instead of reading and writing it back. The
+bytes move, binary files included, with no `read_file` line limit, and each
 call resolves to one line (`Copied '<source>' to '<destination>' (<size>).`,
 `Moved …`, `Removed '<path>'.`). They are governed by their declared paths like
 any other call, so a governance refusal (a destination in a read-only mount, a
-disabled skill's file) throws. A failure the operation itself meets (a missing
+disabled skill's file) rejects. A failure the operation itself meets (a missing
 source, a directory, an existing destination without `overwrite: true`)
 resolves to an `Error: …` string instead.
 
-**Authoring rule for `archmax_run` scripts:** if sandboxed code calls `tools.X`,
-the state's `allow` list must cover `tool: X` (with any argument constraints the
-script's call satisfies), or the call is blocked. Grant it per state with
-`tools.allow`, or workflow-wide with `tools.allow_always`; a default tool such as
-`read_file` is covered wherever the workflow-wide grant includes it. Lifecycle
-hooks need no such grant.
+**Authoring rule for every script:** if sandboxed code calls `tools.X`, the state
+it runs in must cover `tool: X` (with any argument constraints the call
+satisfies), or `tools.X` is `undefined` (or the call rejects). Grant it per state
+with `tools.allow`, or workflow-wide with `tools.allow_always`; a default tool such
+as `read_file` is covered wherever the workflow-wide grant includes it.
 
 ### `archmax_run` scripts: the `args` contract
 
@@ -288,9 +399,9 @@ store. It reads its input from the global **`args`**:
 
 - **the arguments the model passed** to `archmax_run` (`args.<name>`), plus
 - **`args.variables`** — the session's variables as a flat `name → value` map,
-  the same map a hook gets. The runtime supplies it on every call, so a script
-  reads the run's input (a seeded list, a delivered payload) without the model
-  having to retype it.
+  the same map a code state gets. The runtime supplies it on every call, so a
+  script reads the run's input (a seeded list, a delivered payload) without the
+  model having to retype it.
 
 ```js
 /** One sub-run per requested order. */
@@ -299,16 +410,18 @@ const orders = args.variables?.orders_to_enrich ?? [];
 
 `args.variables` is a read-only snapshot; a script that must persist a result
 returns it and the state's `requires:` makes the model record it with
-`archmax_set_variables`. There is **no `task()`** in an `archmax_run` script or in
-`archmax_eval`. The model has no `task` tool at all: it is disclosed in no state
-and grantable by nothing, because a rubric grades the agent rather than serving it.
+`archmax_set_variables`. An agent's script reaches **no control tool** — not
+`archmax_advance`, not the variable tools — and there is **no `task()`** in an
+`archmax_run` script or in `archmax_eval`. The model has no `task` tool at all: it
+is disclosed in no state and grantable by nothing, because judging work is a
+grader state and delegating it is a sub-workflow.
 
 ### Scripts and sub-workflow fan-out
 
 A script **is** the deterministic way to drive a fan-out. Delegation tools are on the `tools.*`
-surface — a delegation does work and returns a value, unlike the control tools a script may never
-call — so a script decides how many sub-runs to start, with what inputs, and what to do with each
-answer:
+surface — a delegation does work and returns a value, unlike the control tools an agent's script
+may never call — so a script decides how many sub-runs to start, with what inputs, and what to do
+with each answer:
 
 ```js
 /** One sub-run per delayed order, all in flight at once. */
@@ -328,59 +441,68 @@ enriched;
 `Promise.all` genuinely parallelizes: the bridge starts each host call detached and returns its
 promise handle immediately. The runtime still bounds how many sub-runs are in flight
 (the dispatcher's `maxConcurrent`), queueing the rest. The list never enters the model's
-context.
+context. A code state may drive the same fan-out when its own state grants the delegation tool,
+and then record the results itself with `tools.archmax_set_variables` before it advances.
 
 Two limits still hold, both inherited rather than special to delegation. A script may only call a
 delegation tool its **calling state** allows — the same kernel verdict an agent's call gets. And a
 script's delegation **cannot park**: a QuickJS frame is not durable, so a child that reaches a human
 state fails that call closed with `parked`.
 
-Scripts still may not call `archmax_advance` (moving the state machine is the model's governed
-decision) or `archmax_set_variables`. Concurrent calls succeed or fail **independently**, so a script
-can act on what worked — `Promise.allSettled` is the honest shape when partial success is
-meaningful. Each sub-run is its own session with its own `scratchpad/`, so concurrent sub-runs
+An agent's script still may not call `archmax_advance` (moving the state machine is the model's
+governed decision) or `archmax_set_variables`. Concurrent calls succeed or fail **independently**,
+so a script can act on what worked — `Promise.allSettled` is the honest shape when partial success
+is meaningful. Each sub-run is its own session with its own `scratchpad/`, so concurrent sub-runs
 never collide on a path; a `file` return comes back as a copy under a name no other file holds.
 
 A script lives as long as its turn. When the host cancels the turn, a call still in flight fails
 with `Tool '<name>' failed: the turn was aborted`, and every call the script makes after that is
 refused the same way before it reaches the tool. A retry in a `catch` therefore dispatches nothing
-more, so there is no need to tell a cancel apart from an ordinary failure. Hook scripts stop the
-same way.
+more, so there is no need to tell a cancel apart from an ordinary failure. Code-state scripts stop
+the same way.
 
-### Worked example: a `before` gate
+### Worked example: a check in front of a state
 
-The tenancy half of the bundled example's entry gate
-(`workflows/order-lookup/hooks/check-tenancy.js`), the second hook in
-`identify-case`'s `before` list — so a missing or unknown email has already been
-vetoed by `check-requester.js` before this runs:
+To screen every request before any model call, make the trigger's entry state a
+code state that advances to where the work starts, or to a state that declines it.
+The bundled example's `screen-request` (`workflows/order-lookup/scripts/screen-request.js`)
+merges a requester check and a tenancy check — wired as in
+[Authoring model](#authoring-model-hand-authored), with `decline` a terminal agent
+state that tells the person why:
 
 ```js
 /**
- * Tenancy gate — a requester may only reach their own company's orders.
+ * Request screen — the requester must be known, and may only reach their own
+ * company's orders.
  *
  * Binds the requester's email (the first one in the first user message) to the
  * customers whose orders carry it in skills/order-data/assets/orders.json, then
  * checks the request two ways: it names another customer, or it references an
  * order id (`ORD-…`) owned by another customer. Matching is case-insensitive.
  *
- * Vetoes with the customers or order ids the requester reached for when either
- * check finds one; otherwise ok. If the order database cannot be read, vetoes
- * too (fail-closed).
+ * Advances to decline — with the reason the decline state tells the person — when
+ * there is no email, the email is unknown, or either tenancy check finds a
+ * foreign customer; otherwise to identify-case. An order database that cannot
+ * be read throws: the state fails closed through its on_error.
  */
-export default async function hook({ messages, tools }) {
-  let orders;
-  try {
-    orders = JSON.parse(await tools.readFile({ file_path: "skills/order-data/assets/orders.json" }));
-    if (!Array.isArray(orders)) throw new Error("not an array");
-  } catch {
-    return veto("Could not load skills/order-data/assets/orders.json - unable to check tenancy.");
-  }
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+export default defineCodeState(async ({ tools }) => {
+  const { messages } = JSON.parse(await tools.archmax_get_history());
+  const orders = JSON.parse(await tools.read_file({ file_path: "skills/order-data/assets/orders.json" }));
+  if (!Array.isArray(orders)) throw new Error("skills/order-data/assets/orders.json is not a list of orders");
 
   const request = messages.find((m) => m.role === "user")?.text ?? "";
   const email = (request.match(/[\w.+-]+@[\w.-]+\.\w{2,}/)?.[0] ?? "").toLowerCase();
+  if (!email) {
+    return tools.archmax_advance({ to: "decline", reason: "Include your email address so we can look up your account." });
+  }
   const own = new Set(
     orders.filter((o) => String(o.email).toLowerCase() === email).map((o) => String(o.customer)),
   );
+  if (own.size === 0) {
+    return tools.archmax_advance({ to: "decline", reason: `"${email}" is not in the order database.` });
+  }
 
   const lower = request.toLowerCase();
   const foreignByName = [...new Set(orders.map((o) => String(o.customer)))].filter(
@@ -392,35 +514,64 @@ export default async function hook({ messages, tools }) {
     .map((o) => String(o.id));
 
   if (foreignByName.length > 0 || foreignById.length > 0) {
-    const detail = (foreignByName.length > 0 ? foreignByName : foreignById).join(", ");
-    return veto(
-      `The email address "${email}" is not authorized to access orders for ${detail}. You may only view orders for your own account.`,
-    );
+    return tools.archmax_advance({
+      to: "decline",
+      reason: `"${email}" may only view orders for its own account. Do not name the other customer's orders.`,
+    });
   }
-  return ok();
-}
+  await tools.archmax_advance({ to: "identify-case", reason: `${email} is authorized for ${[...own].join(", ")}.` });
+});
 ```
 
-The pattern to internalize: **one `return veto(reason)` per veto condition,
-each with a human-readable reason that names the fix**; `console.log` for
-anything worth seeing in a verbose run; `return ok()` at the end.
+The pattern to internalize: **one `archmax_advance` per outcome, each with a
+`reason` the next state can act on** (the `decline` agent reads it from the `[code]`
+note and tells the person); `console.log` for anything worth seeing in a verbose
+run; a `throw` for what should fail the state rather than route it. To end the
+session as a failure instead, with no reply at all, call
+`tools.archmax_raise({ code: "unknown-requester", reason })`.
 
-### Worked example: an `after` policy check
+### Worked example: a check behind a state
 
-An `after` hook re-derives policy deterministically so the agent can never
-record a decision the policy forbids. Wiring (on `refund-request` in the
-bundled example's `workflow.yaml`):
+To check the agent's work before the session moves on, route the agent's
+transition into a code state, and give that state an edge onward and an edge
+**back**. The bundled example's `check-refund` sits between `refund-request` (the
+agent records a decision) and `refund-review` (a person reviews it), so a decision
+the policy forbids never reaches the reviewer:
 
 ```yaml
-after:
-  script: hooks/check-refund.js
+states:
+  refund-request:
+    instructions: >-
+      … Record the decision in scratchpad/refund.json, tell the customer, and in
+      that same message archmax_advance to check-refund. If the check sends the
+      case back, its note names the fix: correct the file and advance again.
+    skills:
+      allow: [order-data, refund-policy]
+    transitions:
+      - to: check-refund
+        description: The refund decision has been recorded and explained to the customer.
+  check-refund:
+    type: code
+    script: scripts/check-refund.js
+    skills:
+      allow: [order-data]
+    on_error: escalation
+    transitions:
+      - to: refund-review
+        description: The recorded decision matches the refund policy.
+      - to: refund-request
+        description: The recorded decision contradicts the policy; send it back with the fix.
+      - to: escalation
+        description: The decision still fails the check after two corrections.
 ```
 
-The check (`workflows/order-lookup/hooks/check-refund.js`):
+The check (`workflows/order-lookup/scripts/check-refund.js`), which counts its own
+earlier send-backs on the trail and escalates on the third:
 
 ```js
 /**
- * Refund policy gate — the agent may not record a refund the policy forbids.
+ * Refund policy check — the agent may not hand a refund the policy forbids to
+ * the reviewer.
  *
  * Re-derives the refund decision from the order database instead of trusting
  * the one the agent wrote. Reads the recorded ticket from scratchpad/refund.json
@@ -430,78 +581,183 @@ The check (`workflows/order-lookup/hooks/check-refund.js`):
  * Policy: a refund is "approved" only when the order exists with status
  * delivered or delayed; an unknown order and any other status must be "denied".
  *
- * Vetoes, each with a reason that names the fix, when: the ticket file is
- * missing or not valid JSON; `decision` is not exactly "approved" or "denied";
- * the order database cannot be read; or the recorded decision contradicts the
- * derived one. Otherwise ok.
+ * Advances to refund-review when the recorded decision matches. Otherwise sends
+ * the session back to refund-request with a reason naming the fix — the ticket
+ * missing or unparseable, `decision` not "approved"/"denied", or the decision
+ * contradicting the policy — and, once it has sent it back twice (counted on
+ * the trail), advances to escalation instead. An unreadable order database
+ * throws: the state fails through its on_error.
  */
-export default async function hook({ tools }) {
+import { defineCodeState } from "@archmax-ai/harness/sandbox";
+
+const MAX_SEND_BACKS = 2;
+
+export default defineCodeState(async ({ tools }) => {
+  const { trail } = JSON.parse(await tools.archmax_get_history());
+  const sentBack = trail.filter((s) => s.kind === "code" && s.to === "refund-request").length;
+  const sendBack = (reason) =>
+    sentBack >= MAX_SEND_BACKS
+      ? tools.archmax_advance({ to: "escalation", reason: `Still failing after ${sentBack} corrections: ${reason}` })
+      : tools.archmax_advance({ to: "refund-request", reason });
+
   let refund;
   try {
-    refund = JSON.parse(await tools.readFile({ file_path: "scratchpad/refund.json" }));
+    refund = JSON.parse(await tools.read_file({ file_path: "scratchpad/refund.json" }));
   } catch (e) {
-    return veto(
-      `scratchpad/refund.json could not be read or parsed (${e.message}) - write it as a JSON object with "orderId" and "decision" before leaving this state`,
-    );
+    return sendBack(`scratchpad/refund.json could not be read or parsed (${e.message}) - write it as a JSON object with "orderId" and "decision", then advance again`);
   }
-
   const decision = refund?.decision;
   if (decision !== "approved" && decision !== "denied") {
-    return veto(`scratchpad/refund.json "decision" must be exactly "approved" or "denied"; got ${JSON.stringify(decision)}`);
-  }
-
-  let orders;
-  try {
-    orders = JSON.parse(await tools.readFile({ file_path: "skills/order-data/assets/orders.json" }));
-  } catch {
-    return veto("skills/order-data/assets/orders.json could not be read - the order database must be accessible to validate the refund decision");
+    return sendBack(`scratchpad/refund.json "decision" must be exactly "approved" or "denied"; got ${JSON.stringify(decision)}`);
   }
 
+  const orders = JSON.parse(await tools.read_file({ file_path: "skills/order-data/assets/orders.json" }));
   const wanted = typeof refund.orderId === "string" ? refund.orderId.trim().toLowerCase() : "";
   const order = orders.find((o) => typeof o?.id === "string" && o.id.toLowerCase() === wanted);
   const derived = order && ["delivered", "delayed"].includes(order.status) ? "approved" : "denied";
   console.log(`Refund policy check - derived "${derived}", recorded "${decision}"`);
 
-  if (decision === derived) return ok();
-  const why = !order
-    ? "it does not exist in the order database"
-    : derived === "approved"
-      ? `its status is "${order.status}"`
-      : `its status "${order.status}" is not delivered or delayed`;
-  return veto(
-    `Policy requires "${derived}" for order ${JSON.stringify(refund.orderId)} because ${why}, but the recorded decision is "${decision}" - update scratchpad/refund.json to decision: "${derived}"`,
+  if (decision === derived) {
+    return tools.archmax_advance({ to: "refund-review", reason: `"${decision}" for ${refund.orderId} matches the refund policy.` });
+  }
+  const why = !order ? "it does not exist in the order database" : `its status is "${order.status}"`;
+  return sendBack(
+    `Policy requires "${derived}" for order ${JSON.stringify(refund.orderId)} because ${why}, but the recorded decision is "${decision}" - update scratchpad/refund.json to decision: "${derived}", correct what you told the customer, and advance again`,
   );
+});
+```
+
+Note how the send-back reasons carry the _fix_: the agent reads the reason as a
+`[code]` note, rewrites `scratchpad/refund.json`, and advances again. There is no
+retry budget to declare: the script counts the rounds itself, from the history's
+`trail`, and decides when to give up.
+
+### Worked example: approve, then end
+
+A check that approves into a terminal **agent** state costs one more model call:
+that state's agent has to finish the turn. Approve into a **terminal code state**
+instead. Its script runs and the session completes, with no further model call.
+Say the enrichment path's grader approves into `enrichments-approved`, and the
+trigger declares `returns: [delayed_order_ids]`:
+
+```yaml
+  enrichments-approved:
+    type: code
+    script: scripts/enrichments-approved.js     # no transitions: terminal
+```
+
+```js
+/**
+ * Approved-enrichments record — the end of the enrichment path.
+ *
+ * Reads the `enrichments` the grader approved and sets the trigger's declared
+ * return `delayed_order_ids` from them, so a caller has the result without
+ * walking the list, then returns: the session completes.
+ */
+export default async function ({ variables, tools }) {
+  const delayed = variables.enrichments.filter((e) => e.delayed).map((e) => e.order_id);
+  await tools.archmax_set_variables({ variables: { delayed_order_ids: delayed } });
 }
 ```
 
-Note how the veto reasons carry the _fix_: the agent reads the reason,
-rewrites `scratchpad/refund.json`, and retries the transition.
+A terminal code state's completion is held to the trigger's `returns` like any
+completion: set a declared return with `tools.archmax_set_variables` before the
+script returns.
 
-### When to use a grading rubric instead
+### When to use a grader state instead
 
-Use a `script:` hook when the check is **deterministic** — derivable from
+Use a **code state** when the check is **deterministic** — derivable from
 workspace data with plain code (policy tables, schema checks, cross-file
-consistency). Use a `rubric:` hook when the check requires **judgment**
-(is the reply complete? is the tone right?):
+consistency). Use a **grader state** when the check requires **judgment** (is the
+report complete? is the summary faithful?). A grader is an isolated subagent the
+runtime runs on entry: its system prompt is a compiled-in preamble followed by the
+state's `instructions` (its criteria), it reads the session with
+`archmax_get_history` (the whole transcript, tool results included, and the
+trail) and the work with its own state's tools, and it decides with
+`archmax_advance` along one of its transitions, or ends the session with
+`archmax_raise`. The bundled example's enrichment path:
 
 ```yaml
 states:
-  orders-question:
-    after:
-      - rubric:
-          max_iterations: 2     # `correct` verdicts allowed before a hard veto
-          instructions: |-
-            You review the agent's final reply about the user's orders...
-            Return { "verdict": "ok" | "correct" | "veto", "reason": "..." }.
+  enrich-order:
+    instructions: >-
+      Run skills/order-enrichment/scripts/enrich-orders.js with archmax_run …
+      Record that list as the `enrichments` variable with archmax_set_variables,
+      then advance to review-enrichment, which checks it. If the review sends it
+      back, fix what its note names and advance again.
+    requires: [enrichments]
+    transitions:
+      - to: review-enrichment
+        description: Every order has been enriched and `enrichments` is recorded.
+  review-enrichment:
+    type: grader
+    budget: { maxTurns: 8 }          # the grader's own model calls
+    on_error: escalation             # a grader that fails or finishes undecided routes here
+    skills:
+      allow: []                      # read_file, from the workflow-wide grant, reads the returned files
+    instructions: |-
+      You check the enrichments recorded for this run before they are reported.
+
+      1. Read `orders_to_enrich` and `enrichments` with `archmax_get_variables`.
+      2. The enrichments are correct when `enrichments` holds exactly one entry
+         per requested `order_id` — none missing, none extra — and each entry
+         has an `enrichment_file` and a boolean `delayed`.
+      3. Read each `enrichment_file` with `read_file`: its `delayed` must match
+         the entry's.
+
+      - Correct: advance to `enrichment-reported`.
+      - Wrong: advance back to `enrich-order`, naming exactly what is missing or
+        does not match.
+      - Before sending it back, call `archmax_get_history` and count the steps
+        in `trail` with `kind: "grader"` and `to: "enrich-order"`: if there are
+        already two, raise `enrichment-incorrect` instead.
+    transitions:
+      - to: enrichment-reported      # a terminal agent state that summarizes the enrichments
+        description: Every requested order has exactly one enrichment, and each matches its file.
+      - to: enrich-order
+        description: >-
+          The enrichments are incomplete or do not match their files: send them
+          back, naming exactly what to fix.
 ```
 
-A rubric may return `correct` — the agent gets another attempt with the
-grader's reason as correction, budgeted by its own `max_iterations`. Script hooks
-get the exact same flow when they return `correct(reason)` under a
-`max_iterations` sidecar. A rubric whose response cannot be parsed
-into a verdict **fails closed** (veto with a snippet of the raw output). A rubric
-receives a compact JSON payload (`userRequest`, `history`, `state`, `phase`) —
-its `instructions` are written against that, not against a hook's `messages`.
+What to know:
+
+- A grader state **must** declare non-empty `instructions` and at least one
+  transition (`validate` errors): a grader with nowhere to send the session could
+  only approve by saying nothing, which would fail open. `evidence`, `approvers`
+  and `budget.maxParks` are errors on it. Every edge **into** a grader carries a
+  `description`: its instructions are criteria the work it judges is never shown,
+  so an undescribed edge into one is a load error.
+- `archmax_get_history` returns `{ messages, trail }` — the same history a code
+  state reads: the whole transcript, a `tool` entry carrying its result in `text`,
+  and every trail step. Not windowed: a grader judges the whole session, so its
+  criteria say which part counts ("the files `enrichments` names", "the last
+  assistant message with text"). Check a claim against the tool result or
+  the file itself, never against the agent's retelling of it.
+- There is **no iteration budget**. A grader that should give up after N rounds
+  says so in its `instructions` and counts the rounds from the history's trail
+  (each earlier send-back is `{ kind: "grader", to: "<graded state>" }`), as
+  above. The turn's recursion limit is the only backstop.
+- The grader is offered exactly its state's surface — its grants (never
+  `write_todos`, `archmax_eval`, `archmax_run`, `archmax_wait` or `archmax_reset`,
+  even when `allow_always` lists them) and the controls a code state gets:
+  `archmax_advance`, `archmax_raise`, the variable tools and `archmax_get_history`
+  — governed against the grader state. Its messages never enter the session's
+  transcript and its tokens never stream; the session reads its decision as a
+  `[grader]` note and a `kind: grader` trail step.
+- A grader that answers in text without deciding **fails closed** (`grader state
+  '<slug>' finished without calling archmax_advance or archmax_raise`), routed
+  through `on_error`. `budget.maxTurns` / `timeoutMs` bound its own model calls.
+- `model` on a grader state names the id it runs on, resolved through the
+  assembly's `modelFactory` under the **`grader`** role.
+- The checked state's `instructions` tell the agent that advancing into the
+  grader is what hands the work in, and to fix the work when a note sends it back
+  — never to argue with the note.
+- **Put a grader where the agent hands work on, not on a live answer.** A turn's
+  `reply` is every assistant text of the turn, in order, so a draft the grader
+  sends back has still reached the person. Check work that waits for nobody — a
+  report, a record, a decision a person reviews next — and let a live answer end
+  where it is given.
 
 ---
 
@@ -521,7 +777,7 @@ workflows/<name>/tests/
   `archmax test` filter argument matches that path as a substring.
 - **Cases are data, not code.** The host parses, validates, and interprets
   them directly — no QuickJS sandbox is created for a case. The sandbox still
-  runs lifecycle hooks and `archmax_run` *inside the driven agent*, unchanged.
+  runs code-state scripts and `archmax_run` *inside the driven agent*, unchanged.
 - **A case reads like a script.** `steps` is one flat sequential list where
   actions (`send`, `decide`) and assertions are peers; each assertion
   evaluates against the view of the nearest action above it.
@@ -556,7 +812,7 @@ workflows/<name>/tests/
     (`>-`) and a literal (`|`) block of the same prose score alike.
   - Work title-first: write `title` and `description` before the steps, and
     never leave them contradicting each other. This replaces the JSDoc-header
-    rule that applied to JS test files; JSDoc headers now apply to hook
+    rule that applied to JS test files; JSDoc headers now apply to code-state
     scripts and `archmax_run` sources only.
 
 Run with `archmax test <workflow> [filter]`. A minimal case:
@@ -585,8 +841,8 @@ tests:
     120000 # per-case WALL-CLOCK budget (default 120000) —
     # deliberately named differently from settings.timeoutMs,
     # the per-script sandbox budget
-  judge: {} # grader settings ({} = env-configured default model;
-    # or { model, modelOptions })
+  judge: {} # the model that scores `grade:` ({} = env-configured
+    # default model; or { model, modelOptions }) — not a grader state
 ```
 
 There is no `reporters` option. A
@@ -607,7 +863,8 @@ Unknown keys are validation **errors**. All keys except `title` and
 | `variables`   | `{ <name>: <value> }`                          | Session variables seeded for every driven turn, supplied as the runtime's `variables` and therefore **locked**. Values may be structured. This is where a case puts the run's input — a trigger carries none. Recover the real payload from a previous run's `artifacts/variables.json` rather than inventing one: see [Recovering a case's inputs from previous runs](#recovering-a-cases-inputs-from-previous-runs). |
 | `trigger`     | `{ id }`                                       | The trigger every driven turn of the case runs under. Carries **only an id**; `args` is rejected with a pointer to `variables:`. Validated against the workflow machine before any step — an unknown id fails the case (even with no steps), listing the workflow's declared triggers. Omitted ⇒ the manual trigger. See [Start conditions](#start-conditions-trigger-variables-and-workspace).                                              |
 | `workspace`   | `{ <path>: <content> }`                        | Files seeded into the case's run workspace **before any step**. Strings are written verbatim; non-string YAML values are JSON-serialized; a single-key `{ from: <tests/-relative path> }` mapping copies a file byte-for-byte. Only agent-visible run-zone paths are seedable (root-level files like `trigger.json`, or `scratchpad/…`); authored (`skills/…`), runtime-internal, and escaping paths are rejected before anything is written. |
-| `mocks`       | `[{ tool, whenInput?, result }]`               | Declarative tool mocks: when the driven agent calls `tool` with input partially matching `whenInput`, return `result` instead of executing. Intercepts **agent-initiated and PTC** (script `tools.*`) calls alike. See [the mocking section](#settle-the-mocking-depth-before-writing-a-case).                                        |
+| `mocks`       | `[{ tool, whenInput?, result }]`               | Declarative tool mocks: when `tool` is called with input partially matching `whenInput`, return `result` instead of executing. Intercepts **agent-initiated** calls and every programmatic call alike — an agent's script's `tools.*`, a code state's `tools.*`, a grader's calls. A control tool (`archmax_advance`, `archmax_raise`, the variable tools) is never mocked. See [the mocking section](#settle-the-mocking-depth-before-writing-a-case).                                        |
+| `clock`       | `"2026-03-20"` / `"…T14:30:00Z"` | The date and time every model call of the case states as "now": an ISO 8601 date (midnight UTC) or a date-time with `Z` or an offset; a zoneless or impossible value is a schema error. Carried on every action, a handoff and a child session included, and outranks the host's `clock` option. See [Start conditions](#start-conditions-trigger-variables-and-workspace). |
 | `steps`       | flat list of step entries      | The case script: actions and assertions as peers (below).                                                                                                                                                                                                                                                                                                          |
 
 There is **no multi-session surface** in test spec version 1 — no `sessions:`,
@@ -661,20 +918,20 @@ failure in one of them **halts the case** — see
 
 | Assertion                                | Meaning                                                                                                                                                                                                                                                                                                                      |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `succeeded: true`                        | **Structural.** The run finished: not failed **and not parked**, and the agent did not end it with `archmax_raise` (a raise fails here, naming its code).                                                                                                                                                                                     |
+| `succeeded: true`                        | **Structural.** Reads the action's outcome: passes when it is `completed` — not parked, not raised with `archmax_raise`, not failed, not rejected. A tool call that failed or was blocked along the way, and that the turn recovered from, does not fail it. A miss says why: the raised code and reason, `the session is parked`, or `the turn did not complete`. |
 | `parked: true`                           | **Structural.** The run is parked at a human state awaiting a decision.                                                                                                                                                                                                                                                                        |
 | `raised: true` / `raised: <code>` / `raised: { code?, reason? }` | **Structural.** The agent ended the turn with `archmax_raise({ code, reason })`. A string pins the code exactly; the mapping pins the code and matches the reason — exactly, or as a regex when written `"/pattern/flags"`. A miss names the code that was raised, or says the run did not raise.                                  |
 | `variables: { expect, path?, locked? }`  | Every named variable is set to the expected value — deep equality, so a structured expectation compares by value. `path` addresses into a value per name (`items.-1.sku` is the last element); `locked` asserts the lock state. |
-| `reachedState: <slug>`                   | **Structural.** A **committed** (non-trigger) audit-trail step entered the state — agent `archmax_advance`, human decision, `archmax_reset`, or `on_error` route. The trigger-arrival step never counts (it is recorded before the entry state's `before` gate runs, so a vetoed-entry run never "reaches" its start state).                        |
-| `reply: { includes?, excludes? }`        | `includes`: substrings or `/pattern/flags` regex strings that must **all** match; `excludes`: none may match (leak checks — a refusal that quotes the data it refuses still leaks it). Each accepts a **single token or a list** (`includes: "ORD-1003"` works). Matched against the turn's **whole assistant transcript**, not just the final message (a parked run often closes with a short "moving on" message while the substantive answer came earlier). |
+| `reachedState: <slug>`                   | **Structural.** A **committed** (non-trigger) audit-trail step entered the state — the agent's `archmax_advance`, a grader's or a code state's advance, a human decision, `archmax_reset`, an `on_error` route. The trigger-arrival step never counts, so a session reaches its start state only by moving into it (a session whose entry code state raised never "reaches" it).                        |
+| `reply: { includes?, excludes? }`        | `includes`: substrings or `/pattern/flags` regex strings that must **all** match; `excludes`: none may match (leak checks — a refusal that quotes the data it refuses still leaks it). Each accepts a **single token or a list** (`includes: "ORD-1003"` works). Matched against **every assistant message of the session so far** (earlier turns included), not just the final message (a parked run often closes with a short "moving on" message while the substantive answer came earlier). |
 | `calledTool: { name, input? }`           | The turn recorded a call to tool `name`; `input` is a **partial** match — mappings match on the declared keys (nested mappings partially), arrays by deep equality, and `/pattern/flags` string values match as **regexes** (recommended for file paths, so the model's exact spelling doesn't matter).                        |
 | `notCalledTool: { name, input? }`        | No matching call occurred.                                                                                                                                                                                                                                                                                                    |
 | `blockedTool: { name, input? }`          | A matching call was made **and refused by governance** — the assertion for testing a guard. Distinct from `notCalledTool` (nothing was tried, which proves nothing about the guard) and from a tool that ran and errored (only a policy rejection counts). Use it to test a state's `tools.allow` narrowing or its `skills.allow` set. |
-| `usedNoTools: true`                      | The turn used no tools at all.                                                                                                                                                                                                                                                                                                |
-| `trail: { to?, kind?, reason?, count }`  | **Structural.** The number of audit-trail steps matching **all** given fields equals `count` (declare at least one of `to`/`kind`/`reason`). `kind`: `trigger` \| `agent` \| `human` \| `on_error` \| `branch` \| `join`. The trail accumulates across turns — each turn starts with a `trigger` step.                                        |
-| `noTraversal: true`                      | **Structural.** The trail holds nothing but trigger arrivals — a veto at entry committed no transitions.                                                                                                                                                                                                                                      |
+| `usedNoTools: true`                      | The turn's agent used no tools at all. An automated state's calls are not in the transcript, so they never count.                                                                                                                                                                                                                                                                                                |
+| `trail: { to?, kind?, reason?, count }`  | **Structural.** The number of audit-trail steps matching **all** given fields equals `count` (declare at least one of `to`/`kind`/`reason`). `kind`: `trigger` \| `agent` \| `human` \| `grader` \| `code` \| `sub-workflow` \| `reset` \| `on_error` — a grader's or code state's move is `grader`/`code`, with the `reason` it passed to `archmax_advance`. `count: 0` asserts a state was never entered. The trail accumulates across turns — each turn starts with a `trigger` step.                                        |
+| `noTraversal: true`                      | **Structural.** The trail holds nothing but trigger arrivals — nothing moved the session (an entry code state that raised, an agent that answered from its start state). A grader's or code state's move is a traversal.                                                                                                                                                                                                                                      |
 | `triggerArrival: <trigger-id>`           | **Structural.** Some trail step has `kind: trigger` and that trigger id as its reason — the run really started from the declared trigger.                                                                                                                                                                                                     |
-| `grade: { closedQA, atLeast }`           | LLM-grade the turn's **run evidence** against the `closedQA` criterion — its final reply *plus* a bounded chronological record of the assistant messages and tool calls behind it (each call with input, output, and status; mocked calls appear like real ones). The two are weighed differently: a criterion about what the user was **told** is met only by the reply, one about what the agent **did** may be met by the record — so `closedQA: looked the order up before answering` is a legitimate criterion, not only phrasing checks. **`atLeast` decides the outcome** — score ≥ `atLeast` passes, below it **fails the case**; the judge model's own opinion never overrides your declared bar, so the record can't disagree with the verdict. The judge is instructed to keep its reason to 1–3 sentences, so it fits on the verdict line. Requires `tests.judge` in `workflow.yaml`.                                            |
+| `grade: { closedQA, atLeast }`           | LLM-grade the turn's **run evidence** against the `closedQA` criterion — what the action's turn said (every text of that turn, empty when it said nothing) *plus* a bounded chronological record of the session's assistant messages and tool calls so far (each call with input, output, and status; mocked calls appear like real ones). The two are weighed differently: a criterion about what the user was **told** is met only by the reply, one about what the agent **did** may be met by the record — so `closedQA: looked the order up before answering` is a legitimate criterion, not only phrasing checks. **`atLeast` decides the outcome** — score ≥ `atLeast` passes, below it **fails the case**; the judge model's own opinion never overrides your declared bar, so the record can't disagree with the verdict. The judge is instructed to keep its reason to 1–3 sentences, so it fits on the verdict line. Requires `tests.judge` in `workflow.yaml`.                                            |
 
 **Regex form**: a string shaped `/pattern/flags` is compiled as a regular
 expression; anything else matches as a plain substring (in `reply` tokens) or
@@ -684,7 +941,30 @@ validation errors**, never silently matched as literals. Quote them in YAML —
 
 **There is no generic predicate.** No `satisfies`, no inline JS — that is the
 point of the format. Bespoke logic belongs in a vitest unit test against the
-engine or in a lifecycle hook.
+engine or in a code state on the graph.
+
+**An automated state is asserted by what it committed.** A code state's or a
+grader's own tool calls are not in the transcript, so `calledTool`,
+`notCalledTool`, `blockedTool` and `usedNoTools` see only the agent's, and a
+grader's words are never part of `reply`. Assert its move and reason with
+`reachedState` / `trail: { kind: code | grader, to, reason?, count }`, its raise
+with `raised`, what it set with `variables`, and its dispatches with
+`ranWorkflow`:
+
+```yaml
+steps:
+  - send: "Hi, I'm support@acmecorp.com. Which orders are delayed?"
+  - trail: { kind: code, to: identify-case, count: 1 }   # the entry screen passed it
+```
+
+```yaml
+trigger: { id: enrichment_requested }                    # the enrichment path
+variables: { orders_to_enrich: [{ order_id: "ORD-1002" }, { order_id: "ORD-1003" }] }
+steps:
+  - send: "Enrich the requested orders."
+  - trail: { kind: grader, to: enrichment-reported, count: 1 }   # the grader approved the enrichments
+  - trail: { kind: grader, to: enrich-order, count: 0 }          # without a send-back
+```
 
 ### Structural assertions halt the case
 
@@ -762,8 +1042,8 @@ steps:
   runtime's `variables` and therefore **locked**, values structured or
   scalar. A seed here is indistinguishable from a production host seed to
   everything downstream: a `${{…}}` reference in a `tools.allow` glob resolves
-  from it, a state's `requires:` gate is satisfied by it, a lifecycle hook reads
-  it in `variables`, and `archmax_set_variables` refuses to rewrite it.
+  from it, a state's `requires:` gate is satisfied by it, a code state's script
+  reads it in `variables`, and `archmax_set_variables` refuses to rewrite it.
   **Recover the real payload rather than inventing one** — see
   [Recovering a case's inputs from previous runs](#recovering-a-cases-inputs-from-previous-runs).
 - **`workspace`** — input files seeded before any step. Keys are run-zone
@@ -783,6 +1063,15 @@ Two operational notes:
   _earlier_ run whose declaration was since removed can linger. The default
   (per-run unique sessions) starts clean.
 
+**Pin the date** with a case-level `clock:` whenever a fixture or a prompt
+carries a date (an order placed on `2026-03-15`, "refundable for 30 days"):
+without it the model reads the real "now" and the verdict drifts with the
+calendar. Pin on a ten-minute mark (the line is rounded down to ten minutes,
+UTC only). Only the prompt is pinned — code-state scripts, the sandbox's `Date`, a
+park's `resumeAt` and every recorded timestamp stay real, so a script that needs
+the case's "today" reads it from a seeded variable, and a wait resumed in the
+case is resumed with `deliver`, not by its `until`.
+
 ### Recovering a case's inputs from previous runs
 
 A trigger carries only an id, so everything a firing passes arrives as
@@ -863,8 +1152,8 @@ actually calls and propose a split:
   inventory, today's date-dependent data). A test that is not safe to re-run is
   not a test.
 - **Leave real by default** reads against fixtures committed to the workspace,
-  the workflow's own scripts and hooks, and run-zone file writes — mocking those
-  would test the mock instead of the workflow.
+  the workflow's own scripts and code states, and run-zone file writes — mocking
+  those would test the mock instead of the workflow.
 - **Ask** about reads against a live system: cheap and stable enough to keep
   real, or slow, rate-limited, or credential-bound enough to mock?
 
@@ -874,9 +1163,10 @@ while a reader checking the case against the workflow needs to know what was
 deliberately left real, which is exactly the kind of rationale the comment
 exists for.
 
-Mocks are the top-level `mocks:` list; they intercept **agent-initiated and
-PTC** (script `tools.*`) calls with the same partial-input matching as
-`calledTool`. Interception is guaranteed under `archmax test`. A host running
+Mocks are the top-level `mocks:` list; they intercept **agent-initiated** calls
+and every programmatic call — an agent's script, a code state's script, a
+grader — with the same partial-input matching as `calledTool`. So a mock of a
+file an entry code state reads changes what that state decides too. Interception is guaranteed under `archmax test`. A host running
 the same cases through `runTests` with its own `createTarget` must wire
 `createToolMockMiddleware()` into that agent — a case that declares `mocks:`
 against a target that cannot intercept them is refused with an error **before
@@ -892,9 +1182,8 @@ workflow-governed target. See
 # (threshold 0.7) checks the order is attributed to the requester's company.
 title: Delayed orders answered for a known requester
 description: >-
-  One turn from support@acmecorp.com (present in skills/order-data/assets/orders.json): the run
-  succeeds, the trail committed the route into orders-question, and the reply
-  names the one delayed order, ORD-1003.
+  A known requester's question routes into orders-question, and the reply names
+  the one delayed order, ORD-1003.
 steps:
   - send: "Hi, I'm support@acmecorp.com. Which orders are delayed for Acme?"
   - succeeded: true
@@ -908,27 +1197,33 @@ steps:
       atLeast: 0.7
 ```
 
-### Worked example: veto, leak check, `noTraversal`
+### Worked example: declined at entry, leak check
 
-A `before` veto leaves the audit trail holding nothing but the trigger
-arrival — `noTraversal` asserts exactly that, and `reply.excludes` catches a
-refusal that quotes the data it refuses to share:
+An entry code state that declines a request commits a `code` step into the
+declining state and none into the state the work starts in — `reachedState`
+and a `count: 0` trail pin exactly that — and `reply.excludes` catches a
+refusal that quotes the data it refuses to share. (Had the screen ended the
+session with `tools.archmax_raise` instead, `raised: <code>` and
+`noTraversal: true` would pin it.)
 
 ```yaml
-# The `excludes` tokens matter as much as the refusal itself: a refusal that
-# quotes the order ids it declines to share still leaks them. The judge
-# (threshold 0.7) covers the same ground in prose.
-title: Cross-tenant order access is vetoed
+# The `trail` count pins the decline to *entry*: identify-case was never
+# entered, so no route was taken. The `excludes` tokens matter as much as the
+# refusal itself: a refusal that quotes the order ids it declines to share
+# still leaks them. The judge (threshold 0.7) covers the same ground in prose.
+title: Cross-tenant order access is declined
 description: >-
-  A known requester asking for Globex's delayed orders is declined as
-  unauthorized, nothing beyond the trigger arrival reaches the trail, and no
-  Globex order id appears in the reply.
+  A known requester asking for Globex's delayed orders is declined at entry,
+  identify-case is never entered, and no Globex order id appears in the reply.
 steps:
   - send: "Hi, this is support@acmecorp.com. Show me Globex's delayed orders."
+  - succeeded: true
+  - reachedState: decline
+  - trail: { kind: code, to: decline, count: 1 }
+  - trail: { to: identify-case, count: 0 }
   - reply:
-      includes: "/not authorized|only .* your own|rejected/i"
+      includes: "/not authorized|only .* your own|declined/i"
       excludes: ["ORD-2001", "ORD-2002"]
-  - noTraversal: true
   - grade:
       closedQA: >-
         declines the request because the requester is not authorized to view
@@ -940,20 +1235,28 @@ steps:
 ### Worked example: mocking tool results
 
 ```yaml
-# Only read_file against skills/order-data/assets/orders.json is mocked; everything else — the
-# hooks, the agent's own writes — stays real. Asserting the lookup *and* the
-# empty answer catches both a skipped lookup and an invented order.
-title: Empty order database reports no matches
+# Only read_file against skills/order-data/assets/orders.json is mocked; the
+# agent's own writes stay real. The report_requested trigger enters
+# report-requested directly, so no code state reads the records first — a mock
+# answers a code state's calls too, and an empty database would make the entry
+# screen decline the requester. Asserting the lookup *and* the empty answer
+# catches both a skipped lookup and an invented order.
+title: Empty order database reports no delayed orders
 description: >-
-  With skills/order-data/assets/orders.json mocked empty, a delayed-orders question from a known
-  requester still consults the database, and the reply reports no matching
-  orders.
+  With skills/order-data/assets/orders.json mocked empty, a requested report
+  still consults the database, and the reply reports no delayed orders.
+trigger:
+  id: report_requested
+variables:
+  company: "Acme Corp"
+workspace:
+  trigger.json: { company: "Acme Corp" }
 mocks:
   - tool: read_file
     whenInput: { file_path: skills/order-data/assets/orders.json }
     result: "[]"
 steps:
-  - send: "Hi, I'm support@acmecorp.com. Which of my orders are delayed?"
+  - send: "A delayed-orders report was requested."
   - calledTool:
       name: read_file
       input:
@@ -1044,8 +1347,8 @@ seeded byte-for-byte before any step:
 title: Delayed-orders report compiled from a trigger
 description: >-
   The report_requested trigger starts the run: the agent reads the seeded
-  trigger.json payload, writes scratchpad/report.json, and the reply names Acme's
-  one delayed order, ORD-1003.
+  trigger.json, writes scratchpad/report.json, and the reply names Acme's one
+  delayed order, ORD-1003.
 trigger:
   id: report_requested
 variables:
@@ -1065,7 +1368,7 @@ steps:
   - calledTool:
       name: write_file
       input:
-        file_path: "/output\\/report\\.json/"
+        file_path: "/scratchpad\\/report\\.json/"
   - reply:
       includes: ["ORD-1003", "Acme"]
 ```
@@ -1092,7 +1395,7 @@ skipped silently. The mapping:
 | `t.auditTrail()` + `filter(...).length === n`                 | `- trail: { to?, kind?, reason?, count }`; "nothing but the trigger arrival" ⇒ `- noTraversal: true`; trigger-arrival reason ⇒ `- triggerArrival: <id>` |
 | `t.judge.autoevals.closedQA(c).atLeast(n)`                    | `- grade: { closedQA: c, atLeast: n }` step entry                                                                        |
 | `t.skip(reason)`                                              | `skip: <reason>`                                                                                                         |
-| bespoke predicates                                            | **No YAML equivalent — deliberate.** Move bespoke logic into a vitest unit test against the engine, or a lifecycle hook (`veto(reason)`). |
+| bespoke predicates                                            | **No YAML equivalent — deliberate.** Move bespoke logic into a vitest unit test against the engine, or a code state that checks it on the graph. |
 | `import { defineEval } from "@archmax-ai/harness/testing"`             | Nothing — the subpath is removed; YAML imports nothing                                                                   |
 
 Removed package exports: `createDriveTool`, `DriveRequest`, `DriveSession`,
@@ -1101,8 +1404,9 @@ cases themselves: `parseCaseDocument`, `CaseSchemaError`, the case types
 (`CaseDocument`, `CaseStep`, `CaseExpectation`, …), and the test-spec
 versioning surface (`DEFAULT_TEST_SPEC_VERSION`, `SUPPORTED_TEST_SPEC_VERSIONS`,
 `resolveTestSpecVersion`, `isTestSpecVersionSupported`,
-`UnsupportedTestSpecVersionError`). `@archmax-ai/harness/sandbox` carries the hook
-contract (`ok`/`veto`/`correct`, `defineHook`, `HookInput`).
+`UnsupportedTestSpecVersionError`). `@archmax-ai/harness/sandbox` carries the
+code-state contract (`defineCodeState`, `CodeStateInput`, `CodeStateArgs`,
+`CodeStateFn`, `SandboxTools`, `SessionHistory`, `HistoryMessage`, `TrailStep`).
 
 ---
 
@@ -1110,11 +1414,11 @@ contract (`ok`/`veto`/`correct`, `defineHook`, `HookInput`).
 
 | Concern                                                                               | File in the SDK                                                                      |
 | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Sandbox prelude (verdict helpers, `defineHook`)                                        | `src/sandbox/assets/parts/core.js`, `lifecycle-hook.js`; `src/sandbox/prelude.ts`        |
-| Hook source preparation (`@archmax-ai/harness/*` import stripping, `export default`, foreign-import errors) | `src/sandbox/imports.ts`                                                      |
-| Executor, sandbox tools, PTC gateway, rubric-dispatch bridge                          | `src/sandbox/executor.ts`, `tools.ts`, `ptc-gateway.ts`, `bridge.ts`                     |
-| Typed entry point (`ok`/`veto`/`correct`, `defineHook`, `HookInput`)                   | `src/public/sandbox.ts`                                                                  |
-| Lifecycle verdict parsing & fail-closed rules                                         | `src/lifecycle/runner.ts`                                                                |
-| Hook input assembly (`messages`)                                                      | `src/lifecycle/runner.ts`, `src/lifecycle/transcript.ts`                                 |
+| Sandbox prelude (the `code` context, `defineCodeState`, the scoped `tools` view)        | `src/sandbox/assets/parts/code-state.js`; `src/sandbox/prelude.ts`                       |
+| Script source preparation (`@archmax-ai/harness/*` import stripping, `export default`, foreign-import errors) | `src/sandbox/imports.ts`                                                      |
+| Executor, sandbox tools, PTC gateway                                                  | `src/sandbox/executor.ts`, `tools.ts`, `ptc-gateway.ts`                                  |
+| Typed entry point (`defineCodeState`, `CodeStateInput`, `SessionHistory`, `HistoryMessage`, `TrailStep`) | `src/public/sandbox.ts`                                                |
+| Running an automated state, its outcomes and controls                                 | `src/workflow/automated.ts`, `automated-controls.ts`                                     |
+| Code-state and grader runs; the history (`messages`, `trail`)                         | `src/workflow/code-state.ts`, `grader-state.ts`, `history.ts`                            |
 | Case engine (host-side)                                                               | `src/testing/` — case schema `case-schema.ts`, discovery `discovery.ts`, assertion evaluation `assertions.ts`, grader `grade.ts`, runner `runner.ts` |
-| Validation diagnostics (missing script file, foreign import, YAML case checks)        | `src/validate/validate.ts`                                                               |
+| Validation diagnostics (missing code-state script, foreign import, YAML case checks)  | `src/validate/validate.ts`                                                               |