@cotal-ai/pi 0.50.0 → 0.50.1

package/dist/index.js

@@ -16719,7 +16719,7 @@ import { isConcreteChannel as isConcreteChannel3, channelInAllow as channelInAll
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.50.0",
+  "version": "0.50.1",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -16818,7 +16818,7 @@ var DOCS_BUNDLE = {
       "title": "Connect Hermes (alpha)",
       "kind": "Guide (informative)",
       "summary": "Hermes (Nous Research) joins a Cotal mesh as a lateral peer, with the same shared cotal tool surface and delivery model as the other connectors.",
-      "body": "# Connect Hermes (alpha)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Hermes](https://nousresearch.com) (Nous Research) joins a Cotal mesh as a lateral peer, with the\nsame shared `cotal_*` tool surface and delivery model as the other connectors. The `hermes`\nconnector ships in the `cotal-ai` package, so no extra install of the connector itself.\n\n**Alpha** means it runs today (spawn it, it joins the mesh and takes turns) but with real\nconstraints, all verified below: it is **Unix-only**, needs an external Python toolchain you\nprovide (`uv` + `hermes-agent` on a supported version range), is **not** offered in the\n`cotal setup` picker, is **not** bundled in the container image (so no containerized Hermes, see\n[Deploy](deploy.md)), and does not support session resume.\n\n## Prerequisites\n\n- **Unix (macOS or Linux).** Windows is unsupported; the connector throws at launch (it uses an\n  AF_UNIX socket bridge and a Python sidecar).\n- **`uv` on your PATH.** The launcher runs `uv run --project <connector> hermes gateway run`, so\n  `uv` provisions the Python environment that provides the `hermes` CLI.\n- **`hermes-agent` in the supported `0.18` to `0.21` range.** The launcher asserts the installed\n  version at startup and fails loudly outside it (no silent degrade), because a different\n  major.minor can move the plugin/platform/hook API this connector targets. A plain `pip` or `uv`\n  resolve installs 0.19.0, the newest release on PyPI, which is inside the range. The 0.20.x and\n  0.21.x releases exist only on GitHub, and an install from git or the install script is also\n  inside the range. Below 0.18 the gateway does not send the reconnect signal the adapter needs,\n  so those versions are refused.\n\n## Spawn it\n\n```bash\ncotal spawn --agent hermes            # foreground in this terminal\nCOTAL_DEFAULT_AGENT=hermes cotal spawn # make it the default harness (an explicit --agent wins)\n```\n\nOr set `agent: hermes` in a team [manifest](manifest.md). Persona and role come from the agent\nfile like any connector (see [agent-files.md](agent-files.md)).\n\nHermes is **not** in the `cotal setup` picker (setup wires only Claude Code and OpenCode), so it\nis spawn-only: there is no setup step for it beyond having the toolchain above.\n\n## Choose a model\n\nHermes is model-agnostic; set any one provider's key in your environment. Model precedence\nmatches the other connectors: the `--model` flag, else the agent file's `model:`, else an ambient\n`HERMES_MODEL`. Hermes exposes no `cotal models` catalog (unlike OpenCode).\n\n## How it binds\n\nUnlike Claude Code or OpenCode (where the harness *is* the process), Hermes runs as a long-lived\n**gateway daemon** that spins up a fresh agent per inbound message. So the mesh connection can't\nlive inside a per-turn process; the connector's command is a small **launcher/supervisor** that\nowns the mesh endpoint for the gateway's whole life and runs `hermes gateway run` as its child.\n\n- The launcher bridges to an in-gateway **Python plugin** (the platform adapter, presence hooks,\n  and the `cotal_*` tools) over local AF_UNIX sockets.\n- It runs the gateway in an isolated `HERMES_HOME` profile (a temp dir), so your own `~/.hermes`\n  is never touched, with approvals off (a supervised agent has no human at the TUI to approve).\n  To put your own Hermes on the mesh instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n- The persona is written as Hermes' `SOUL.md` (its system-prompt file), the one place a system\n  prompt can be set.\n- Quiet-channel ambient is skipped by the automatic bridge pump, even when an older quiet item is\n  ahead of a DM. `cotal_inbox` explicitly surfaces and clears quiet ambient without consuming the\n  connector-owned automatic queue; quiet `@mention`s remain automatic.\n\nThe shared tool surface and inbound-message model are documented once, for all connectors: see\n[mcp-tools.md](mcp-tools.md) and [connect-claude.md](connect-claude.md).\n\n## Use your own Hermes profile\n\nThe isolated profile above is the right default for a disposable seat, but it cannot serve the\nother reason to run Hermes: joining the Hermes you already have, with its credentials and\nintegrations. Those live in your real profile, so a seat on a temp `HERMES_HOME` cannot reach your\nnotification path.\n\nSet `COTAL_HERMES_ADOPT_HOME` to your profile directory to run the gateway there instead:\n\n```bash\nexport COTAL_HERMES_ADOPT_HOME=\"$HOME/.hermes\"\ncotal spawn --agent hermes\n```\n\nThe launcher then installs only its own `plugins/cotal` directory, refreshed on each launch. It\nreads your `config.yaml` and never writes it, and it leaves your `SOUL.md` alone. Enabling the\nplugin stays your decision, so add this to your `config.yaml` first:\n\n```yaml\nplugins:\n  enabled: [cotal]\ngateway:\n  platforms:\n    cotal:\n      enabled: true\n```\n\nWithout those two settings the launch fails and tells you what to add. Two more consequences\nfollow from not writing your config. Your approval settings stay as you left them, so a profile\nthat prompts for approvals will still prompt, with no human at the TUI to answer. An agent file\npersona is refused rather than applied, because applying it means overwriting your `SOUL.md`.\n\n## How presence follows the turn\n\nThe hooks map Hermes's lifecycle onto presence: `pre_llm_call` and `pre_tool_call` write `working`,\n`approval_wait` writes `waiting`, `post_llm_call` and `on_session_end` write `idle`. That last\nworking-to-idle transition is the turn boundary the run relay reads (a surfaced run turn yields\n`done` there), so `gateway_startup` and `on_session_start` write their `idle` through a path that\nmoves presence and nothing else: an adapter reconnect or a session start that lands mid-turn is a\nlifecycle event, and treating it as an ending would yield work the model had not finished.\n\n## Limits\n\n- **Unix-only** (no Windows).\n- **No session resume**: `cotal spawn --resume` throws.\n- **Not containerized**: the [deploy](deploy.md) image bundles only Claude Code and OpenCode (no\n  `uv`/`hermes-agent`), so there is no containerized Hermes today.\n- **Brings its own toolchain**: you supply `uv` and a `hermes-agent` inside the supported range.\n- **No initial prompt**: `cotal spawn --prompt` throws, because the gateway has no first-turn\n  carrier wired, so a seat cannot be given its opening instruction at spawn.\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md) \xB7 [Connect pi](connect-pi.md)\n"
+      "body": "# Connect Hermes (alpha)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Hermes](https://nousresearch.com) (Nous Research) joins a Cotal mesh as a lateral peer, with the\nsame shared `cotal_*` tool surface and delivery model as the other connectors. The `hermes`\nconnector ships in the `cotal-ai` package, so no extra install of the connector itself.\n\n**Alpha** means it runs today (spawn it, it joins the mesh and takes turns) but with real\nconstraints, all verified below: it is **Unix-only**, needs an external Python toolchain you\nprovide (`uv` + `hermes-agent` on a supported version range), is **not** offered in the\n`cotal setup` picker, is **not** bundled in the container image (so no containerized Hermes, see\n[Deploy](deploy.md)), and does not support session resume.\n\n## Prerequisites\n\n- **Unix (macOS or Linux).** Windows is unsupported; the connector throws at launch (it uses an\n  AF_UNIX socket bridge and a Python sidecar).\n- **`uv` on your PATH.** The launcher runs `uv run --project <connector> hermes gateway run`, so\n  `uv` provisions the Python environment that provides the `hermes` CLI.\n- **`hermes-agent` in the supported `0.18` to `0.21` range.** The launcher asserts the installed\n  version at startup and fails loudly outside it (no silent degrade), because a different\n  major.minor can move the plugin/platform/hook API this connector targets. A plain `pip` or `uv`\n  resolve installs 0.19.0, the newest release on PyPI, which is inside the range. The 0.20.x and\n  0.21.x releases exist only on GitHub, and an install from git or the install script is also\n  inside the range. Below 0.18 the gateway does not send the reconnect signal the adapter needs,\n  so those versions are refused.\n\n## Spawn it\n\n```bash\ncotal spawn --agent hermes            # foreground in this terminal\nCOTAL_DEFAULT_AGENT=hermes cotal spawn # make it the default harness (an explicit --agent wins)\n```\n\nOr set `agent: hermes` in a team [manifest](manifest.md). Persona and role come from the agent\nfile like any connector (see [agent-files.md](agent-files.md)).\n\nHermes is **not** in the `cotal setup` picker (setup wires only Claude Code and OpenCode), so it\nis spawn-only: there is no setup step for it beyond having the toolchain above.\n\n## Choose a model\n\nHermes is model-agnostic; set any one provider's key in your environment. Model precedence\nmatches the other connectors: the `--model` flag, else the agent file's `model:`, else an ambient\n`HERMES_MODEL`. Hermes exposes no `cotal models` catalog (unlike OpenCode).\n\nWith none of those set, the launch is refused. The managed profile does not read `~/.hermes`, so a\nmodel configured there is not used, and without a model Hermes would choose one of its own over a\nprovider you may have no key for. The refusal names the three ways to set a model. To run on your\nown profile instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n\n## How it binds\n\nUnlike Claude Code or OpenCode (where the harness *is* the process), Hermes runs as a long-lived\n**gateway daemon** that spins up a fresh agent per inbound message. So the mesh connection can't\nlive inside a per-turn process; the connector's command is a small **launcher/supervisor** that\nowns the mesh endpoint for the gateway's whole life and runs `hermes gateway run` as its child.\n\n- The launcher bridges to an in-gateway **Python plugin** (the platform adapter, presence hooks,\n  and the `cotal_*` tools) over local AF_UNIX sockets.\n- It runs the gateway in an isolated `HERMES_HOME` profile (a temp dir), so your own `~/.hermes`\n  is never touched, with approvals off (a supervised agent has no human at the TUI to approve).\n  To put your own Hermes on the mesh instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n- The persona is written as Hermes' `SOUL.md` (its system-prompt file), the one place a system\n  prompt can be set.\n- Quiet-channel ambient is skipped by the automatic bridge pump, even when an older quiet item is\n  ahead of a DM. `cotal_inbox` explicitly surfaces and clears quiet ambient without consuming the\n  connector-owned automatic queue; quiet `@mention`s remain automatic.\n\nThe shared tool surface and inbound-message model are documented once, for all connectors: see\n[mcp-tools.md](mcp-tools.md) and [connect-claude.md](connect-claude.md).\n\n## Use your own Hermes profile\n\nThe isolated profile above is the right default for a disposable seat, but it cannot serve the\nother reason to run Hermes: joining the Hermes you already have, with its credentials and\nintegrations. Those live in your real profile, so a seat on a temp `HERMES_HOME` cannot reach your\nnotification path.\n\nSet `COTAL_HERMES_ADOPT_HOME` to your profile directory to run the gateway there instead:\n\n```bash\nexport COTAL_HERMES_ADOPT_HOME=\"$HOME/.hermes\"\ncotal spawn --agent hermes\n```\n\nThe launcher then installs only its own `plugins/cotal` directory, refreshed on each launch. It\nreads your `config.yaml` and never writes it, and it leaves your `SOUL.md` alone. Enabling the\nplugin stays your decision, so add this to your `config.yaml` first:\n\n```yaml\nplugins:\n  enabled: [cotal]\ngateway:\n  platforms:\n    cotal:\n      enabled: true\n```\n\nWithout those two settings the launch fails and tells you what to add. Two more consequences\nfollow from not writing your config. Your approval settings stay as you left them, so a profile\nthat prompts for approvals will still prompt, with no human at the TUI to answer. An agent file\npersona is refused rather than applied, because applying it means overwriting your `SOUL.md`.\n\n## How presence follows the turn\n\nThe hooks map Hermes's lifecycle onto presence: `pre_llm_call` and `pre_tool_call` write `working`,\n`approval_wait` writes `waiting`, `post_llm_call` and `on_session_end` write `idle`. That last\nworking-to-idle transition is the turn boundary the run relay reads (a surfaced run turn yields\n`done` there), so `gateway_startup` and `on_session_start` write their `idle` through a path that\nmoves presence and nothing else: an adapter reconnect or a session start that lands mid-turn is a\nlifecycle event, and treating it as an ending would yield work the model had not finished.\n\n## Limits\n\n- **Unix-only** (no Windows).\n- **No session resume**: `cotal spawn --resume` throws.\n- **Not containerized**: the [deploy](deploy.md) image bundles only Claude Code and OpenCode (no\n  `uv`/`hermes-agent`), so there is no containerized Hermes today.\n- **Brings its own toolchain**: you supply `uv` and a `hermes-agent` inside the supported range.\n- **No initial prompt**: `cotal spawn --prompt` throws, because the gateway has no first-turn\n  carrier wired, so a seat cannot be given its opening instruction at spawn.\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md) \xB7 [Connect pi](connect-pi.md)\n"
     },
     {
       "slug": "connect-jcode",
@@ -17000,7 +17000,7 @@ var DOCS_BUNDLE = {
       "title": "Workflow runs",
       "kind": "Concept (informative)",
       "summary": "A workflow run is a program that coordinates agents over hours or days and survives the process that started it.",
-      "body": '# Workflow runs\n\n> **Concept** (informative) \xB7 **For:** people writing a durable multi-agent workflow, and implementers hosting one \xB7 **Normative:** [SPEC \xA714](../SPEC.md#14-workflow-runs-v05) and the language reference [`spec/cotal-lang.md`](../spec/cotal-lang.md)\n\nA **workflow run** is a program that coordinates agents over hours or days and survives the\nprocess that started it. The program is written in **Cotal Lang**, a small subset of JavaScript in\nwhich every interaction with the world is one of a dozen **effects** (`spawn`, `turn`, `ask`,\n`checkpoint`, `sleep`, `wait`, `notify`, `monitor`, and the four concurrency scopes) and everything\nelse is ordinary, pure JavaScript. Every effect is written into the run\'s **step journal** before\nit is performed and settled after, keyed by where in the program it happened rather than by when,\nso a run that dies is resumed on any host by **re-running the program from the top** with recorded\neffects returning their recorded results. Nothing about the interpreter is ever serialized: the\njournal and the program are the whole state.\n\n## A first program\n\n```js\nconst planner = await spawn("planner")\nconst builder = await spawn("builder", { worktree: "wt-1" })\n\nconst plan = await ask(planner, { name: "plan", schema: { steps: "array" } })\nconst ok = await checkpoint("approve-plan", "Approve the plan?", { timeout: "4h", onExpiry: "proceed" })\nif (ok.status !== "resolved") {\n  await notify([planner], { decision: "approve-plan", outcome: "expired" })\n}\n\nconst r = await turn(builder, { name: "build", deadline: "30m" })\nif (r.status === "blocked") {\n  await turn(planner, { name: "unblock" })\n}\n\nconst outcome = await race({\n  reply: () => wait(replied(builder), { timeout: "20m" }),\n  giveUp: () => sleep("1h"),\n}, { name: "await-or-move-on" })\nlog("outcome", outcome.index)\n```\n\nRead it as the flowchart it is. `spawn` brings agents in; `ask` is the narrow case where the\nprogram itself needs a value (`schema` is a record the program hands the handler unchanged; the\nlanguage hashes it and gives it no meaning, and the handlers in this repository enforce it as the\nshorthand of the language reference \xA76.5);\n`checkpoint` is a durable pause a human resolves from anywhere, raced against a durable timer; `turn`\nwakes an agent for one turn and returns how it yielded; `race` runs two branches and keeps the one\nwhose recorded clock is earliest. Agents talk to each other in channels as they always do; the\nprogram never speaks in a channel, and the one thing it can put in front of an agent (`notify`) is a\nbounded decision record, not prose.\n\n## The mental model\n\n- **Pure code is JavaScript.** Loops, records, arrays, closures, template literals, destructuring,\n  `try`/`catch`, arithmetic, `switch`, compound assignment, optional chaining, spread and rest: what\n  you would write anyway, with the parts that hide effects or make meaning depend on the host removed\n  (`class`, `this`, `new`, `for...in`, `==`, labels, regex literals, `Math`/`Date`/`JSON`, promises,\n  generators). Every refusal names its code and the edit that fixes it. The builtins are a short list\n  (`keys`, `map`, `sort`, `json.stringify`, `now()`, `random()`), and arrays, strings and numbers\n  answer their usual methods (`xs.map`, `s.trim()`, `n.toFixed()`) and nothing outside that table.\n  Records and arrays you build are yours to change until they cross an effect boundary; a member you\n  do not own, a host prototype, or a value another branch built is refused with a code, never a\n  surprise.\n- **Every effect is journalled and hashed.** A step is keyed `(scope path, kind, name, occurrence)`\n  and its inputs are hashed. Reorder your program, add a step, rename a variable: recorded steps\n  still match. Change what a step asks (a checkpoint\'s prompt, a sleep\'s duration, a turn\'s\n  deadline) and the resume stops with a **divergence** naming the step, rather than replaying an\n  answer to a question the program no longer asks.\n- **Concurrency is visible.** `parallel`, `race`, `fanOut` and `conclave` are the only ways to do\n  two things at once, each branch gets its own journal namespace, and the scope writes its own\n  entry saying how it settled: which arm won a race is a recorded fact, decided by the arms\'\n  recorded clocks and declaration order, never by a scheduler. A branch may not write to anything\n  declared outside it; return the value and read it out of the scope\'s result.\n- **Time and randomness are tamed.** `now()` is the branch\'s run clock, the end of the last effect\n  it awaited; `random()` is a seeded stream derived per scope. Both replay identically.\n- **Values freeze at the boundary.** What crossed into or out of an effect is what the journal\n  recorded, and it cannot change afterwards; build a new value.\n- **The journal is the debugger.** Every entry carries its key, its inputs\' hash, its outcome and\n  its timing, and every error is in the program\'s own coordinates. A run can be **simulated** with a\n  scripted handler and **dry-run** to a plan before it touches an agent. The simulator is\n  discrete-event: timed effects park at their wake times and are delivered in wake order on one\n  virtual clock, so concurrent branches accumulate the durations they wrote and a simulated `race`\n  is decided by the same rule a live handler produces (least recorded clock, ties by declaration\n  order). A `sleep("1m")` arm beats a `sleep("1h")` arm whatever their declaration order.\n\nFull rules, with every code: [`spec/cotal-lang.md`](../spec/cotal-lang.md).\n\n## Continuing a run\n\n**Resume** is re-execution: the driver replays the journal, the program runs from the top, recorded\nsteps return instantly, and the first unrecorded step is performed live. It refuses a journal that\nbelongs to another run, a pin that differs from the recorded ones, and a different language version.\n\n**Migrate** moves a run onto edited source. A dry walk of the new program over the recorded journal\nfinds every recorded step the edit changed (a divergence) and every one it no longer reaches (an\norphan), and the orphan table says what each means: a removed `sleep` is nothing, a removed `turn`\nalready happened, a removed `spawn` is a live agent you must adopt or release, a removed resolved\n`checkpoint` is a human decision you must explicitly discard. The decision is filed as a\n`migration` record with the actor\'s name on it. An adopted seat (`--adopt <name>#<uid>`) goes to\nthe edited program\'s next `spawn` of that persona, which returns the recorded handle and mints\nnothing, so the agent keeps its identity, its worktree and its turn history across the edit. A\nreleased seat (`--release <name>#<uid>`) is despawned when the migration commits, through the same\ndischarge a cancelled branch\'s seat leaves by, so the record never claims a release nothing did.\nThe spawn that adopts a seat binds the orphaned spawn\'s goal as its own, so a resume of that step\nreads the same seat back and a cancellation of it despawns the seat it holds.\n\n**Fork** starts a new run from a named step of an old one, copying the prefix under the parent\'s\npins (seed included, so the copied history\'s pure draws are the same draws). The child is a new run\nunder a new id whose record names the parent and the cut step (`forkedFrom`); the parent is\nuntouched. A spawn inside the copied prefix is honoured by its `onFork`: `"adopt"` copies it, and\nthe child shares the parent\'s agent (the manager shows that seat one turn at a time across both\nruns); `"respawn"`, the default, would mint a fresh identity the copied turns do not address, so\nthis host refuses that cut (L5019) rather than rewriting the parent\'s history.\n\nFork planning and migration inspection use the recorded language version. Version-1 history uses\nthe interpreter. Version-2 history is inspected inside a locked-down worker with a read-only\njournal, without a live effect handler or durable store. Inspection stops before the fork\'s cut\nstep or any effect that needs new work. Program catch and finally blocks cannot extend the cut.\nThe recorded pins are preserved.\n\n## From an agent session\n\nFresh `cotal setup` defaults declare `capabilities: [spawn, run]`. On a static-auth mesh,\nthat exposes `cotal_run` alongside the teammate tools. The manager must be running.\nRead `cotal_docs` pages `lang-card` and `workflows`, then try:\n\n```json\n{\n  "verb": "start",\n  "source": "await sleep(\\"1s\\", { name: \\"first-run\\" });",\n  "file": "first-run.cotal.js"\n}\n```\n\nPass this object to `cotal_run`. `source` contains the program; `file` only labels diagnostics\nand reads nothing from disk. The response returns a run ID before execution finishes. Call\n`cotal_run` with `verb: "status"` and that `runId` to inspect the state and step journal.\nA completed timer records its sleep step as `ok`.\n\n### If `cotal_run` is missing\n\n1. Call `cotal_orientation` and check the connector version, capabilities and tool list.\n   Upgrade an older installation using the [upgrade guide](https://github.com/Cotal-AI/Cotal/blob/main/docs/UPGRADING.md).\n2. Have the operator add `run` to the persona\'s existing `capabilities` list, for example\n   `capabilities: [spawn, run]`. `spawn` alone does not expose `cotal_run`. Setup leaves existing\n   personas unchanged except for its [byte-exact legacy migration](getting-started.md).\n   Peer persona-definition tools cannot grant capabilities.\n3. Relaunch the agent through the manager from the updated persona so it receives newly issued\n   credentials and a fresh connector configuration. Editing the file or reconnecting with the\n   old credential does not grant new broker permissions. If the launch sets `COTAL_CAPABILITIES`,\n   update that override too; it takes precedence over the file.\n4. Check `cotal_orientation` again, then call `cotal_run` with `verb: "ps"` before starting work.\n\nTool visibility alone does not establish execution support. Hosted runs currently require\nstatic authentication with issued caller authority. Open meshes can expose the tool but refuse\nhosted runs; user-auth meshes also refuse them. A legacy credential without issued authority\nmust be replaced through the current issuance path before it can start a hosted run.\n\n## Operating a run\n\nThe manager hosts runs. `cotal run start` hands the program to the manager of the resolved mesh\n(the usual `--space` / `--server` / `--creds` flags), which validates it, mints the run id, drives\nit in its own process, and answers with the id once the run is recorded. The terminal is free the\nmoment the id prints; the run continues on the manager through every pause, and a manager restart\ntakes back every run it had recorded running, from the journal, under the next epoch. `resume`\nnames a run the manager recorded and is refused while the manager is already driving it. `ps` and\n`journal` read; `answer` resolves an open checkpoint, or an open `ask` attempt, from any terminal\nor agent that holds the `run` capability.\n\n```bash\ncotal run start --file build.cotal.js                   # the manager starts it; the minted id is printed\ncotal run ps                                            # list run records: state, holder, lineage\ncotal run journal run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # print the durable step journal\ncotal run resume run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # the manager takes the run back\ncotal run answer run-3f2a90c41b7e0d5a6c884e19b02df4a1 "/checkpoint:approve#0" --value \'"yes"\'\n```\n\nA program that does not validate is refused before anything is recorded, with every problem in the\nanswer as the validator would print it. The driver records the program beside the run, so `resume`\ntakes the run id alone and the manager reads the source back; an edited program is a `migrate` or a\n`fork`, never a resume. An answer is recorded under the answerer the manager knows from the\ncaller\'s credential: a managed agent by its name, anyone else by their principal. The request\ncarries no name. An agent with `capabilities: [run]` has the same five verbs as the `cotal_run`\ntool ([MCP tools](mcp-tools.md)), so a program can be written and started from inside a session.\nA `start` or `resume` answers once the run\'s record is written, within a bounded wait; a manager\nthat is still taking back a predecessor\'s runs at boot refuses both with `unavailable`, and a\nretry a moment later is the whole remedy.\n\n`--local` drives the run in this process instead: `start`, `resume` and `answer` exit when the\ndrive settles, `--by <who>` names the answerer, and `cotal run resume <runId> --local --file\n<program>` is how a run with no recorded program is continued. On a static mesh the local drive\nmints the run\'s own credential from the folder\'s trust material, so it runs from the mesh\'s\nproject folder. A local start also names the run\'s channel ceiling itself:\n`--admit-read <channels> --admit-publish <channels>`, comma-separated patterns or `none`, both\nrequired. The record it writes says an operator admitted the run and why, and the host checks\nit the same way it checks a hosted admission. A user-auth mesh runs no programs yet, hosted or\nlocal: the manager refuses the family by name, since a hosted run\'s seats would be spawned under\nthe static owner, which a user mesh refuses, and a user bearer holds no run rows. An open mesh\nhosts none either, since it issues no caller authority to admit a run under.\n\nA hosted run is **admitted** under the caller that started it. The caller\'s credential is an\nissuance ([identity and auth](identity-and-auth.md#issued-authority)): its requests ride a\nversioned rail that carries the credential\'s generation, and the manager resolves that\ngeneration\'s recorded permission ceiling and writes it beside the run before the driver starts.\nThat ceiling, the caller\'s own channel scope as it was issued, is what the run may read and post\nin channels; the manager\'s own reach never stands in for it. A request from a credential minted\nwithout an issuance is refused with `permission-denied` and a detail naming the caller. A run\nwhose caller had no channels can still sleep, checkpoint and turn agents; its `wait` on a channel\nis refused at the effect.\n\n`cotal run revoke <runId> --local --by <who> --reason <text>` writes the run\'s revocation marker\nfrom the project folder. The admission itself is never rewritten. Every host reads the marker\nbefore its next channel effect, so an open `wait` refuses at its next poll, and no resume,\ntakeover or manager restart continues the run. Revoking twice is not an error, and the first\nreason stands. A run whose admission is missing or revoked is left parked by the manager\'s boot\nreconcile, named in its log.\n\nA run whose step was refused (L5016) stays held; a\nresume on a host that can perform the step performs it live and continues from there.\n`journal` prints what an open pause asks beneath its step key, which is the address `answer` takes\nback. Checkpoint expiry rides the mediated timer writer, which the delivery daemon pumps on a live\nmesh; on a bare broker a pause still resolves, it just cannot expire.\n\n## What is on the wire\n\nThe run\'s wire footprint is [SPEC \xA714](../SPEC.md#14-workflow-runs-v05):\n\n| Thing | Where | What it is |\n| --- | --- | --- |\n| the run | `run.<endpoint>.<runId>` record | the resolved **pins** (seed, logical epoch, budgets, language version) on the immutable half; holder, lease and `journalHigh` on the status half |\n| the program | `program.<endpoint>.<runId>` record | the source the run was started from, verbatim, written once by the driver that pinned the run; what a resume reads and what a migration is measured against |\n| the step journal | `WFJ_<space>` stream, one subject per run | append-only, no age eviction, no Direct Get; every append fenced by the run subject\'s own sequence; takeover is replay-then-activate |\n| a checkpoint answer | `answer.<endpoint>.<token>.<answerId>` | the payload beside the one-use settle fact; the settle names the answer it accepted |\n| a notice | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>` | one bounded decision told to one agent, rendered ahead of its next turn |\n| a migration | `migration.<endpoint>.<runId>.<migrationId>` | the report and who applied it, keyed by the report\'s own digest |\n| the admission | `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>` | the caller the run was admitted for, its channel ceiling and its provenance; written once before the driver starts, and the store refuses a second write on the key |\n| a revocation | `revoked.v1.<endpoint>.<runId>` in the same store | who revoked the run and why; create-only, idempotent, permanent at the broker, read by every host before its next channel effect |\n\nA run\'s **driver** connects on a `run-driver` credential minted for one run and takeover\nattempt. It can append to its journal, use its replay durable, and write its own `run`, `program`,\n`notice` and `migration` records. It has no store point reads, checkpoint writes, chat consumers,\nor channel and membership registry grants.\n\nThe hosting process keeps a separate `run-mediator` connection for effects and reads. The driver\nreceives methods and data from that host; it never receives the mediator credential or connection.\nThe host checks the journal\'s current activation and step identity before dispatch, and checks\npause and wait authority again at each operation. Cancellation cleanup also admits losing steps\nnamed by a settled parent whose `cancel.issued` is still false. That permission allows cleanup;\nit cannot mint or rearm a cancelled pause. Wait acknowledgements consume host-held delivery\nreceipts. A recorded match can be reread only at its bound sequence and channel. A conclave\'s\nrecorded ownership flag must match its step-derived channel before registry writes or cleanup.\n\nThe mediator retains endpoint-wide checkpoint rights and stream-wide leader reads as trusted\nhost authority. Record reads exposed to the driver are restricted to its own run\'s keys. Reads\nthat decide writes remain leader-served. A read of the journal uses the run\'s filtered replay\ndurable, including the diagnostic for a journal with no run record. That durable is named after\nthe takeover, and an attempt reads it many times, so reads under one takeover run one at a time in\nthe hosting process and a replay removes a durable of its own name that an interrupted earlier read\nleft behind. A durable that survives a replay\'s own delete belongs to a reader the process cannot\naccount for, and reading its tail is refused.\n\nA served read uses a one-shot `run-operator` credential. An answer uses a read to find the open\npause, then a second credential pinned to that token for the answer and settlement.\n`cotal run --local` uses the same driver/mediator split. On an authenticated mesh it needs the\nlocally recorded space signer to mint both credentials; a single `--creds` file is refused.\nDirect library users supplying broker clients to `MeshHandler` are constructing a trusted effect\nhost. A hosted driver receives its closed effect interface instead.\n\nThis split confines broker credentials; it is not process isolation for injected host code.\nThe runtime and its effect host share the manager process. A run\'s channel reach is the admitted\nceiling ([SPEC \xA714.8](../SPEC.md#148-run-admission)): the starting caller\'s issued channel scope,\nrecorded once in `cotal_admission_<space>` under a per-run `run-admitter` credential the driver\nnever holds, and re-read by the host before every channel effect. Spawn and turn keep their own\ndelegated checks; `notify` writes agent-addressed notices and is not channel publication. Treat\n`run` as program-execution authority bounded by that ceiling, not as sandboxing of the program.\n\nA version-1 fork can replay its settled parent history through the host. Inherited checkpoint\nidentifiers carry no authority to read, rearm or claim the parent\'s pauses. New child effects use\nchild-derived identifiers. A fork is a new run and takes a new admission under the caller who\nforks it; the parent\'s ceiling is not inherited.\n\n\n## What ships today\n\nThe language, its validator, interpreter, simulator and dry run are `@cotal-ai/lang`\n(`packages/lang`), usable in-process with your own effect handler and with no broker: `validate(src)`,\nthen `run(src, { runId, handler })`, and `resume(src, journal, { runId, pins, handler })` to pick a\nrun up from its journal (the package README has the snippet, with `SimHandler` as the handler). That\nis the in-process route, yours to drive with your own handler; a run the driver starts executes on\nthe compiled engine, as the engine paragraph below says. The wire\nsubstrate of \xA714 (the `WFJ_<space>` stream, the five record kinds, the activation barrier, the\nper-run grants) is in `@cotal-ai/core`, and the run driver, journal store, migrate and fork are\n`@cotal-ai/runtime` (`implementations/runtime`). On the mesh handler, `sleep`, `checkpoint`,\n`wait(message(...))`, `wait(idle(...))`, `wait(down(...))`, `wait(replied(...))`, `notify`,\n`spawn`, `conclave`, `ask`, `monitor` and `turn` are durable.\n`spawn` is\nthe manager\'s spawn action submitted under the step\'s own identity: the goal binds under the step\'s\nrequest id, so a resumed run re-attaches to the same seat instead of allocating a second one, a\nfailed or refused spawn is catchable as L4002 with the manager\'s recorded reason, and a spawn on a\nrace branch that loses is despawned by the run\'s own cancellation sweep. `permits` are the budgets\nthis host meters: `turns`, how many turns the run may dispatch to the agent, and `wallClock`, a\nduration from the spawn after which no turn is admitted. The turn that would exceed one is the\ncatchable L4001 (kind `permit-turns` or `permit-wall-clock`; a deadline the remaining wall clock\ncannot hold counts as exceeding it), an adopted run counts the turns its journal recorded, and a\nbudget the host has no meter for, such as `tokens` or `spend`, is refused at the spawn rather than\naccepted and ignored. `supervise` is the restart policy this host asks the manager to enforce:\n`restarts`, how many in-window process deaths may come back under the same handle, and `window`,\nthe duration those deaths are counted in (default `10m`). The manager restarts the process in\nplace under the same name, lifecycle uid, persona, worktree and permits; `monitor` does not fire\nfor a restart, and `wait(down)` fires only when the seat is gone for good. Spending the budget\nretires the seat, and the next `turn` is the catchable L4002. A policy this host cannot enforce\n(an unknown key, a user-mode seat, or a runtime that cannot respawn a name in place) is refused\nat the spawn rather than accepted and ignored. `conclave` joins its\nmembers to a real channel as durable membership rows: the channel derives from the step\'s own\nrequest id when the program names none (a program-named channel is borrowed, never torn down, and\na membership that predates the conclave survives its close), each member handle resolves to its\nprincipal through the seat\'s own presence row (an absent member is catchable as L4002), and a\nconclave cancelled on a losing branch is released by the same cancellation sweep. `ask` parks one\ncheckpoint-plane pause per attempt, answered through `cotal run answer` as a checkpoint is, and\ntells the agent through the same relay `turn` uses: one relay per attempt under the attempt\'s own\ntoken, carrying the schema, the attempt count, the deadline and the previous refusal, which the\nseat\'s connector renders as the record wanted and the command that answers it. An ask addresses\nan agent the run spawned (anything else refuses before an attempt opens), a resumed attempt tells\nthe seat nothing twice, and a seat gone at the relay is L4002. On the pause itself:\nthe shorthand of the language reference \xA76.5 is enforced (an unreadable schema is L4022), a\nnon-conforming answer costs one attempt and its refusal reason is recorded on the entry for the\nanswerer to read, exhausted attempts (default one) are the catchable L4006, and so is the one\nabsolute deadline for the whole ask passing with no conforming record (its kind is `ask-deadline`).\n`checkpoint` binds what it asks on its own entry, so `cotal run journal` prints the question under\nthe step key an answer is addressed by while the pause is open: the address alone left whoever was\nasked reading the source to find out what "approve" meant. An `escalate` addressed to an agent this\nrun spawned is relayed to that seat through the same turn relay an `ask` uses, carrying the prompt\nand the token to answer under; a `to` naming anyone else is a person, and their pause stays the\none anybody can answer, with the addressee recorded and rendered beside the question.\n`monitor` registers interest in an agent, and the\nregistration is the journal entry itself, carrying the handle it registered: monitoring an agent\nthat is already dead succeeds, and the death is the wait\'s to observe. `wait(down(...))` observes\na monitored agent, and refuses one the run never performed `monitor` on. It reads the death off presence liveness, the\nsame witness a conclave join resolves members through: the value carries the handle, the reason\n(`lapsed` when nothing live holds the name any more, `superseded` when a live row holds it under\na different incarnation) and the time of observation, a wait that begins after the death resolves\nat once, and a timeout resolves null on one absolute deadline a resumed run re-attaches to.\n`turn` wakes one seat for one host turn through the manager as a pull-shaped relay: the run\nsubmits the turn under the step\'s own identity, the manager holds it as a goal pinned to the\nseat\'s incarnation, and the seat pulls it under its own reach ahead of its next host turn, so\nnothing is pushed into a session mid-thought. The payload the seat reads names the run and the\nstep and carries the rendered run context, plus any pending notices addressed to it, which the\nturn consumes. The seat yields through `cotal_yield` (`done`, `blocked`, or `handoff` with an\naddressee), and ending its host turn yields `done` for every turn it was shown. A `handoff` names\nanother seat the same run spawned: the next `turn` in the same scope to that seat records the\nlink, a handoff to a name the run never spawned is the catchable L4005, and one to a seat bound\nto a different worktree is L4004. The deadline elapsing before any yield is the catchable L4003:\nthe acceptance names the instant, the manager\'s goal-bound hold denies at it, and the run arms its\nown pause on that same instant, so either side outliving the other still converges on the same\nanswer. A seat that dies mid-turn is read off its own presence row by the run itself and is the\ncatchable L4002, and a death the manager marked on the deadline terminal reads the same way. Two\nturns on one seat, from two branches or from two runs, reach it one at a time: the language\ndispatches the second when the first settles, and the manager shows a seat the oldest unsettled\nturn alone. On an auth mesh the relay needs no extra grant: every spawned seat\'s baseline\ncredential carries its own pull and yield rows, the run driver\'s operator instrument carries the\nturn request, and the manager arms the deadline hold over its own serve grant and expires it\nitself once due. An accept the manager cannot finish is unwound to a failed terminal on the goal\nit bound, and a retry of that submission is refused naming the terminal rather than accepted a\nsecond time.\n`wait(replied(...))` observes those turns from another branch: a completed turn is a reply, and\nthe wait resolves with the observation record (the handle, the yield\'s status and note, the\nyield\'s own stamp). It reads as a level, the way `wait(down)` does: a reply that already exists\nresolves the wait at once, and two replies resolve to the latest by the yield\'s stamp. A denied\nor cancelled turn is never a reply, so an unanswered wait rides its own mediated timeout to\n`null`, and a handle the run never spawned or turned refuses loudly, since only this run\'s turns\nare observable. A turn the run itself ended without an accepted yield (its deadline, a\ncancellation, a refused handoff) is never a reply, whatever the seat yields to the relay later.\nA `spawn` may bind its agent to a **logical worktree** (`spawn("builder", { worktree: "wt-1" })`):\nthe handle carries the id, and the run enforces the one rule the language states about it: two\nagents never share a worktree concurrently. The validator rejects the literal case up front\n(L3022: two branches of one concurrent scope spawning into one literal worktree, named branch\nfunctions included), and the runtime guards the rest, computed ids included: a spawn claims its\ntree before it submits, so a second spawn into a tree held by a live seat or by a spawn still\nbringing one up is the catchable L4008, a spawn that ends without a handle gives the tree back,\nand the tree is reusable the moment a holder\'s presence row is gone, so a discharged race loser\nor a crashed seat releases its tree with no bookkeeping. A spawn the endpoint refuses at accept\nis the catchable L4000 (L4001 when the refusal is the endpoint\'s seat capacity), and one whose\nseat never came up is L4002. A refusal that states the command did not run is answered\nbefore it gets that far. In a space served by more than one manager the resolve and the invoke\nare separate trips through the same anycast queue, so a run\'s call can reach an instance it did\nnot resolve against, and that instance refuses ahead of any effect. The run drops its resolved\nhandle, re-describes and re-issues, for a bounded number of attempts; after them the refusal\nsurfaces as the effect\'s own failure and still states that nothing ran. A spawn that names a\n`placement` addresses one instance by name, so a refusal from it is that incarnation answering\nabout itself and is never re-issued. A turn handoff across worktrees is the L4004 described above. Recovery keeps these honest: a resumed run\nreseeds its roster, holders and handoff memos from its own journal, and the driver re-issues any\nrecorded-but-undischarged cancellation at adoption, before the engine performs a new step, so a\nloser a crash left alive does not keep its seat or its tree while the resumed run works on. The\nsame sweep withdraws a cancelled branch\'s undelivered notices: a notice waits on the run for its\naddressee\'s next turn, so a decision the run cancelled would otherwise arrive at an agent with\nnothing to distinguish it from one that stood.\n\nEvery effect the language defines performs on the mesh handler; nothing is refused as\nnot-yet-durable any more. The operator surface over the driver is `cotal run`; the section above has the verbs.\n\n**Two engines, and which one runs your program.** The tree-walker is language version `1` and the\ncompiled engine is version `2`, two languages rather than two speeds of one (`spec/cotal-lang.md`\n\xA78.4 lists what differs). The driver hosts both: **every run a driver starts is stamped `2` and\nexecuted by the compiled engine**. The program runs in its own locked-down worker thread with\nnothing in its global scope, while the effects and the durable journal stay in the driver\'s process,\nbridged over a message port. No socket or credential enters the isolate holding the program,\nand **every version-`1` record keeps replaying on the walker**, which is the walker\'s job. The\ndriver serves a declared set of versions, and a record whose version it does not serve is refused\nby name (**L5023**) with the run left untouched, instead of being replayed by whichever engine\nhappens to be present. Records do not cross between versions in either direction; the repair is to\nresume on the recorded version, or to fork.\n\n**The engine needs node 22 or newer** and refuses below it as `EngineUnavailable`, which is an\nimplementation limit and not a language error: it carries no `L` code, so there is nothing to look\nup in the catalog. It is a floor rather than a warning because the engine\'s frame plumbing rests on\n`AsyncLocalStorage`, and 22 is the lowest node it has been measured on. The walker has no such floor.\n'
+      "body": '# Workflow runs\n\n> **Concept** (informative) \xB7 **For:** people writing a durable multi-agent workflow, and implementers hosting one \xB7 **Normative:** [SPEC \xA714](../SPEC.md#14-workflow-runs-v05) and the language reference [`spec/cotal-lang.md`](../spec/cotal-lang.md)\n\nA **workflow run** is a program that coordinates agents over hours or days and survives the\nprocess that started it. The program is written in **Cotal Lang**, a small subset of JavaScript in\nwhich every interaction with the world is one of a dozen **effects** (`spawn`, `turn`, `ask`,\n`checkpoint`, `sleep`, `wait`, `notify`, `monitor`, and the four concurrency scopes) and everything\nelse is ordinary, pure JavaScript. Every effect is written into the run\'s **step journal** before\nit is performed and settled after, keyed by where in the program it happened rather than by when,\nso a run that dies is resumed on any host by **re-running the program from the top** with recorded\neffects returning their recorded results. Nothing about the interpreter is ever serialized: the\njournal and the program are the whole state.\n\n## A first program\n\n```js\nconst planner = await spawn("planner")\nconst builder = await spawn("builder", { worktree: "wt-1" })\n\nconst plan = await ask(planner, { name: "plan", schema: { steps: "array" } })\nconst ok = await checkpoint("approve-plan", "Approve the plan?", { timeout: "4h", onExpiry: "proceed" })\nif (ok.status !== "resolved") {\n  await notify([planner], { decision: "approve-plan", outcome: "expired" })\n}\n\nconst r = await turn(builder, { name: "build", deadline: "30m" })\nif (r.status === "blocked") {\n  await turn(planner, { name: "unblock" })\n}\n\nconst outcome = await race({\n  reply: () => wait(replied(builder), { timeout: "20m" }),\n  giveUp: () => sleep("1h"),\n}, { name: "await-or-move-on" })\nlog("outcome", outcome.index)\n```\n\nRead it as the flowchart it is. `spawn` brings agents in; `ask` is the narrow case where the\nprogram itself needs a value (`schema` is a record the program hands the handler unchanged; the\nlanguage hashes it and gives it no meaning, and the handlers in this repository enforce it as the\nshorthand of the language reference \xA76.5);\n`checkpoint` is a durable pause a human resolves from anywhere, raced against a durable timer; `turn`\nwakes an agent for one turn and returns how it yielded; `race` runs two branches and keeps the one\nwhose recorded clock is earliest. Agents talk to each other in channels as they always do; the\nprogram never speaks in a channel, and the one thing it can put in front of an agent (`notify`) is a\nbounded decision record, not prose.\n\n## The mental model\n\n- **Pure code is JavaScript.** Loops, records, arrays, closures, template literals, destructuring,\n  `try`/`catch`, arithmetic, `switch`, compound assignment, optional chaining, spread and rest: what\n  you would write anyway, with the parts that hide effects or make meaning depend on the host removed\n  (`class`, `this`, `new`, `for...in`, `==`, labels, regex literals, `Math`/`Date`/`JSON`, promises,\n  generators). Every refusal names its code and the edit that fixes it. The builtins are a short list\n  (`keys`, `map`, `sort`, `json.stringify`, `now()`, `random()`), and arrays, strings and numbers\n  answer their usual methods (`xs.map`, `s.trim()`, `n.toFixed()`) and nothing outside that table.\n  Records and arrays you build are yours to change until they cross an effect boundary; a member you\n  do not own, a host prototype, or a value another branch built is refused with a code, never a\n  surprise.\n- **Every effect is journalled and hashed.** A step is keyed `(scope path, kind, name, occurrence)`\n  and its inputs are hashed. Reorder your program, add a step, rename a variable: recorded steps\n  still match. Change what a step asks (a checkpoint\'s prompt, a sleep\'s duration, a turn\'s\n  deadline) and the resume stops with a **divergence** naming the step, rather than replaying an\n  answer to a question the program no longer asks.\n- **Concurrency is visible.** `parallel`, `race`, `fanOut` and `conclave` are the only ways to do\n  two things at once, each branch gets its own journal namespace, and the scope writes its own\n  entry saying how it settled: which arm won a race is a recorded fact, decided by the arms\'\n  recorded clocks and declaration order, never by a scheduler. A branch may not write to anything\n  declared outside it; return the value and read it out of the scope\'s result.\n- **Time and randomness are tamed.** `now()` is the branch\'s run clock, the end of the last effect\n  it awaited; `random()` is a seeded stream derived per scope. Both replay identically.\n- **Values freeze at the boundary.** What crossed into or out of an effect is what the journal\n  recorded, and it cannot change afterwards; build a new value.\n- **The journal is the debugger.** Every entry carries its key, its inputs\' hash, its outcome and\n  its timing, and every error is in the program\'s own coordinates. A run can be **simulated** with a\n  scripted handler and **dry-run** to a plan before it touches an agent. The simulator is\n  discrete-event: timed effects park at their wake times and are delivered in wake order on one\n  virtual clock, so concurrent branches accumulate the durations they wrote and a simulated `race`\n  is decided by the same rule a live handler produces (least recorded clock, ties by declaration\n  order). A `sleep("1m")` arm beats a `sleep("1h")` arm whatever their declaration order.\n\nFull rules, with every code: [`spec/cotal-lang.md`](../spec/cotal-lang.md).\n\n## Continuing a run\n\n**Resume** is re-execution: the driver replays the journal, the program runs from the top, recorded\nsteps return instantly, and the first unrecorded step is performed live. It refuses a journal that\nbelongs to another run, a pin that differs from the recorded ones, and a different language version.\n\n**Migrate** moves a run onto edited source. A dry walk of the new program over the recorded journal\nfinds every recorded step the edit changed (a divergence) and every one it no longer reaches (an\norphan), and the orphan table says what each means: a removed `sleep` is nothing, a removed `turn`\nalready happened, a removed `spawn` is a live agent you must adopt or release, a removed resolved\n`checkpoint` is a human decision you must explicitly discard. The decision is filed as a\n`migration` record with the actor\'s name on it. An adopted seat (`--adopt <name>#<uid>`) goes to\nthe edited program\'s next `spawn` of that persona, which returns the recorded handle and mints\nnothing, so the agent keeps its identity, its worktree and its turn history across the edit. A\nreleased seat (`--release <name>#<uid>`) is despawned when the migration commits, through the same\ndischarge a cancelled branch\'s seat leaves by, so the record never claims a release nothing did.\nThe spawn that adopts a seat binds the orphaned spawn\'s goal as its own, so a resume of that step\nreads the same seat back and a cancellation of it despawns the seat it holds.\n\n**Fork** starts a new run from a named step of an old one, copying the prefix under the parent\'s\npins (seed included, so the copied history\'s pure draws are the same draws). The child is a new run\nunder a new id whose record names the parent and the cut step (`forkedFrom`); the parent is\nuntouched. A spawn inside the copied prefix is honoured by its `onFork`: `"adopt"` copies it, and\nthe child shares the parent\'s agent (the manager shows that seat one turn at a time across both\nruns); `"respawn"`, the default, would mint a fresh identity the copied turns do not address, so\nthis host refuses that cut (L5019) rather than rewriting the parent\'s history.\n\nFork planning and migration inspection use the recorded language version. Version-1 history uses\nthe interpreter. Version-2 history is inspected inside a locked-down worker with a read-only\njournal, without a live effect handler or durable store. Inspection stops before the fork\'s cut\nstep or any effect that needs new work. Program catch and finally blocks cannot extend the cut.\nThe recorded pins are preserved.\n\n## From an agent session\n\nFresh `cotal setup` defaults declare `capabilities: [spawn, run]`. On a static-auth mesh,\nthat exposes `cotal_run` alongside the teammate tools. The manager must be running.\nRead `cotal_docs` pages `lang-card` and `workflows`, then try:\n\n```json\n{\n  "verb": "start",\n  "source": "await sleep(\\"1s\\", { name: \\"first-run\\" });",\n  "file": "first-run.cotal.js"\n}\n```\n\nPass this object to `cotal_run`. `source` contains the program; `file` only labels diagnostics\nand reads nothing from disk. The response returns a run ID before execution finishes. Call\n`cotal_run` with `verb: "status"` and that `runId` to inspect the state and step journal.\nA completed timer records its sleep step as `ok`.\n\n### If `cotal_run` is missing\n\n1. Call `cotal_orientation` and check the connector version, capabilities and tool list.\n   Upgrade an older installation using the [upgrade guide](https://github.com/Cotal-AI/Cotal/blob/main/docs/UPGRADING.md).\n2. Have the operator add `run` to the persona\'s existing `capabilities` list, for example\n   `capabilities: [spawn, run]`. `spawn` alone does not expose `cotal_run`. Setup leaves existing\n   personas unchanged except for its [byte-exact legacy migration](getting-started.md).\n   Peer persona-definition tools cannot grant capabilities.\n3. Relaunch the agent through the manager from the updated persona so it receives newly issued\n   credentials and a fresh connector configuration. Editing the file or reconnecting with the\n   old credential does not grant new broker permissions. If the launch sets `COTAL_CAPABILITIES`,\n   update that override too; it takes precedence over the file.\n4. Check `cotal_orientation` again, then call `cotal_run` with `verb: "ps"` before starting work.\n\nTool visibility alone does not establish execution support. Hosted runs currently require\nstatic authentication with issued caller authority. Open meshes can expose the tool but refuse\nhosted runs; user-auth meshes also refuse them. A legacy credential without issued authority\nmust be replaced through the current issuance path before it can start a hosted run.\n\n## Operating a run\n\nThe manager hosts runs. `cotal run start` hands the program to the manager of the resolved mesh\n(the usual `--space` / `--server` / `--creds` flags), which validates it, mints the run id, drives\nit in its own process, and answers with the id once the run is recorded. The terminal is free the\nmoment the id prints; the run continues on the manager through every pause, and a manager restart\ntakes back every run it had recorded running, from the journal, under the next epoch. `resume`\nnames a run the manager recorded and is refused while the manager is already driving it. `ps` and\n`journal` read; `answer` resolves an open checkpoint, or an open `ask` attempt, from any terminal\nor agent that holds the `run` capability.\n\n```bash\ncotal run start --file build.cotal.js                   # the manager starts it; the minted id is printed\ncotal run ps                                            # list run records: state, holder, lineage\ncotal run journal run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # print the durable step journal\ncotal run resume run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # the manager takes the run back\ncotal run answer run-3f2a90c41b7e0d5a6c884e19b02df4a1 "/checkpoint:approve#0" --value \'"yes"\'\n```\n\nA program that does not validate is refused before anything is recorded, with every problem in the\nanswer as the validator would print it. The driver records the program beside the run, so `resume`\ntakes the run id alone and the manager reads the source back; an edited program is a `migrate` or a\n`fork`, never a resume. An answer is recorded under the answerer the manager knows from the\ncaller\'s credential: a managed agent by its name, anyone else by their principal. The request\ncarries no name. An agent with `capabilities: [run]` has the same five verbs as the `cotal_run`\ntool ([MCP tools](mcp-tools.md)), so a program can be written and started from inside a session.\nA `start` or `resume` answers once the run\'s record is written, within a bounded wait; a manager\nthat is still taking back a predecessor\'s runs at boot refuses both with `unavailable`, and a\nretry a moment later is the whole remedy.\n\n`--local` drives the run in this process instead: `start`, `resume` and `answer` exit when the\ndrive settles, `--by <who>` names the answerer, and `cotal run resume <runId> --local --file\n<program>` is how a run with no recorded program is continued. On a static mesh the local drive\nmints the run\'s own credential from the folder\'s trust material, so it runs from the mesh\'s\nproject folder. A local start also names the run\'s channel ceiling itself:\n`--admit-read <channels> --admit-publish <channels>`, comma-separated patterns or `none`, both\nrequired. The record it writes says an operator admitted the run and why, and the host checks\nit the same way it checks a hosted admission. A user-auth mesh runs no programs yet, hosted or\nlocal: the manager refuses the family by name, since a hosted run\'s seats would be spawned under\nthe static owner, which a user mesh refuses, and a user bearer holds no run rows. An open mesh\nhosts none either, since it issues no caller authority to admit a run under.\n\nA hosted run is **admitted** under the caller that started it. The caller\'s credential is an\nissuance ([identity and auth](identity-and-auth.md#issued-authority)): its requests ride a\nversioned rail that carries the credential\'s generation, and the manager resolves that\ngeneration\'s recorded permission ceiling and writes it beside the run before the driver starts.\nThat ceiling, the caller\'s own channel scope as it was issued, is what the run may read and post\nin channels; the manager\'s own reach never stands in for it. A request from a credential minted\nwithout an issuance is refused with `permission-denied` and a detail naming the caller. A run\nwhose caller had no channels can still sleep, checkpoint and turn agents; its `wait` on a channel\nis refused at the effect.\n\n`cotal run revoke <runId> --local --by <who> --reason <text>` writes the run\'s revocation marker\nfrom the project folder. An empty `--by` or `--reason` is refused before anything is written. The\nadmission itself is never rewritten. Every host reads the marker\nbefore its next channel effect, so an open `wait` refuses at its next poll, and no resume,\ntakeover or manager restart continues the run. Revoking twice is not an error, and the first\nreason stands. A run whose admission is missing or revoked is left parked by the manager\'s boot\nreconcile, named in its log.\n\n`run ps --local` reads the marker beside each run record and prints `revoked` for a run that\ncarries one, whatever state the record itself holds, with the revoker and the reason under the\ntable. The record is display only here: a revoke writes no terminal state, because no host drove\nthe run to one and the journal owns the facts. A marker the listing cannot read, whether the store\nis unreachable or the marker has a version or shape it does not know, prints `unchecked` in the\n`STATE` column. The reason and the state the record carries go to stderr, and the command exits 1\nonce every row is printed. The hosted `run ps` reads the record alone.\n\nA run whose step was refused (L5016) stays held; a\nresume on a host that can perform the step performs it live and continues from there.\n`journal` prints what an open pause asks beneath its step key, which is the address `answer` takes\nback. Checkpoint expiry rides the mediated timer writer, which the delivery daemon pumps on a live\nmesh; on a bare broker a pause still resolves, it just cannot expire.\n\n## What is on the wire\n\nThe run\'s wire footprint is [SPEC \xA714](../SPEC.md#14-workflow-runs-v05):\n\n| Thing | Where | What it is |\n| --- | --- | --- |\n| the run | `run.<endpoint>.<runId>` record | the resolved **pins** (seed, logical epoch, budgets, language version) on the immutable half; holder, lease and `journalHigh` on the status half |\n| the program | `program.<endpoint>.<runId>` record | the source the run was started from, verbatim, written once by the driver that pinned the run; what a resume reads and what a migration is measured against |\n| the step journal | `WFJ_<space>` stream, one subject per run | append-only, no age eviction, no Direct Get; every append fenced by the run subject\'s own sequence; takeover is replay-then-activate |\n| a checkpoint answer | `answer.<endpoint>.<token>.<answerId>` | the payload beside the one-use settle fact; the settle names the answer it accepted |\n| a notice | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>` | one bounded decision told to one agent, rendered ahead of its next turn |\n| a migration | `migration.<endpoint>.<runId>.<migrationId>` | the report and who applied it, keyed by the report\'s own digest |\n| the admission | `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>` | the caller the run was admitted for, its channel ceiling and its provenance; written once before the driver starts, and the store refuses a second write on the key |\n| a revocation | `revoked.v1.<endpoint>.<runId>` in the same store | who revoked the run and why; create-only, idempotent, permanent at the broker, read by every host before its next channel effect |\n\nA run\'s **driver** connects on a `run-driver` credential minted for one run and takeover\nattempt. It can append to its journal, use its replay durable, and write its own `run`, `program`,\n`notice` and `migration` records. It has no store point reads, checkpoint writes, chat consumers,\nor channel and membership registry grants.\n\nThe hosting process keeps a separate `run-mediator` connection for effects and reads. The driver\nreceives methods and data from that host; it never receives the mediator credential or connection.\nThe host checks the journal\'s current activation and step identity before dispatch, and checks\npause and wait authority again at each operation. Cancellation cleanup also admits losing steps\nnamed by a settled parent whose `cancel.issued` is still false. That permission allows cleanup;\nit cannot mint or rearm a cancelled pause. Wait acknowledgements consume host-held delivery\nreceipts. A recorded match can be reread only at its bound sequence and channel. A conclave\'s\nrecorded ownership flag must match its step-derived channel before registry writes or cleanup.\n\nThe mediator retains endpoint-wide checkpoint rights and stream-wide leader reads as trusted\nhost authority. Record reads exposed to the driver are restricted to its own run\'s keys. Reads\nthat decide writes remain leader-served. A read of the journal uses the run\'s filtered replay\ndurable, including the diagnostic for a journal with no run record. That durable is named after\nthe takeover, and an attempt reads it many times, so reads under one takeover run one at a time in\nthe hosting process and a replay removes a durable of its own name that an interrupted earlier read\nleft behind. A durable that survives a replay\'s own delete belongs to a reader the process cannot\naccount for, and reading its tail is refused.\n\nA served read uses a one-shot `run-operator` credential. An answer uses a read to find the open\npause, then a second credential pinned to that token for the answer and settlement.\n`cotal run --local` uses the same driver/mediator split. On an authenticated mesh it needs the\nlocally recorded space signer to mint both credentials; a single `--creds` file is refused.\nDirect library users supplying broker clients to `MeshHandler` are constructing a trusted effect\nhost. A hosted driver receives its closed effect interface instead.\n\nThis split confines broker credentials; it is not process isolation for injected host code.\nThe runtime and its effect host share the manager process. A run\'s channel reach is the admitted\nceiling ([SPEC \xA714.8](../SPEC.md#148-run-admission)): the starting caller\'s issued channel scope,\nrecorded once in `cotal_admission_<space>` under a per-run `run-admitter` credential the driver\nnever holds, and re-read by the host before every channel effect. Spawn and turn keep their own\ndelegated checks; `notify` writes agent-addressed notices and is not channel publication. Treat\n`run` as program-execution authority bounded by that ceiling, not as sandboxing of the program.\n\nA version-1 fork can replay its settled parent history through the host. Inherited checkpoint\nidentifiers carry no authority to read, rearm or claim the parent\'s pauses. New child effects use\nchild-derived identifiers. A fork is a new run and takes a new admission under the caller who\nforks it; the parent\'s ceiling is not inherited.\n\n\n## What ships today\n\nThe language, its validator, interpreter, simulator and dry run are `@cotal-ai/lang`\n(`packages/lang`), usable in-process with your own effect handler and with no broker: `validate(src)`,\nthen `run(src, { runId, handler })`, and `resume(src, journal, { runId, pins, handler })` to pick a\nrun up from its journal (the package README has the snippet, with `SimHandler` as the handler). That\nis the in-process route, yours to drive with your own handler; a run the driver starts executes on\nthe compiled engine, as the engine paragraph below says. The wire\nsubstrate of \xA714 (the `WFJ_<space>` stream, the five record kinds, the activation barrier, the\nper-run grants) is in `@cotal-ai/core`, and the run driver, journal store, migrate and fork are\n`@cotal-ai/runtime` (`implementations/runtime`). On the mesh handler, `sleep`, `checkpoint`,\n`wait(message(...))`, `wait(idle(...))`, `wait(down(...))`, `wait(replied(...))`, `notify`,\n`spawn`, `conclave`, `ask`, `monitor` and `turn` are durable.\n`spawn` is\nthe manager\'s spawn action submitted under the step\'s own identity: the goal binds under the step\'s\nrequest id, so a resumed run re-attaches to the same seat instead of allocating a second one, a\nfailed or refused spawn is catchable as L4002 with the manager\'s recorded reason, and a spawn on a\nrace branch that loses is despawned by the run\'s own cancellation sweep. `permits` are the budgets\nthis host meters: `turns`, how many turns the run may dispatch to the agent, and `wallClock`, a\nduration from the spawn after which no turn is admitted. The turn that would exceed one is the\ncatchable L4001 (kind `permit-turns` or `permit-wall-clock`; a deadline the remaining wall clock\ncannot hold counts as exceeding it), an adopted run counts the turns its journal recorded, and a\nbudget the host has no meter for, such as `tokens` or `spend`, is refused at the spawn rather than\naccepted and ignored. `supervise` is the restart policy this host asks the manager to enforce:\n`restarts`, how many in-window process deaths may come back under the same handle, and `window`,\nthe duration those deaths are counted in (default `10m`). The manager restarts the process in\nplace under the same name, lifecycle uid, persona, worktree and permits; `monitor` does not fire\nfor a restart, and `wait(down)` fires only when the seat is gone for good. Spending the budget\nretires the seat, and the next `turn` is the catchable L4002. A policy this host cannot enforce\n(an unknown key, a user-mode seat, or a runtime that cannot respawn a name in place) is refused\nat the spawn rather than accepted and ignored. `conclave` joins its\nmembers to a real channel as durable membership rows: the channel derives from the step\'s own\nrequest id when the program names none (a program-named channel is borrowed, never torn down, and\na membership that predates the conclave survives its close), each member handle resolves to its\nprincipal through the seat\'s own presence row (an absent member is catchable as L4002), and a\nconclave cancelled on a losing branch is released by the same cancellation sweep. `ask` parks one\ncheckpoint-plane pause per attempt, answered through `cotal run answer` as a checkpoint is, and\ntells the agent through the same relay `turn` uses: one relay per attempt under the attempt\'s own\ntoken, carrying the schema, the attempt count, the deadline and the previous refusal, which the\nseat\'s connector renders as the record wanted and the command that answers it. An ask addresses\nan agent the run spawned (anything else refuses before an attempt opens), a resumed attempt tells\nthe seat nothing twice, and a seat gone at the relay is L4002. On the pause itself:\nthe shorthand of the language reference \xA76.5 is enforced (an unreadable schema is L4022), a\nnon-conforming answer costs one attempt and its refusal reason is recorded on the entry for the\nanswerer to read, exhausted attempts (default one) are the catchable L4006, and so is the one\nabsolute deadline for the whole ask passing with no conforming record (its kind is `ask-deadline`).\n`checkpoint` binds what it asks on its own entry, so `cotal run journal` prints the question under\nthe step key an answer is addressed by while the pause is open: the address alone left whoever was\nasked reading the source to find out what "approve" meant. An `escalate` addressed to an agent this\nrun spawned is relayed to that seat through the same turn relay an `ask` uses, carrying the prompt\nand the token to answer under; a `to` naming anyone else is a person, and their pause stays the\none anybody can answer, with the addressee recorded and rendered beside the question.\n`monitor` registers interest in an agent, and the\nregistration is the journal entry itself, carrying the handle it registered: monitoring an agent\nthat is already dead succeeds, and the death is the wait\'s to observe. `wait(down(...))` observes\na monitored agent, and refuses one the run never performed `monitor` on. It reads the death off presence liveness, the\nsame witness a conclave join resolves members through: the value carries the handle, the reason\n(`lapsed` when nothing live holds the name any more, `superseded` when a live row holds it under\na different incarnation) and the time of observation, a wait that begins after the death resolves\nat once, and a timeout resolves null on one absolute deadline a resumed run re-attaches to.\n`turn` wakes one seat for one host turn through the manager as a pull-shaped relay: the run\nsubmits the turn under the step\'s own identity, the manager holds it as a goal pinned to the\nseat\'s incarnation, and the seat pulls it under its own reach ahead of its next host turn, so\nnothing is pushed into a session mid-thought. The payload the seat reads names the run and the\nstep and carries the rendered run context, plus any pending notices addressed to it, which the\nturn consumes. The seat yields through `cotal_yield` (`done`, `blocked`, or `handoff` with an\naddressee), and ending its host turn yields `done` for every turn it was shown. A `handoff` names\nanother seat the same run spawned: the next `turn` in the same scope to that seat records the\nlink, a handoff to a name the run never spawned is the catchable L4005, and one to a seat bound\nto a different worktree is L4004. The deadline elapsing before any yield is the catchable L4003:\nthe acceptance names the instant, the manager\'s goal-bound hold denies at it, and the run arms its\nown pause on that same instant, so either side outliving the other still converges on the same\nanswer. A seat that dies mid-turn is read off its own presence row by the run itself and is the\ncatchable L4002, and a death the manager marked on the deadline terminal reads the same way. Two\nturns on one seat, from two branches or from two runs, reach it one at a time: the language\ndispatches the second when the first settles, and the manager shows a seat the oldest unsettled\nturn alone. On an auth mesh the relay needs no extra grant: every spawned seat\'s baseline\ncredential carries its own pull and yield rows, the run driver\'s operator instrument carries the\nturn request, and the manager arms the deadline hold over its own serve grant and expires it\nitself once due. An accept the manager cannot finish is unwound to a failed terminal on the goal\nit bound, and a retry of that submission is refused naming the terminal rather than accepted a\nsecond time.\n`wait(replied(...))` observes those turns from another branch: a completed turn is a reply, and\nthe wait resolves with the observation record (the handle, the yield\'s status and note, the\nyield\'s own stamp). It reads as a level, the way `wait(down)` does: a reply that already exists\nresolves the wait at once, and two replies resolve to the latest by the yield\'s stamp. A denied\nor cancelled turn is never a reply, so an unanswered wait rides its own mediated timeout to\n`null`, and a handle the run never spawned or turned refuses loudly, since only this run\'s turns\nare observable. A turn the run itself ended without an accepted yield (its deadline, a\ncancellation, a refused handoff) is never a reply, whatever the seat yields to the relay later.\nA `spawn` may bind its agent to a **logical worktree** (`spawn("builder", { worktree: "wt-1" })`):\nthe handle carries the id, and the run enforces the one rule the language states about it: two\nagents never share a worktree concurrently. The validator rejects the literal case up front\n(L3022: two branches of one concurrent scope spawning into one literal worktree, named branch\nfunctions included), and the runtime guards the rest, computed ids included: a spawn claims its\ntree before it submits, so a second spawn into a tree held by a live seat or by a spawn still\nbringing one up is the catchable L4008, a spawn that ends without a handle gives the tree back,\nand the tree is reusable the moment a holder\'s presence row is gone, so a discharged race loser\nor a crashed seat releases its tree with no bookkeeping. A spawn the endpoint refuses at accept\nis the catchable L4000 (L4001 when the refusal is the endpoint\'s seat capacity), and one whose\nseat never came up is L4002. A refusal that states the command did not run is answered\nbefore it gets that far. In a space served by more than one manager the resolve and the invoke\nare separate trips through the same anycast queue, so a run\'s call can reach an instance it did\nnot resolve against, and that instance refuses ahead of any effect. The run drops its resolved\nhandle, re-describes and re-issues, for a bounded number of attempts; after them the refusal\nsurfaces as the effect\'s own failure and still states that nothing ran. A spawn that names a\n`placement` addresses one instance by name, so a refusal from it is that incarnation answering\nabout itself and is never re-issued. A turn handoff across worktrees is the L4004 described above. Recovery keeps these honest: a resumed run\nreseeds its roster, holders and handoff memos from its own journal, and the driver re-issues any\nrecorded-but-undischarged cancellation at adoption, before the engine performs a new step, so a\nloser a crash left alive does not keep its seat or its tree while the resumed run works on. The\nsame sweep withdraws a cancelled branch\'s undelivered notices: a notice waits on the run for its\naddressee\'s next turn, so a decision the run cancelled would otherwise arrive at an agent with\nnothing to distinguish it from one that stood.\n\nEvery effect the language defines performs on the mesh handler; nothing is refused as\nnot-yet-durable any more. The operator surface over the driver is `cotal run`; the section above has the verbs.\n\n**Two engines, and which one runs your program.** The tree-walker is language version `1` and the\ncompiled engine is version `2`, two languages rather than two speeds of one (`spec/cotal-lang.md`\n\xA78.4 lists what differs). The driver hosts both: **every run a driver starts is stamped `2` and\nexecuted by the compiled engine**. The program runs in its own locked-down worker thread with\nnothing in its global scope, while the effects and the durable journal stay in the driver\'s process,\nbridged over a message port. No socket or credential enters the isolate holding the program,\nand **every version-`1` record keeps replaying on the walker**, which is the walker\'s job. The\ndriver serves a declared set of versions, and a record whose version it does not serve is refused\nby name (**L5023**) with the run left untouched, instead of being replayed by whichever engine\nhappens to be present. Records do not cross between versions in either direction; the repair is to\nresume on the recorded version, or to fork.\n\n**The engine needs node 22 or newer** and refuses below it as `EngineUnavailable`, which is an\nimplementation limit and not a language error: it carries no `L` code, so there is nothing to look\nup in the catalog. It is a floor rather than a warning because the engine\'s frame plumbing rests on\n`AsyncLocalStorage`, and 22 is the lowest node it has been measured on. The walker has no such floor.\n'
     }
   ],
   "spec": {

package/dist/standalone.js

@@ -57905,7 +57905,7 @@ config(en_default());
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.50.0",
+  "version": "0.50.1",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -58004,7 +58004,7 @@ var DOCS_BUNDLE = {
       "title": "Connect Hermes (alpha)",
       "kind": "Guide (informative)",
       "summary": "Hermes (Nous Research) joins a Cotal mesh as a lateral peer, with the same shared cotal tool surface and delivery model as the other connectors.",
-      "body": "# Connect Hermes (alpha)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Hermes](https://nousresearch.com) (Nous Research) joins a Cotal mesh as a lateral peer, with the\nsame shared `cotal_*` tool surface and delivery model as the other connectors. The `hermes`\nconnector ships in the `cotal-ai` package, so no extra install of the connector itself.\n\n**Alpha** means it runs today (spawn it, it joins the mesh and takes turns) but with real\nconstraints, all verified below: it is **Unix-only**, needs an external Python toolchain you\nprovide (`uv` + `hermes-agent` on a supported version range), is **not** offered in the\n`cotal setup` picker, is **not** bundled in the container image (so no containerized Hermes, see\n[Deploy](deploy.md)), and does not support session resume.\n\n## Prerequisites\n\n- **Unix (macOS or Linux).** Windows is unsupported; the connector throws at launch (it uses an\n  AF_UNIX socket bridge and a Python sidecar).\n- **`uv` on your PATH.** The launcher runs `uv run --project <connector> hermes gateway run`, so\n  `uv` provisions the Python environment that provides the `hermes` CLI.\n- **`hermes-agent` in the supported `0.18` to `0.21` range.** The launcher asserts the installed\n  version at startup and fails loudly outside it (no silent degrade), because a different\n  major.minor can move the plugin/platform/hook API this connector targets. A plain `pip` or `uv`\n  resolve installs 0.19.0, the newest release on PyPI, which is inside the range. The 0.20.x and\n  0.21.x releases exist only on GitHub, and an install from git or the install script is also\n  inside the range. Below 0.18 the gateway does not send the reconnect signal the adapter needs,\n  so those versions are refused.\n\n## Spawn it\n\n```bash\ncotal spawn --agent hermes            # foreground in this terminal\nCOTAL_DEFAULT_AGENT=hermes cotal spawn # make it the default harness (an explicit --agent wins)\n```\n\nOr set `agent: hermes` in a team [manifest](manifest.md). Persona and role come from the agent\nfile like any connector (see [agent-files.md](agent-files.md)).\n\nHermes is **not** in the `cotal setup` picker (setup wires only Claude Code and OpenCode), so it\nis spawn-only: there is no setup step for it beyond having the toolchain above.\n\n## Choose a model\n\nHermes is model-agnostic; set any one provider's key in your environment. Model precedence\nmatches the other connectors: the `--model` flag, else the agent file's `model:`, else an ambient\n`HERMES_MODEL`. Hermes exposes no `cotal models` catalog (unlike OpenCode).\n\n## How it binds\n\nUnlike Claude Code or OpenCode (where the harness *is* the process), Hermes runs as a long-lived\n**gateway daemon** that spins up a fresh agent per inbound message. So the mesh connection can't\nlive inside a per-turn process; the connector's command is a small **launcher/supervisor** that\nowns the mesh endpoint for the gateway's whole life and runs `hermes gateway run` as its child.\n\n- The launcher bridges to an in-gateway **Python plugin** (the platform adapter, presence hooks,\n  and the `cotal_*` tools) over local AF_UNIX sockets.\n- It runs the gateway in an isolated `HERMES_HOME` profile (a temp dir), so your own `~/.hermes`\n  is never touched, with approvals off (a supervised agent has no human at the TUI to approve).\n  To put your own Hermes on the mesh instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n- The persona is written as Hermes' `SOUL.md` (its system-prompt file), the one place a system\n  prompt can be set.\n- Quiet-channel ambient is skipped by the automatic bridge pump, even when an older quiet item is\n  ahead of a DM. `cotal_inbox` explicitly surfaces and clears quiet ambient without consuming the\n  connector-owned automatic queue; quiet `@mention`s remain automatic.\n\nThe shared tool surface and inbound-message model are documented once, for all connectors: see\n[mcp-tools.md](mcp-tools.md) and [connect-claude.md](connect-claude.md).\n\n## Use your own Hermes profile\n\nThe isolated profile above is the right default for a disposable seat, but it cannot serve the\nother reason to run Hermes: joining the Hermes you already have, with its credentials and\nintegrations. Those live in your real profile, so a seat on a temp `HERMES_HOME` cannot reach your\nnotification path.\n\nSet `COTAL_HERMES_ADOPT_HOME` to your profile directory to run the gateway there instead:\n\n```bash\nexport COTAL_HERMES_ADOPT_HOME=\"$HOME/.hermes\"\ncotal spawn --agent hermes\n```\n\nThe launcher then installs only its own `plugins/cotal` directory, refreshed on each launch. It\nreads your `config.yaml` and never writes it, and it leaves your `SOUL.md` alone. Enabling the\nplugin stays your decision, so add this to your `config.yaml` first:\n\n```yaml\nplugins:\n  enabled: [cotal]\ngateway:\n  platforms:\n    cotal:\n      enabled: true\n```\n\nWithout those two settings the launch fails and tells you what to add. Two more consequences\nfollow from not writing your config. Your approval settings stay as you left them, so a profile\nthat prompts for approvals will still prompt, with no human at the TUI to answer. An agent file\npersona is refused rather than applied, because applying it means overwriting your `SOUL.md`.\n\n## How presence follows the turn\n\nThe hooks map Hermes's lifecycle onto presence: `pre_llm_call` and `pre_tool_call` write `working`,\n`approval_wait` writes `waiting`, `post_llm_call` and `on_session_end` write `idle`. That last\nworking-to-idle transition is the turn boundary the run relay reads (a surfaced run turn yields\n`done` there), so `gateway_startup` and `on_session_start` write their `idle` through a path that\nmoves presence and nothing else: an adapter reconnect or a session start that lands mid-turn is a\nlifecycle event, and treating it as an ending would yield work the model had not finished.\n\n## Limits\n\n- **Unix-only** (no Windows).\n- **No session resume**: `cotal spawn --resume` throws.\n- **Not containerized**: the [deploy](deploy.md) image bundles only Claude Code and OpenCode (no\n  `uv`/`hermes-agent`), so there is no containerized Hermes today.\n- **Brings its own toolchain**: you supply `uv` and a `hermes-agent` inside the supported range.\n- **No initial prompt**: `cotal spawn --prompt` throws, because the gateway has no first-turn\n  carrier wired, so a seat cannot be given its opening instruction at spawn.\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md) \xB7 [Connect pi](connect-pi.md)\n"
+      "body": "# Connect Hermes (alpha)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Hermes](https://nousresearch.com) (Nous Research) joins a Cotal mesh as a lateral peer, with the\nsame shared `cotal_*` tool surface and delivery model as the other connectors. The `hermes`\nconnector ships in the `cotal-ai` package, so no extra install of the connector itself.\n\n**Alpha** means it runs today (spawn it, it joins the mesh and takes turns) but with real\nconstraints, all verified below: it is **Unix-only**, needs an external Python toolchain you\nprovide (`uv` + `hermes-agent` on a supported version range), is **not** offered in the\n`cotal setup` picker, is **not** bundled in the container image (so no containerized Hermes, see\n[Deploy](deploy.md)), and does not support session resume.\n\n## Prerequisites\n\n- **Unix (macOS or Linux).** Windows is unsupported; the connector throws at launch (it uses an\n  AF_UNIX socket bridge and a Python sidecar).\n- **`uv` on your PATH.** The launcher runs `uv run --project <connector> hermes gateway run`, so\n  `uv` provisions the Python environment that provides the `hermes` CLI.\n- **`hermes-agent` in the supported `0.18` to `0.21` range.** The launcher asserts the installed\n  version at startup and fails loudly outside it (no silent degrade), because a different\n  major.minor can move the plugin/platform/hook API this connector targets. A plain `pip` or `uv`\n  resolve installs 0.19.0, the newest release on PyPI, which is inside the range. The 0.20.x and\n  0.21.x releases exist only on GitHub, and an install from git or the install script is also\n  inside the range. Below 0.18 the gateway does not send the reconnect signal the adapter needs,\n  so those versions are refused.\n\n## Spawn it\n\n```bash\ncotal spawn --agent hermes            # foreground in this terminal\nCOTAL_DEFAULT_AGENT=hermes cotal spawn # make it the default harness (an explicit --agent wins)\n```\n\nOr set `agent: hermes` in a team [manifest](manifest.md). Persona and role come from the agent\nfile like any connector (see [agent-files.md](agent-files.md)).\n\nHermes is **not** in the `cotal setup` picker (setup wires only Claude Code and OpenCode), so it\nis spawn-only: there is no setup step for it beyond having the toolchain above.\n\n## Choose a model\n\nHermes is model-agnostic; set any one provider's key in your environment. Model precedence\nmatches the other connectors: the `--model` flag, else the agent file's `model:`, else an ambient\n`HERMES_MODEL`. Hermes exposes no `cotal models` catalog (unlike OpenCode).\n\nWith none of those set, the launch is refused. The managed profile does not read `~/.hermes`, so a\nmodel configured there is not used, and without a model Hermes would choose one of its own over a\nprovider you may have no key for. The refusal names the three ways to set a model. To run on your\nown profile instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n\n## How it binds\n\nUnlike Claude Code or OpenCode (where the harness *is* the process), Hermes runs as a long-lived\n**gateway daemon** that spins up a fresh agent per inbound message. So the mesh connection can't\nlive inside a per-turn process; the connector's command is a small **launcher/supervisor** that\nowns the mesh endpoint for the gateway's whole life and runs `hermes gateway run` as its child.\n\n- The launcher bridges to an in-gateway **Python plugin** (the platform adapter, presence hooks,\n  and the `cotal_*` tools) over local AF_UNIX sockets.\n- It runs the gateway in an isolated `HERMES_HOME` profile (a temp dir), so your own `~/.hermes`\n  is never touched, with approvals off (a supervised agent has no human at the TUI to approve).\n  To put your own Hermes on the mesh instead, see [Use your own Hermes profile](#use-your-own-hermes-profile).\n- The persona is written as Hermes' `SOUL.md` (its system-prompt file), the one place a system\n  prompt can be set.\n- Quiet-channel ambient is skipped by the automatic bridge pump, even when an older quiet item is\n  ahead of a DM. `cotal_inbox` explicitly surfaces and clears quiet ambient without consuming the\n  connector-owned automatic queue; quiet `@mention`s remain automatic.\n\nThe shared tool surface and inbound-message model are documented once, for all connectors: see\n[mcp-tools.md](mcp-tools.md) and [connect-claude.md](connect-claude.md).\n\n## Use your own Hermes profile\n\nThe isolated profile above is the right default for a disposable seat, but it cannot serve the\nother reason to run Hermes: joining the Hermes you already have, with its credentials and\nintegrations. Those live in your real profile, so a seat on a temp `HERMES_HOME` cannot reach your\nnotification path.\n\nSet `COTAL_HERMES_ADOPT_HOME` to your profile directory to run the gateway there instead:\n\n```bash\nexport COTAL_HERMES_ADOPT_HOME=\"$HOME/.hermes\"\ncotal spawn --agent hermes\n```\n\nThe launcher then installs only its own `plugins/cotal` directory, refreshed on each launch. It\nreads your `config.yaml` and never writes it, and it leaves your `SOUL.md` alone. Enabling the\nplugin stays your decision, so add this to your `config.yaml` first:\n\n```yaml\nplugins:\n  enabled: [cotal]\ngateway:\n  platforms:\n    cotal:\n      enabled: true\n```\n\nWithout those two settings the launch fails and tells you what to add. Two more consequences\nfollow from not writing your config. Your approval settings stay as you left them, so a profile\nthat prompts for approvals will still prompt, with no human at the TUI to answer. An agent file\npersona is refused rather than applied, because applying it means overwriting your `SOUL.md`.\n\n## How presence follows the turn\n\nThe hooks map Hermes's lifecycle onto presence: `pre_llm_call` and `pre_tool_call` write `working`,\n`approval_wait` writes `waiting`, `post_llm_call` and `on_session_end` write `idle`. That last\nworking-to-idle transition is the turn boundary the run relay reads (a surfaced run turn yields\n`done` there), so `gateway_startup` and `on_session_start` write their `idle` through a path that\nmoves presence and nothing else: an adapter reconnect or a session start that lands mid-turn is a\nlifecycle event, and treating it as an ending would yield work the model had not finished.\n\n## Limits\n\n- **Unix-only** (no Windows).\n- **No session resume**: `cotal spawn --resume` throws.\n- **Not containerized**: the [deploy](deploy.md) image bundles only Claude Code and OpenCode (no\n  `uv`/`hermes-agent`), so there is no containerized Hermes today.\n- **Brings its own toolchain**: you supply `uv` and a `hermes-agent` inside the supported range.\n- **No initial prompt**: `cotal spawn --prompt` throws, because the gateway has no first-turn\n  carrier wired, so a seat cannot be given its opening instruction at spawn.\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md) \xB7 [Connect pi](connect-pi.md)\n"
     },
     {
       "slug": "connect-jcode",
@@ -58186,7 +58186,7 @@ var DOCS_BUNDLE = {
       "title": "Workflow runs",
       "kind": "Concept (informative)",
       "summary": "A workflow run is a program that coordinates agents over hours or days and survives the process that started it.",
-      "body": '# Workflow runs\n\n> **Concept** (informative) \xB7 **For:** people writing a durable multi-agent workflow, and implementers hosting one \xB7 **Normative:** [SPEC \xA714](../SPEC.md#14-workflow-runs-v05) and the language reference [`spec/cotal-lang.md`](../spec/cotal-lang.md)\n\nA **workflow run** is a program that coordinates agents over hours or days and survives the\nprocess that started it. The program is written in **Cotal Lang**, a small subset of JavaScript in\nwhich every interaction with the world is one of a dozen **effects** (`spawn`, `turn`, `ask`,\n`checkpoint`, `sleep`, `wait`, `notify`, `monitor`, and the four concurrency scopes) and everything\nelse is ordinary, pure JavaScript. Every effect is written into the run\'s **step journal** before\nit is performed and settled after, keyed by where in the program it happened rather than by when,\nso a run that dies is resumed on any host by **re-running the program from the top** with recorded\neffects returning their recorded results. Nothing about the interpreter is ever serialized: the\njournal and the program are the whole state.\n\n## A first program\n\n```js\nconst planner = await spawn("planner")\nconst builder = await spawn("builder", { worktree: "wt-1" })\n\nconst plan = await ask(planner, { name: "plan", schema: { steps: "array" } })\nconst ok = await checkpoint("approve-plan", "Approve the plan?", { timeout: "4h", onExpiry: "proceed" })\nif (ok.status !== "resolved") {\n  await notify([planner], { decision: "approve-plan", outcome: "expired" })\n}\n\nconst r = await turn(builder, { name: "build", deadline: "30m" })\nif (r.status === "blocked") {\n  await turn(planner, { name: "unblock" })\n}\n\nconst outcome = await race({\n  reply: () => wait(replied(builder), { timeout: "20m" }),\n  giveUp: () => sleep("1h"),\n}, { name: "await-or-move-on" })\nlog("outcome", outcome.index)\n```\n\nRead it as the flowchart it is. `spawn` brings agents in; `ask` is the narrow case where the\nprogram itself needs a value (`schema` is a record the program hands the handler unchanged; the\nlanguage hashes it and gives it no meaning, and the handlers in this repository enforce it as the\nshorthand of the language reference \xA76.5);\n`checkpoint` is a durable pause a human resolves from anywhere, raced against a durable timer; `turn`\nwakes an agent for one turn and returns how it yielded; `race` runs two branches and keeps the one\nwhose recorded clock is earliest. Agents talk to each other in channels as they always do; the\nprogram never speaks in a channel, and the one thing it can put in front of an agent (`notify`) is a\nbounded decision record, not prose.\n\n## The mental model\n\n- **Pure code is JavaScript.** Loops, records, arrays, closures, template literals, destructuring,\n  `try`/`catch`, arithmetic, `switch`, compound assignment, optional chaining, spread and rest: what\n  you would write anyway, with the parts that hide effects or make meaning depend on the host removed\n  (`class`, `this`, `new`, `for...in`, `==`, labels, regex literals, `Math`/`Date`/`JSON`, promises,\n  generators). Every refusal names its code and the edit that fixes it. The builtins are a short list\n  (`keys`, `map`, `sort`, `json.stringify`, `now()`, `random()`), and arrays, strings and numbers\n  answer their usual methods (`xs.map`, `s.trim()`, `n.toFixed()`) and nothing outside that table.\n  Records and arrays you build are yours to change until they cross an effect boundary; a member you\n  do not own, a host prototype, or a value another branch built is refused with a code, never a\n  surprise.\n- **Every effect is journalled and hashed.** A step is keyed `(scope path, kind, name, occurrence)`\n  and its inputs are hashed. Reorder your program, add a step, rename a variable: recorded steps\n  still match. Change what a step asks (a checkpoint\'s prompt, a sleep\'s duration, a turn\'s\n  deadline) and the resume stops with a **divergence** naming the step, rather than replaying an\n  answer to a question the program no longer asks.\n- **Concurrency is visible.** `parallel`, `race`, `fanOut` and `conclave` are the only ways to do\n  two things at once, each branch gets its own journal namespace, and the scope writes its own\n  entry saying how it settled: which arm won a race is a recorded fact, decided by the arms\'\n  recorded clocks and declaration order, never by a scheduler. A branch may not write to anything\n  declared outside it; return the value and read it out of the scope\'s result.\n- **Time and randomness are tamed.** `now()` is the branch\'s run clock, the end of the last effect\n  it awaited; `random()` is a seeded stream derived per scope. Both replay identically.\n- **Values freeze at the boundary.** What crossed into or out of an effect is what the journal\n  recorded, and it cannot change afterwards; build a new value.\n- **The journal is the debugger.** Every entry carries its key, its inputs\' hash, its outcome and\n  its timing, and every error is in the program\'s own coordinates. A run can be **simulated** with a\n  scripted handler and **dry-run** to a plan before it touches an agent. The simulator is\n  discrete-event: timed effects park at their wake times and are delivered in wake order on one\n  virtual clock, so concurrent branches accumulate the durations they wrote and a simulated `race`\n  is decided by the same rule a live handler produces (least recorded clock, ties by declaration\n  order). A `sleep("1m")` arm beats a `sleep("1h")` arm whatever their declaration order.\n\nFull rules, with every code: [`spec/cotal-lang.md`](../spec/cotal-lang.md).\n\n## Continuing a run\n\n**Resume** is re-execution: the driver replays the journal, the program runs from the top, recorded\nsteps return instantly, and the first unrecorded step is performed live. It refuses a journal that\nbelongs to another run, a pin that differs from the recorded ones, and a different language version.\n\n**Migrate** moves a run onto edited source. A dry walk of the new program over the recorded journal\nfinds every recorded step the edit changed (a divergence) and every one it no longer reaches (an\norphan), and the orphan table says what each means: a removed `sleep` is nothing, a removed `turn`\nalready happened, a removed `spawn` is a live agent you must adopt or release, a removed resolved\n`checkpoint` is a human decision you must explicitly discard. The decision is filed as a\n`migration` record with the actor\'s name on it. An adopted seat (`--adopt <name>#<uid>`) goes to\nthe edited program\'s next `spawn` of that persona, which returns the recorded handle and mints\nnothing, so the agent keeps its identity, its worktree and its turn history across the edit. A\nreleased seat (`--release <name>#<uid>`) is despawned when the migration commits, through the same\ndischarge a cancelled branch\'s seat leaves by, so the record never claims a release nothing did.\nThe spawn that adopts a seat binds the orphaned spawn\'s goal as its own, so a resume of that step\nreads the same seat back and a cancellation of it despawns the seat it holds.\n\n**Fork** starts a new run from a named step of an old one, copying the prefix under the parent\'s\npins (seed included, so the copied history\'s pure draws are the same draws). The child is a new run\nunder a new id whose record names the parent and the cut step (`forkedFrom`); the parent is\nuntouched. A spawn inside the copied prefix is honoured by its `onFork`: `"adopt"` copies it, and\nthe child shares the parent\'s agent (the manager shows that seat one turn at a time across both\nruns); `"respawn"`, the default, would mint a fresh identity the copied turns do not address, so\nthis host refuses that cut (L5019) rather than rewriting the parent\'s history.\n\nFork planning and migration inspection use the recorded language version. Version-1 history uses\nthe interpreter. Version-2 history is inspected inside a locked-down worker with a read-only\njournal, without a live effect handler or durable store. Inspection stops before the fork\'s cut\nstep or any effect that needs new work. Program catch and finally blocks cannot extend the cut.\nThe recorded pins are preserved.\n\n## From an agent session\n\nFresh `cotal setup` defaults declare `capabilities: [spawn, run]`. On a static-auth mesh,\nthat exposes `cotal_run` alongside the teammate tools. The manager must be running.\nRead `cotal_docs` pages `lang-card` and `workflows`, then try:\n\n```json\n{\n  "verb": "start",\n  "source": "await sleep(\\"1s\\", { name: \\"first-run\\" });",\n  "file": "first-run.cotal.js"\n}\n```\n\nPass this object to `cotal_run`. `source` contains the program; `file` only labels diagnostics\nand reads nothing from disk. The response returns a run ID before execution finishes. Call\n`cotal_run` with `verb: "status"` and that `runId` to inspect the state and step journal.\nA completed timer records its sleep step as `ok`.\n\n### If `cotal_run` is missing\n\n1. Call `cotal_orientation` and check the connector version, capabilities and tool list.\n   Upgrade an older installation using the [upgrade guide](https://github.com/Cotal-AI/Cotal/blob/main/docs/UPGRADING.md).\n2. Have the operator add `run` to the persona\'s existing `capabilities` list, for example\n   `capabilities: [spawn, run]`. `spawn` alone does not expose `cotal_run`. Setup leaves existing\n   personas unchanged except for its [byte-exact legacy migration](getting-started.md).\n   Peer persona-definition tools cannot grant capabilities.\n3. Relaunch the agent through the manager from the updated persona so it receives newly issued\n   credentials and a fresh connector configuration. Editing the file or reconnecting with the\n   old credential does not grant new broker permissions. If the launch sets `COTAL_CAPABILITIES`,\n   update that override too; it takes precedence over the file.\n4. Check `cotal_orientation` again, then call `cotal_run` with `verb: "ps"` before starting work.\n\nTool visibility alone does not establish execution support. Hosted runs currently require\nstatic authentication with issued caller authority. Open meshes can expose the tool but refuse\nhosted runs; user-auth meshes also refuse them. A legacy credential without issued authority\nmust be replaced through the current issuance path before it can start a hosted run.\n\n## Operating a run\n\nThe manager hosts runs. `cotal run start` hands the program to the manager of the resolved mesh\n(the usual `--space` / `--server` / `--creds` flags), which validates it, mints the run id, drives\nit in its own process, and answers with the id once the run is recorded. The terminal is free the\nmoment the id prints; the run continues on the manager through every pause, and a manager restart\ntakes back every run it had recorded running, from the journal, under the next epoch. `resume`\nnames a run the manager recorded and is refused while the manager is already driving it. `ps` and\n`journal` read; `answer` resolves an open checkpoint, or an open `ask` attempt, from any terminal\nor agent that holds the `run` capability.\n\n```bash\ncotal run start --file build.cotal.js                   # the manager starts it; the minted id is printed\ncotal run ps                                            # list run records: state, holder, lineage\ncotal run journal run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # print the durable step journal\ncotal run resume run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # the manager takes the run back\ncotal run answer run-3f2a90c41b7e0d5a6c884e19b02df4a1 "/checkpoint:approve#0" --value \'"yes"\'\n```\n\nA program that does not validate is refused before anything is recorded, with every problem in the\nanswer as the validator would print it. The driver records the program beside the run, so `resume`\ntakes the run id alone and the manager reads the source back; an edited program is a `migrate` or a\n`fork`, never a resume. An answer is recorded under the answerer the manager knows from the\ncaller\'s credential: a managed agent by its name, anyone else by their principal. The request\ncarries no name. An agent with `capabilities: [run]` has the same five verbs as the `cotal_run`\ntool ([MCP tools](mcp-tools.md)), so a program can be written and started from inside a session.\nA `start` or `resume` answers once the run\'s record is written, within a bounded wait; a manager\nthat is still taking back a predecessor\'s runs at boot refuses both with `unavailable`, and a\nretry a moment later is the whole remedy.\n\n`--local` drives the run in this process instead: `start`, `resume` and `answer` exit when the\ndrive settles, `--by <who>` names the answerer, and `cotal run resume <runId> --local --file\n<program>` is how a run with no recorded program is continued. On a static mesh the local drive\nmints the run\'s own credential from the folder\'s trust material, so it runs from the mesh\'s\nproject folder. A local start also names the run\'s channel ceiling itself:\n`--admit-read <channels> --admit-publish <channels>`, comma-separated patterns or `none`, both\nrequired. The record it writes says an operator admitted the run and why, and the host checks\nit the same way it checks a hosted admission. A user-auth mesh runs no programs yet, hosted or\nlocal: the manager refuses the family by name, since a hosted run\'s seats would be spawned under\nthe static owner, which a user mesh refuses, and a user bearer holds no run rows. An open mesh\nhosts none either, since it issues no caller authority to admit a run under.\n\nA hosted run is **admitted** under the caller that started it. The caller\'s credential is an\nissuance ([identity and auth](identity-and-auth.md#issued-authority)): its requests ride a\nversioned rail that carries the credential\'s generation, and the manager resolves that\ngeneration\'s recorded permission ceiling and writes it beside the run before the driver starts.\nThat ceiling, the caller\'s own channel scope as it was issued, is what the run may read and post\nin channels; the manager\'s own reach never stands in for it. A request from a credential minted\nwithout an issuance is refused with `permission-denied` and a detail naming the caller. A run\nwhose caller had no channels can still sleep, checkpoint and turn agents; its `wait` on a channel\nis refused at the effect.\n\n`cotal run revoke <runId> --local --by <who> --reason <text>` writes the run\'s revocation marker\nfrom the project folder. The admission itself is never rewritten. Every host reads the marker\nbefore its next channel effect, so an open `wait` refuses at its next poll, and no resume,\ntakeover or manager restart continues the run. Revoking twice is not an error, and the first\nreason stands. A run whose admission is missing or revoked is left parked by the manager\'s boot\nreconcile, named in its log.\n\nA run whose step was refused (L5016) stays held; a\nresume on a host that can perform the step performs it live and continues from there.\n`journal` prints what an open pause asks beneath its step key, which is the address `answer` takes\nback. Checkpoint expiry rides the mediated timer writer, which the delivery daemon pumps on a live\nmesh; on a bare broker a pause still resolves, it just cannot expire.\n\n## What is on the wire\n\nThe run\'s wire footprint is [SPEC \xA714](../SPEC.md#14-workflow-runs-v05):\n\n| Thing | Where | What it is |\n| --- | --- | --- |\n| the run | `run.<endpoint>.<runId>` record | the resolved **pins** (seed, logical epoch, budgets, language version) on the immutable half; holder, lease and `journalHigh` on the status half |\n| the program | `program.<endpoint>.<runId>` record | the source the run was started from, verbatim, written once by the driver that pinned the run; what a resume reads and what a migration is measured against |\n| the step journal | `WFJ_<space>` stream, one subject per run | append-only, no age eviction, no Direct Get; every append fenced by the run subject\'s own sequence; takeover is replay-then-activate |\n| a checkpoint answer | `answer.<endpoint>.<token>.<answerId>` | the payload beside the one-use settle fact; the settle names the answer it accepted |\n| a notice | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>` | one bounded decision told to one agent, rendered ahead of its next turn |\n| a migration | `migration.<endpoint>.<runId>.<migrationId>` | the report and who applied it, keyed by the report\'s own digest |\n| the admission | `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>` | the caller the run was admitted for, its channel ceiling and its provenance; written once before the driver starts, and the store refuses a second write on the key |\n| a revocation | `revoked.v1.<endpoint>.<runId>` in the same store | who revoked the run and why; create-only, idempotent, permanent at the broker, read by every host before its next channel effect |\n\nA run\'s **driver** connects on a `run-driver` credential minted for one run and takeover\nattempt. It can append to its journal, use its replay durable, and write its own `run`, `program`,\n`notice` and `migration` records. It has no store point reads, checkpoint writes, chat consumers,\nor channel and membership registry grants.\n\nThe hosting process keeps a separate `run-mediator` connection for effects and reads. The driver\nreceives methods and data from that host; it never receives the mediator credential or connection.\nThe host checks the journal\'s current activation and step identity before dispatch, and checks\npause and wait authority again at each operation. Cancellation cleanup also admits losing steps\nnamed by a settled parent whose `cancel.issued` is still false. That permission allows cleanup;\nit cannot mint or rearm a cancelled pause. Wait acknowledgements consume host-held delivery\nreceipts. A recorded match can be reread only at its bound sequence and channel. A conclave\'s\nrecorded ownership flag must match its step-derived channel before registry writes or cleanup.\n\nThe mediator retains endpoint-wide checkpoint rights and stream-wide leader reads as trusted\nhost authority. Record reads exposed to the driver are restricted to its own run\'s keys. Reads\nthat decide writes remain leader-served. A read of the journal uses the run\'s filtered replay\ndurable, including the diagnostic for a journal with no run record. That durable is named after\nthe takeover, and an attempt reads it many times, so reads under one takeover run one at a time in\nthe hosting process and a replay removes a durable of its own name that an interrupted earlier read\nleft behind. A durable that survives a replay\'s own delete belongs to a reader the process cannot\naccount for, and reading its tail is refused.\n\nA served read uses a one-shot `run-operator` credential. An answer uses a read to find the open\npause, then a second credential pinned to that token for the answer and settlement.\n`cotal run --local` uses the same driver/mediator split. On an authenticated mesh it needs the\nlocally recorded space signer to mint both credentials; a single `--creds` file is refused.\nDirect library users supplying broker clients to `MeshHandler` are constructing a trusted effect\nhost. A hosted driver receives its closed effect interface instead.\n\nThis split confines broker credentials; it is not process isolation for injected host code.\nThe runtime and its effect host share the manager process. A run\'s channel reach is the admitted\nceiling ([SPEC \xA714.8](../SPEC.md#148-run-admission)): the starting caller\'s issued channel scope,\nrecorded once in `cotal_admission_<space>` under a per-run `run-admitter` credential the driver\nnever holds, and re-read by the host before every channel effect. Spawn and turn keep their own\ndelegated checks; `notify` writes agent-addressed notices and is not channel publication. Treat\n`run` as program-execution authority bounded by that ceiling, not as sandboxing of the program.\n\nA version-1 fork can replay its settled parent history through the host. Inherited checkpoint\nidentifiers carry no authority to read, rearm or claim the parent\'s pauses. New child effects use\nchild-derived identifiers. A fork is a new run and takes a new admission under the caller who\nforks it; the parent\'s ceiling is not inherited.\n\n\n## What ships today\n\nThe language, its validator, interpreter, simulator and dry run are `@cotal-ai/lang`\n(`packages/lang`), usable in-process with your own effect handler and with no broker: `validate(src)`,\nthen `run(src, { runId, handler })`, and `resume(src, journal, { runId, pins, handler })` to pick a\nrun up from its journal (the package README has the snippet, with `SimHandler` as the handler). That\nis the in-process route, yours to drive with your own handler; a run the driver starts executes on\nthe compiled engine, as the engine paragraph below says. The wire\nsubstrate of \xA714 (the `WFJ_<space>` stream, the five record kinds, the activation barrier, the\nper-run grants) is in `@cotal-ai/core`, and the run driver, journal store, migrate and fork are\n`@cotal-ai/runtime` (`implementations/runtime`). On the mesh handler, `sleep`, `checkpoint`,\n`wait(message(...))`, `wait(idle(...))`, `wait(down(...))`, `wait(replied(...))`, `notify`,\n`spawn`, `conclave`, `ask`, `monitor` and `turn` are durable.\n`spawn` is\nthe manager\'s spawn action submitted under the step\'s own identity: the goal binds under the step\'s\nrequest id, so a resumed run re-attaches to the same seat instead of allocating a second one, a\nfailed or refused spawn is catchable as L4002 with the manager\'s recorded reason, and a spawn on a\nrace branch that loses is despawned by the run\'s own cancellation sweep. `permits` are the budgets\nthis host meters: `turns`, how many turns the run may dispatch to the agent, and `wallClock`, a\nduration from the spawn after which no turn is admitted. The turn that would exceed one is the\ncatchable L4001 (kind `permit-turns` or `permit-wall-clock`; a deadline the remaining wall clock\ncannot hold counts as exceeding it), an adopted run counts the turns its journal recorded, and a\nbudget the host has no meter for, such as `tokens` or `spend`, is refused at the spawn rather than\naccepted and ignored. `supervise` is the restart policy this host asks the manager to enforce:\n`restarts`, how many in-window process deaths may come back under the same handle, and `window`,\nthe duration those deaths are counted in (default `10m`). The manager restarts the process in\nplace under the same name, lifecycle uid, persona, worktree and permits; `monitor` does not fire\nfor a restart, and `wait(down)` fires only when the seat is gone for good. Spending the budget\nretires the seat, and the next `turn` is the catchable L4002. A policy this host cannot enforce\n(an unknown key, a user-mode seat, or a runtime that cannot respawn a name in place) is refused\nat the spawn rather than accepted and ignored. `conclave` joins its\nmembers to a real channel as durable membership rows: the channel derives from the step\'s own\nrequest id when the program names none (a program-named channel is borrowed, never torn down, and\na membership that predates the conclave survives its close), each member handle resolves to its\nprincipal through the seat\'s own presence row (an absent member is catchable as L4002), and a\nconclave cancelled on a losing branch is released by the same cancellation sweep. `ask` parks one\ncheckpoint-plane pause per attempt, answered through `cotal run answer` as a checkpoint is, and\ntells the agent through the same relay `turn` uses: one relay per attempt under the attempt\'s own\ntoken, carrying the schema, the attempt count, the deadline and the previous refusal, which the\nseat\'s connector renders as the record wanted and the command that answers it. An ask addresses\nan agent the run spawned (anything else refuses before an attempt opens), a resumed attempt tells\nthe seat nothing twice, and a seat gone at the relay is L4002. On the pause itself:\nthe shorthand of the language reference \xA76.5 is enforced (an unreadable schema is L4022), a\nnon-conforming answer costs one attempt and its refusal reason is recorded on the entry for the\nanswerer to read, exhausted attempts (default one) are the catchable L4006, and so is the one\nabsolute deadline for the whole ask passing with no conforming record (its kind is `ask-deadline`).\n`checkpoint` binds what it asks on its own entry, so `cotal run journal` prints the question under\nthe step key an answer is addressed by while the pause is open: the address alone left whoever was\nasked reading the source to find out what "approve" meant. An `escalate` addressed to an agent this\nrun spawned is relayed to that seat through the same turn relay an `ask` uses, carrying the prompt\nand the token to answer under; a `to` naming anyone else is a person, and their pause stays the\none anybody can answer, with the addressee recorded and rendered beside the question.\n`monitor` registers interest in an agent, and the\nregistration is the journal entry itself, carrying the handle it registered: monitoring an agent\nthat is already dead succeeds, and the death is the wait\'s to observe. `wait(down(...))` observes\na monitored agent, and refuses one the run never performed `monitor` on. It reads the death off presence liveness, the\nsame witness a conclave join resolves members through: the value carries the handle, the reason\n(`lapsed` when nothing live holds the name any more, `superseded` when a live row holds it under\na different incarnation) and the time of observation, a wait that begins after the death resolves\nat once, and a timeout resolves null on one absolute deadline a resumed run re-attaches to.\n`turn` wakes one seat for one host turn through the manager as a pull-shaped relay: the run\nsubmits the turn under the step\'s own identity, the manager holds it as a goal pinned to the\nseat\'s incarnation, and the seat pulls it under its own reach ahead of its next host turn, so\nnothing is pushed into a session mid-thought. The payload the seat reads names the run and the\nstep and carries the rendered run context, plus any pending notices addressed to it, which the\nturn consumes. The seat yields through `cotal_yield` (`done`, `blocked`, or `handoff` with an\naddressee), and ending its host turn yields `done` for every turn it was shown. A `handoff` names\nanother seat the same run spawned: the next `turn` in the same scope to that seat records the\nlink, a handoff to a name the run never spawned is the catchable L4005, and one to a seat bound\nto a different worktree is L4004. The deadline elapsing before any yield is the catchable L4003:\nthe acceptance names the instant, the manager\'s goal-bound hold denies at it, and the run arms its\nown pause on that same instant, so either side outliving the other still converges on the same\nanswer. A seat that dies mid-turn is read off its own presence row by the run itself and is the\ncatchable L4002, and a death the manager marked on the deadline terminal reads the same way. Two\nturns on one seat, from two branches or from two runs, reach it one at a time: the language\ndispatches the second when the first settles, and the manager shows a seat the oldest unsettled\nturn alone. On an auth mesh the relay needs no extra grant: every spawned seat\'s baseline\ncredential carries its own pull and yield rows, the run driver\'s operator instrument carries the\nturn request, and the manager arms the deadline hold over its own serve grant and expires it\nitself once due. An accept the manager cannot finish is unwound to a failed terminal on the goal\nit bound, and a retry of that submission is refused naming the terminal rather than accepted a\nsecond time.\n`wait(replied(...))` observes those turns from another branch: a completed turn is a reply, and\nthe wait resolves with the observation record (the handle, the yield\'s status and note, the\nyield\'s own stamp). It reads as a level, the way `wait(down)` does: a reply that already exists\nresolves the wait at once, and two replies resolve to the latest by the yield\'s stamp. A denied\nor cancelled turn is never a reply, so an unanswered wait rides its own mediated timeout to\n`null`, and a handle the run never spawned or turned refuses loudly, since only this run\'s turns\nare observable. A turn the run itself ended without an accepted yield (its deadline, a\ncancellation, a refused handoff) is never a reply, whatever the seat yields to the relay later.\nA `spawn` may bind its agent to a **logical worktree** (`spawn("builder", { worktree: "wt-1" })`):\nthe handle carries the id, and the run enforces the one rule the language states about it: two\nagents never share a worktree concurrently. The validator rejects the literal case up front\n(L3022: two branches of one concurrent scope spawning into one literal worktree, named branch\nfunctions included), and the runtime guards the rest, computed ids included: a spawn claims its\ntree before it submits, so a second spawn into a tree held by a live seat or by a spawn still\nbringing one up is the catchable L4008, a spawn that ends without a handle gives the tree back,\nand the tree is reusable the moment a holder\'s presence row is gone, so a discharged race loser\nor a crashed seat releases its tree with no bookkeeping. A spawn the endpoint refuses at accept\nis the catchable L4000 (L4001 when the refusal is the endpoint\'s seat capacity), and one whose\nseat never came up is L4002. A refusal that states the command did not run is answered\nbefore it gets that far. In a space served by more than one manager the resolve and the invoke\nare separate trips through the same anycast queue, so a run\'s call can reach an instance it did\nnot resolve against, and that instance refuses ahead of any effect. The run drops its resolved\nhandle, re-describes and re-issues, for a bounded number of attempts; after them the refusal\nsurfaces as the effect\'s own failure and still states that nothing ran. A spawn that names a\n`placement` addresses one instance by name, so a refusal from it is that incarnation answering\nabout itself and is never re-issued. A turn handoff across worktrees is the L4004 described above. Recovery keeps these honest: a resumed run\nreseeds its roster, holders and handoff memos from its own journal, and the driver re-issues any\nrecorded-but-undischarged cancellation at adoption, before the engine performs a new step, so a\nloser a crash left alive does not keep its seat or its tree while the resumed run works on. The\nsame sweep withdraws a cancelled branch\'s undelivered notices: a notice waits on the run for its\naddressee\'s next turn, so a decision the run cancelled would otherwise arrive at an agent with\nnothing to distinguish it from one that stood.\n\nEvery effect the language defines performs on the mesh handler; nothing is refused as\nnot-yet-durable any more. The operator surface over the driver is `cotal run`; the section above has the verbs.\n\n**Two engines, and which one runs your program.** The tree-walker is language version `1` and the\ncompiled engine is version `2`, two languages rather than two speeds of one (`spec/cotal-lang.md`\n\xA78.4 lists what differs). The driver hosts both: **every run a driver starts is stamped `2` and\nexecuted by the compiled engine**. The program runs in its own locked-down worker thread with\nnothing in its global scope, while the effects and the durable journal stay in the driver\'s process,\nbridged over a message port. No socket or credential enters the isolate holding the program,\nand **every version-`1` record keeps replaying on the walker**, which is the walker\'s job. The\ndriver serves a declared set of versions, and a record whose version it does not serve is refused\nby name (**L5023**) with the run left untouched, instead of being replayed by whichever engine\nhappens to be present. Records do not cross between versions in either direction; the repair is to\nresume on the recorded version, or to fork.\n\n**The engine needs node 22 or newer** and refuses below it as `EngineUnavailable`, which is an\nimplementation limit and not a language error: it carries no `L` code, so there is nothing to look\nup in the catalog. It is a floor rather than a warning because the engine\'s frame plumbing rests on\n`AsyncLocalStorage`, and 22 is the lowest node it has been measured on. The walker has no such floor.\n'
+      "body": '# Workflow runs\n\n> **Concept** (informative) \xB7 **For:** people writing a durable multi-agent workflow, and implementers hosting one \xB7 **Normative:** [SPEC \xA714](../SPEC.md#14-workflow-runs-v05) and the language reference [`spec/cotal-lang.md`](../spec/cotal-lang.md)\n\nA **workflow run** is a program that coordinates agents over hours or days and survives the\nprocess that started it. The program is written in **Cotal Lang**, a small subset of JavaScript in\nwhich every interaction with the world is one of a dozen **effects** (`spawn`, `turn`, `ask`,\n`checkpoint`, `sleep`, `wait`, `notify`, `monitor`, and the four concurrency scopes) and everything\nelse is ordinary, pure JavaScript. Every effect is written into the run\'s **step journal** before\nit is performed and settled after, keyed by where in the program it happened rather than by when,\nso a run that dies is resumed on any host by **re-running the program from the top** with recorded\neffects returning their recorded results. Nothing about the interpreter is ever serialized: the\njournal and the program are the whole state.\n\n## A first program\n\n```js\nconst planner = await spawn("planner")\nconst builder = await spawn("builder", { worktree: "wt-1" })\n\nconst plan = await ask(planner, { name: "plan", schema: { steps: "array" } })\nconst ok = await checkpoint("approve-plan", "Approve the plan?", { timeout: "4h", onExpiry: "proceed" })\nif (ok.status !== "resolved") {\n  await notify([planner], { decision: "approve-plan", outcome: "expired" })\n}\n\nconst r = await turn(builder, { name: "build", deadline: "30m" })\nif (r.status === "blocked") {\n  await turn(planner, { name: "unblock" })\n}\n\nconst outcome = await race({\n  reply: () => wait(replied(builder), { timeout: "20m" }),\n  giveUp: () => sleep("1h"),\n}, { name: "await-or-move-on" })\nlog("outcome", outcome.index)\n```\n\nRead it as the flowchart it is. `spawn` brings agents in; `ask` is the narrow case where the\nprogram itself needs a value (`schema` is a record the program hands the handler unchanged; the\nlanguage hashes it and gives it no meaning, and the handlers in this repository enforce it as the\nshorthand of the language reference \xA76.5);\n`checkpoint` is a durable pause a human resolves from anywhere, raced against a durable timer; `turn`\nwakes an agent for one turn and returns how it yielded; `race` runs two branches and keeps the one\nwhose recorded clock is earliest. Agents talk to each other in channels as they always do; the\nprogram never speaks in a channel, and the one thing it can put in front of an agent (`notify`) is a\nbounded decision record, not prose.\n\n## The mental model\n\n- **Pure code is JavaScript.** Loops, records, arrays, closures, template literals, destructuring,\n  `try`/`catch`, arithmetic, `switch`, compound assignment, optional chaining, spread and rest: what\n  you would write anyway, with the parts that hide effects or make meaning depend on the host removed\n  (`class`, `this`, `new`, `for...in`, `==`, labels, regex literals, `Math`/`Date`/`JSON`, promises,\n  generators). Every refusal names its code and the edit that fixes it. The builtins are a short list\n  (`keys`, `map`, `sort`, `json.stringify`, `now()`, `random()`), and arrays, strings and numbers\n  answer their usual methods (`xs.map`, `s.trim()`, `n.toFixed()`) and nothing outside that table.\n  Records and arrays you build are yours to change until they cross an effect boundary; a member you\n  do not own, a host prototype, or a value another branch built is refused with a code, never a\n  surprise.\n- **Every effect is journalled and hashed.** A step is keyed `(scope path, kind, name, occurrence)`\n  and its inputs are hashed. Reorder your program, add a step, rename a variable: recorded steps\n  still match. Change what a step asks (a checkpoint\'s prompt, a sleep\'s duration, a turn\'s\n  deadline) and the resume stops with a **divergence** naming the step, rather than replaying an\n  answer to a question the program no longer asks.\n- **Concurrency is visible.** `parallel`, `race`, `fanOut` and `conclave` are the only ways to do\n  two things at once, each branch gets its own journal namespace, and the scope writes its own\n  entry saying how it settled: which arm won a race is a recorded fact, decided by the arms\'\n  recorded clocks and declaration order, never by a scheduler. A branch may not write to anything\n  declared outside it; return the value and read it out of the scope\'s result.\n- **Time and randomness are tamed.** `now()` is the branch\'s run clock, the end of the last effect\n  it awaited; `random()` is a seeded stream derived per scope. Both replay identically.\n- **Values freeze at the boundary.** What crossed into or out of an effect is what the journal\n  recorded, and it cannot change afterwards; build a new value.\n- **The journal is the debugger.** Every entry carries its key, its inputs\' hash, its outcome and\n  its timing, and every error is in the program\'s own coordinates. A run can be **simulated** with a\n  scripted handler and **dry-run** to a plan before it touches an agent. The simulator is\n  discrete-event: timed effects park at their wake times and are delivered in wake order on one\n  virtual clock, so concurrent branches accumulate the durations they wrote and a simulated `race`\n  is decided by the same rule a live handler produces (least recorded clock, ties by declaration\n  order). A `sleep("1m")` arm beats a `sleep("1h")` arm whatever their declaration order.\n\nFull rules, with every code: [`spec/cotal-lang.md`](../spec/cotal-lang.md).\n\n## Continuing a run\n\n**Resume** is re-execution: the driver replays the journal, the program runs from the top, recorded\nsteps return instantly, and the first unrecorded step is performed live. It refuses a journal that\nbelongs to another run, a pin that differs from the recorded ones, and a different language version.\n\n**Migrate** moves a run onto edited source. A dry walk of the new program over the recorded journal\nfinds every recorded step the edit changed (a divergence) and every one it no longer reaches (an\norphan), and the orphan table says what each means: a removed `sleep` is nothing, a removed `turn`\nalready happened, a removed `spawn` is a live agent you must adopt or release, a removed resolved\n`checkpoint` is a human decision you must explicitly discard. The decision is filed as a\n`migration` record with the actor\'s name on it. An adopted seat (`--adopt <name>#<uid>`) goes to\nthe edited program\'s next `spawn` of that persona, which returns the recorded handle and mints\nnothing, so the agent keeps its identity, its worktree and its turn history across the edit. A\nreleased seat (`--release <name>#<uid>`) is despawned when the migration commits, through the same\ndischarge a cancelled branch\'s seat leaves by, so the record never claims a release nothing did.\nThe spawn that adopts a seat binds the orphaned spawn\'s goal as its own, so a resume of that step\nreads the same seat back and a cancellation of it despawns the seat it holds.\n\n**Fork** starts a new run from a named step of an old one, copying the prefix under the parent\'s\npins (seed included, so the copied history\'s pure draws are the same draws). The child is a new run\nunder a new id whose record names the parent and the cut step (`forkedFrom`); the parent is\nuntouched. A spawn inside the copied prefix is honoured by its `onFork`: `"adopt"` copies it, and\nthe child shares the parent\'s agent (the manager shows that seat one turn at a time across both\nruns); `"respawn"`, the default, would mint a fresh identity the copied turns do not address, so\nthis host refuses that cut (L5019) rather than rewriting the parent\'s history.\n\nFork planning and migration inspection use the recorded language version. Version-1 history uses\nthe interpreter. Version-2 history is inspected inside a locked-down worker with a read-only\njournal, without a live effect handler or durable store. Inspection stops before the fork\'s cut\nstep or any effect that needs new work. Program catch and finally blocks cannot extend the cut.\nThe recorded pins are preserved.\n\n## From an agent session\n\nFresh `cotal setup` defaults declare `capabilities: [spawn, run]`. On a static-auth mesh,\nthat exposes `cotal_run` alongside the teammate tools. The manager must be running.\nRead `cotal_docs` pages `lang-card` and `workflows`, then try:\n\n```json\n{\n  "verb": "start",\n  "source": "await sleep(\\"1s\\", { name: \\"first-run\\" });",\n  "file": "first-run.cotal.js"\n}\n```\n\nPass this object to `cotal_run`. `source` contains the program; `file` only labels diagnostics\nand reads nothing from disk. The response returns a run ID before execution finishes. Call\n`cotal_run` with `verb: "status"` and that `runId` to inspect the state and step journal.\nA completed timer records its sleep step as `ok`.\n\n### If `cotal_run` is missing\n\n1. Call `cotal_orientation` and check the connector version, capabilities and tool list.\n   Upgrade an older installation using the [upgrade guide](https://github.com/Cotal-AI/Cotal/blob/main/docs/UPGRADING.md).\n2. Have the operator add `run` to the persona\'s existing `capabilities` list, for example\n   `capabilities: [spawn, run]`. `spawn` alone does not expose `cotal_run`. Setup leaves existing\n   personas unchanged except for its [byte-exact legacy migration](getting-started.md).\n   Peer persona-definition tools cannot grant capabilities.\n3. Relaunch the agent through the manager from the updated persona so it receives newly issued\n   credentials and a fresh connector configuration. Editing the file or reconnecting with the\n   old credential does not grant new broker permissions. If the launch sets `COTAL_CAPABILITIES`,\n   update that override too; it takes precedence over the file.\n4. Check `cotal_orientation` again, then call `cotal_run` with `verb: "ps"` before starting work.\n\nTool visibility alone does not establish execution support. Hosted runs currently require\nstatic authentication with issued caller authority. Open meshes can expose the tool but refuse\nhosted runs; user-auth meshes also refuse them. A legacy credential without issued authority\nmust be replaced through the current issuance path before it can start a hosted run.\n\n## Operating a run\n\nThe manager hosts runs. `cotal run start` hands the program to the manager of the resolved mesh\n(the usual `--space` / `--server` / `--creds` flags), which validates it, mints the run id, drives\nit in its own process, and answers with the id once the run is recorded. The terminal is free the\nmoment the id prints; the run continues on the manager through every pause, and a manager restart\ntakes back every run it had recorded running, from the journal, under the next epoch. `resume`\nnames a run the manager recorded and is refused while the manager is already driving it. `ps` and\n`journal` read; `answer` resolves an open checkpoint, or an open `ask` attempt, from any terminal\nor agent that holds the `run` capability.\n\n```bash\ncotal run start --file build.cotal.js                   # the manager starts it; the minted id is printed\ncotal run ps                                            # list run records: state, holder, lineage\ncotal run journal run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # print the durable step journal\ncotal run resume run-3f2a90c41b7e0d5a6c884e19b02df4a1                      # the manager takes the run back\ncotal run answer run-3f2a90c41b7e0d5a6c884e19b02df4a1 "/checkpoint:approve#0" --value \'"yes"\'\n```\n\nA program that does not validate is refused before anything is recorded, with every problem in the\nanswer as the validator would print it. The driver records the program beside the run, so `resume`\ntakes the run id alone and the manager reads the source back; an edited program is a `migrate` or a\n`fork`, never a resume. An answer is recorded under the answerer the manager knows from the\ncaller\'s credential: a managed agent by its name, anyone else by their principal. The request\ncarries no name. An agent with `capabilities: [run]` has the same five verbs as the `cotal_run`\ntool ([MCP tools](mcp-tools.md)), so a program can be written and started from inside a session.\nA `start` or `resume` answers once the run\'s record is written, within a bounded wait; a manager\nthat is still taking back a predecessor\'s runs at boot refuses both with `unavailable`, and a\nretry a moment later is the whole remedy.\n\n`--local` drives the run in this process instead: `start`, `resume` and `answer` exit when the\ndrive settles, `--by <who>` names the answerer, and `cotal run resume <runId> --local --file\n<program>` is how a run with no recorded program is continued. On a static mesh the local drive\nmints the run\'s own credential from the folder\'s trust material, so it runs from the mesh\'s\nproject folder. A local start also names the run\'s channel ceiling itself:\n`--admit-read <channels> --admit-publish <channels>`, comma-separated patterns or `none`, both\nrequired. The record it writes says an operator admitted the run and why, and the host checks\nit the same way it checks a hosted admission. A user-auth mesh runs no programs yet, hosted or\nlocal: the manager refuses the family by name, since a hosted run\'s seats would be spawned under\nthe static owner, which a user mesh refuses, and a user bearer holds no run rows. An open mesh\nhosts none either, since it issues no caller authority to admit a run under.\n\nA hosted run is **admitted** under the caller that started it. The caller\'s credential is an\nissuance ([identity and auth](identity-and-auth.md#issued-authority)): its requests ride a\nversioned rail that carries the credential\'s generation, and the manager resolves that\ngeneration\'s recorded permission ceiling and writes it beside the run before the driver starts.\nThat ceiling, the caller\'s own channel scope as it was issued, is what the run may read and post\nin channels; the manager\'s own reach never stands in for it. A request from a credential minted\nwithout an issuance is refused with `permission-denied` and a detail naming the caller. A run\nwhose caller had no channels can still sleep, checkpoint and turn agents; its `wait` on a channel\nis refused at the effect.\n\n`cotal run revoke <runId> --local --by <who> --reason <text>` writes the run\'s revocation marker\nfrom the project folder. An empty `--by` or `--reason` is refused before anything is written. The\nadmission itself is never rewritten. Every host reads the marker\nbefore its next channel effect, so an open `wait` refuses at its next poll, and no resume,\ntakeover or manager restart continues the run. Revoking twice is not an error, and the first\nreason stands. A run whose admission is missing or revoked is left parked by the manager\'s boot\nreconcile, named in its log.\n\n`run ps --local` reads the marker beside each run record and prints `revoked` for a run that\ncarries one, whatever state the record itself holds, with the revoker and the reason under the\ntable. The record is display only here: a revoke writes no terminal state, because no host drove\nthe run to one and the journal owns the facts. A marker the listing cannot read, whether the store\nis unreachable or the marker has a version or shape it does not know, prints `unchecked` in the\n`STATE` column. The reason and the state the record carries go to stderr, and the command exits 1\nonce every row is printed. The hosted `run ps` reads the record alone.\n\nA run whose step was refused (L5016) stays held; a\nresume on a host that can perform the step performs it live and continues from there.\n`journal` prints what an open pause asks beneath its step key, which is the address `answer` takes\nback. Checkpoint expiry rides the mediated timer writer, which the delivery daemon pumps on a live\nmesh; on a bare broker a pause still resolves, it just cannot expire.\n\n## What is on the wire\n\nThe run\'s wire footprint is [SPEC \xA714](../SPEC.md#14-workflow-runs-v05):\n\n| Thing | Where | What it is |\n| --- | --- | --- |\n| the run | `run.<endpoint>.<runId>` record | the resolved **pins** (seed, logical epoch, budgets, language version) on the immutable half; holder, lease and `journalHigh` on the status half |\n| the program | `program.<endpoint>.<runId>` record | the source the run was started from, verbatim, written once by the driver that pinned the run; what a resume reads and what a migration is measured against |\n| the step journal | `WFJ_<space>` stream, one subject per run | append-only, no age eviction, no Direct Get; every append fenced by the run subject\'s own sequence; takeover is replay-then-activate |\n| a checkpoint answer | `answer.<endpoint>.<token>.<answerId>` | the payload beside the one-use settle fact; the settle names the answer it accepted |\n| a notice | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>` | one bounded decision told to one agent, rendered ahead of its next turn |\n| a migration | `migration.<endpoint>.<runId>.<migrationId>` | the report and who applied it, keyed by the report\'s own digest |\n| the admission | `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>` | the caller the run was admitted for, its channel ceiling and its provenance; written once before the driver starts, and the store refuses a second write on the key |\n| a revocation | `revoked.v1.<endpoint>.<runId>` in the same store | who revoked the run and why; create-only, idempotent, permanent at the broker, read by every host before its next channel effect |\n\nA run\'s **driver** connects on a `run-driver` credential minted for one run and takeover\nattempt. It can append to its journal, use its replay durable, and write its own `run`, `program`,\n`notice` and `migration` records. It has no store point reads, checkpoint writes, chat consumers,\nor channel and membership registry grants.\n\nThe hosting process keeps a separate `run-mediator` connection for effects and reads. The driver\nreceives methods and data from that host; it never receives the mediator credential or connection.\nThe host checks the journal\'s current activation and step identity before dispatch, and checks\npause and wait authority again at each operation. Cancellation cleanup also admits losing steps\nnamed by a settled parent whose `cancel.issued` is still false. That permission allows cleanup;\nit cannot mint or rearm a cancelled pause. Wait acknowledgements consume host-held delivery\nreceipts. A recorded match can be reread only at its bound sequence and channel. A conclave\'s\nrecorded ownership flag must match its step-derived channel before registry writes or cleanup.\n\nThe mediator retains endpoint-wide checkpoint rights and stream-wide leader reads as trusted\nhost authority. Record reads exposed to the driver are restricted to its own run\'s keys. Reads\nthat decide writes remain leader-served. A read of the journal uses the run\'s filtered replay\ndurable, including the diagnostic for a journal with no run record. That durable is named after\nthe takeover, and an attempt reads it many times, so reads under one takeover run one at a time in\nthe hosting process and a replay removes a durable of its own name that an interrupted earlier read\nleft behind. A durable that survives a replay\'s own delete belongs to a reader the process cannot\naccount for, and reading its tail is refused.\n\nA served read uses a one-shot `run-operator` credential. An answer uses a read to find the open\npause, then a second credential pinned to that token for the answer and settlement.\n`cotal run --local` uses the same driver/mediator split. On an authenticated mesh it needs the\nlocally recorded space signer to mint both credentials; a single `--creds` file is refused.\nDirect library users supplying broker clients to `MeshHandler` are constructing a trusted effect\nhost. A hosted driver receives its closed effect interface instead.\n\nThis split confines broker credentials; it is not process isolation for injected host code.\nThe runtime and its effect host share the manager process. A run\'s channel reach is the admitted\nceiling ([SPEC \xA714.8](../SPEC.md#148-run-admission)): the starting caller\'s issued channel scope,\nrecorded once in `cotal_admission_<space>` under a per-run `run-admitter` credential the driver\nnever holds, and re-read by the host before every channel effect. Spawn and turn keep their own\ndelegated checks; `notify` writes agent-addressed notices and is not channel publication. Treat\n`run` as program-execution authority bounded by that ceiling, not as sandboxing of the program.\n\nA version-1 fork can replay its settled parent history through the host. Inherited checkpoint\nidentifiers carry no authority to read, rearm or claim the parent\'s pauses. New child effects use\nchild-derived identifiers. A fork is a new run and takes a new admission under the caller who\nforks it; the parent\'s ceiling is not inherited.\n\n\n## What ships today\n\nThe language, its validator, interpreter, simulator and dry run are `@cotal-ai/lang`\n(`packages/lang`), usable in-process with your own effect handler and with no broker: `validate(src)`,\nthen `run(src, { runId, handler })`, and `resume(src, journal, { runId, pins, handler })` to pick a\nrun up from its journal (the package README has the snippet, with `SimHandler` as the handler). That\nis the in-process route, yours to drive with your own handler; a run the driver starts executes on\nthe compiled engine, as the engine paragraph below says. The wire\nsubstrate of \xA714 (the `WFJ_<space>` stream, the five record kinds, the activation barrier, the\nper-run grants) is in `@cotal-ai/core`, and the run driver, journal store, migrate and fork are\n`@cotal-ai/runtime` (`implementations/runtime`). On the mesh handler, `sleep`, `checkpoint`,\n`wait(message(...))`, `wait(idle(...))`, `wait(down(...))`, `wait(replied(...))`, `notify`,\n`spawn`, `conclave`, `ask`, `monitor` and `turn` are durable.\n`spawn` is\nthe manager\'s spawn action submitted under the step\'s own identity: the goal binds under the step\'s\nrequest id, so a resumed run re-attaches to the same seat instead of allocating a second one, a\nfailed or refused spawn is catchable as L4002 with the manager\'s recorded reason, and a spawn on a\nrace branch that loses is despawned by the run\'s own cancellation sweep. `permits` are the budgets\nthis host meters: `turns`, how many turns the run may dispatch to the agent, and `wallClock`, a\nduration from the spawn after which no turn is admitted. The turn that would exceed one is the\ncatchable L4001 (kind `permit-turns` or `permit-wall-clock`; a deadline the remaining wall clock\ncannot hold counts as exceeding it), an adopted run counts the turns its journal recorded, and a\nbudget the host has no meter for, such as `tokens` or `spend`, is refused at the spawn rather than\naccepted and ignored. `supervise` is the restart policy this host asks the manager to enforce:\n`restarts`, how many in-window process deaths may come back under the same handle, and `window`,\nthe duration those deaths are counted in (default `10m`). The manager restarts the process in\nplace under the same name, lifecycle uid, persona, worktree and permits; `monitor` does not fire\nfor a restart, and `wait(down)` fires only when the seat is gone for good. Spending the budget\nretires the seat, and the next `turn` is the catchable L4002. A policy this host cannot enforce\n(an unknown key, a user-mode seat, or a runtime that cannot respawn a name in place) is refused\nat the spawn rather than accepted and ignored. `conclave` joins its\nmembers to a real channel as durable membership rows: the channel derives from the step\'s own\nrequest id when the program names none (a program-named channel is borrowed, never torn down, and\na membership that predates the conclave survives its close), each member handle resolves to its\nprincipal through the seat\'s own presence row (an absent member is catchable as L4002), and a\nconclave cancelled on a losing branch is released by the same cancellation sweep. `ask` parks one\ncheckpoint-plane pause per attempt, answered through `cotal run answer` as a checkpoint is, and\ntells the agent through the same relay `turn` uses: one relay per attempt under the attempt\'s own\ntoken, carrying the schema, the attempt count, the deadline and the previous refusal, which the\nseat\'s connector renders as the record wanted and the command that answers it. An ask addresses\nan agent the run spawned (anything else refuses before an attempt opens), a resumed attempt tells\nthe seat nothing twice, and a seat gone at the relay is L4002. On the pause itself:\nthe shorthand of the language reference \xA76.5 is enforced (an unreadable schema is L4022), a\nnon-conforming answer costs one attempt and its refusal reason is recorded on the entry for the\nanswerer to read, exhausted attempts (default one) are the catchable L4006, and so is the one\nabsolute deadline for the whole ask passing with no conforming record (its kind is `ask-deadline`).\n`checkpoint` binds what it asks on its own entry, so `cotal run journal` prints the question under\nthe step key an answer is addressed by while the pause is open: the address alone left whoever was\nasked reading the source to find out what "approve" meant. An `escalate` addressed to an agent this\nrun spawned is relayed to that seat through the same turn relay an `ask` uses, carrying the prompt\nand the token to answer under; a `to` naming anyone else is a person, and their pause stays the\none anybody can answer, with the addressee recorded and rendered beside the question.\n`monitor` registers interest in an agent, and the\nregistration is the journal entry itself, carrying the handle it registered: monitoring an agent\nthat is already dead succeeds, and the death is the wait\'s to observe. `wait(down(...))` observes\na monitored agent, and refuses one the run never performed `monitor` on. It reads the death off presence liveness, the\nsame witness a conclave join resolves members through: the value carries the handle, the reason\n(`lapsed` when nothing live holds the name any more, `superseded` when a live row holds it under\na different incarnation) and the time of observation, a wait that begins after the death resolves\nat once, and a timeout resolves null on one absolute deadline a resumed run re-attaches to.\n`turn` wakes one seat for one host turn through the manager as a pull-shaped relay: the run\nsubmits the turn under the step\'s own identity, the manager holds it as a goal pinned to the\nseat\'s incarnation, and the seat pulls it under its own reach ahead of its next host turn, so\nnothing is pushed into a session mid-thought. The payload the seat reads names the run and the\nstep and carries the rendered run context, plus any pending notices addressed to it, which the\nturn consumes. The seat yields through `cotal_yield` (`done`, `blocked`, or `handoff` with an\naddressee), and ending its host turn yields `done` for every turn it was shown. A `handoff` names\nanother seat the same run spawned: the next `turn` in the same scope to that seat records the\nlink, a handoff to a name the run never spawned is the catchable L4005, and one to a seat bound\nto a different worktree is L4004. The deadline elapsing before any yield is the catchable L4003:\nthe acceptance names the instant, the manager\'s goal-bound hold denies at it, and the run arms its\nown pause on that same instant, so either side outliving the other still converges on the same\nanswer. A seat that dies mid-turn is read off its own presence row by the run itself and is the\ncatchable L4002, and a death the manager marked on the deadline terminal reads the same way. Two\nturns on one seat, from two branches or from two runs, reach it one at a time: the language\ndispatches the second when the first settles, and the manager shows a seat the oldest unsettled\nturn alone. On an auth mesh the relay needs no extra grant: every spawned seat\'s baseline\ncredential carries its own pull and yield rows, the run driver\'s operator instrument carries the\nturn request, and the manager arms the deadline hold over its own serve grant and expires it\nitself once due. An accept the manager cannot finish is unwound to a failed terminal on the goal\nit bound, and a retry of that submission is refused naming the terminal rather than accepted a\nsecond time.\n`wait(replied(...))` observes those turns from another branch: a completed turn is a reply, and\nthe wait resolves with the observation record (the handle, the yield\'s status and note, the\nyield\'s own stamp). It reads as a level, the way `wait(down)` does: a reply that already exists\nresolves the wait at once, and two replies resolve to the latest by the yield\'s stamp. A denied\nor cancelled turn is never a reply, so an unanswered wait rides its own mediated timeout to\n`null`, and a handle the run never spawned or turned refuses loudly, since only this run\'s turns\nare observable. A turn the run itself ended without an accepted yield (its deadline, a\ncancellation, a refused handoff) is never a reply, whatever the seat yields to the relay later.\nA `spawn` may bind its agent to a **logical worktree** (`spawn("builder", { worktree: "wt-1" })`):\nthe handle carries the id, and the run enforces the one rule the language states about it: two\nagents never share a worktree concurrently. The validator rejects the literal case up front\n(L3022: two branches of one concurrent scope spawning into one literal worktree, named branch\nfunctions included), and the runtime guards the rest, computed ids included: a spawn claims its\ntree before it submits, so a second spawn into a tree held by a live seat or by a spawn still\nbringing one up is the catchable L4008, a spawn that ends without a handle gives the tree back,\nand the tree is reusable the moment a holder\'s presence row is gone, so a discharged race loser\nor a crashed seat releases its tree with no bookkeeping. A spawn the endpoint refuses at accept\nis the catchable L4000 (L4001 when the refusal is the endpoint\'s seat capacity), and one whose\nseat never came up is L4002. A refusal that states the command did not run is answered\nbefore it gets that far. In a space served by more than one manager the resolve and the invoke\nare separate trips through the same anycast queue, so a run\'s call can reach an instance it did\nnot resolve against, and that instance refuses ahead of any effect. The run drops its resolved\nhandle, re-describes and re-issues, for a bounded number of attempts; after them the refusal\nsurfaces as the effect\'s own failure and still states that nothing ran. A spawn that names a\n`placement` addresses one instance by name, so a refusal from it is that incarnation answering\nabout itself and is never re-issued. A turn handoff across worktrees is the L4004 described above. Recovery keeps these honest: a resumed run\nreseeds its roster, holders and handoff memos from its own journal, and the driver re-issues any\nrecorded-but-undischarged cancellation at adoption, before the engine performs a new step, so a\nloser a crash left alive does not keep its seat or its tree while the resumed run works on. The\nsame sweep withdraws a cancelled branch\'s undelivered notices: a notice waits on the run for its\naddressee\'s next turn, so a decision the run cancelled would otherwise arrive at an agent with\nnothing to distinguish it from one that stood.\n\nEvery effect the language defines performs on the mesh handler; nothing is refused as\nnot-yet-durable any more. The operator surface over the driver is `cotal run`; the section above has the verbs.\n\n**Two engines, and which one runs your program.** The tree-walker is language version `1` and the\ncompiled engine is version `2`, two languages rather than two speeds of one (`spec/cotal-lang.md`\n\xA78.4 lists what differs). The driver hosts both: **every run a driver starts is stamped `2` and\nexecuted by the compiled engine**. The program runs in its own locked-down worker thread with\nnothing in its global scope, while the effects and the durable journal stay in the driver\'s process,\nbridged over a message port. No socket or credential enters the isolate holding the program,\nand **every version-`1` record keeps replaying on the walker**, which is the walker\'s job. The\ndriver serves a declared set of versions, and a record whose version it does not serve is refused\nby name (**L5023**) with the run left untouched, instead of being replayed by whichever engine\nhappens to be present. Records do not cross between versions in either direction; the repair is to\nresume on the recorded version, or to fork.\n\n**The engine needs node 22 or newer** and refuses below it as `EngineUnavailable`, which is an\nimplementation limit and not a language error: it carries no `L` code, so there is nothing to look\nup in the catalog. It is a floor rather than a warning because the engine\'s frame plumbing rests on\n`AsyncLocalStorage`, and 22 is the lowest node it has been measured on. The walker has no such floor.\n'
     }
   ],
   "spec": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cotal-ai/pi",
-  "version": "0.50.0",
+  "version": "0.50.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -34,8 +34,8 @@
     "esbuild": "^0.28.0",
     "typebox": "^1.1.0",
     "zod": "^4.4.3",
-    "@cotal-ai/core": "0.50.0",
-    "@cotal-ai/connector-core": "0.50.0"
+    "@cotal-ai/core": "0.50.1",
+    "@cotal-ai/connector-core": "0.50.1"
   },
   "files": [
     "dist"