@cotal-ai/pi 0.65.0 → 0.66.1

package/dist/index.js

@@ -3262,6 +3262,10 @@ var AguiEmitter = class _AguiEmitter {
   get stopped() {
     return this.halted !== void 0;
   }
+  /** The run {@link closeRun} would close now, or `undefined` at a stopping point. */
+  get openRunId() {
+    return this.brackets.runId;
+  }
   /**
    * Boot recovery, branching on the WAL's tag.
    *
@@ -4664,6 +4668,7 @@ var AguiEmitterHolder = class {
   onError;
   onRunClosed;
   waitLive;
+  runMeta;
   emitter;
   /** The path this holder is BOUND to. Set before `starting`, so a second path is refused even
    *  while the first start is still in flight. */
@@ -4714,12 +4719,19 @@ var AguiEmitterHolder = class {
    *   connectors' `MeshAgent`-adjacent wiring owns: the holder knows WHEN to publish, the caller
    *   knows HOW to observe liveness. Without it, a rebuild window between two pumps reads
    *   `max_payload` off a connection that is not there and kills the seat (#1868).
+   * @param runMeta The Cotal metadata for the run {@link closeRun} is about to close, such as its
+   *   stop reason or usage, put on whichever terminal closes it. Asked inside the queued close
+   *   rather than taken at call time, because the hook calls `closeRun` before the flush queued
+   *   ahead of it has mapped the turn's last records, and those are what the metadata comes from.
+   *   Keyed on the run id, so a provider that only knows a different run answers `undefined`
+   *   instead of attributing its numbers to this one.
    */
-  constructor(startEmitter, onError, onRunClosed, waitLive) {
+  constructor(startEmitter, onError, onRunClosed, waitLive, runMeta) {
     this.startEmitter = startEmitter;
     this.onError = onError;
     this.onRunClosed = onRunClosed;
     this.waitLive = waitLive;
+    this.runMeta = runMeta;
   }
   /** True once an emitter is running here. False while a start is still in flight — it reports what
    *  IS, never what is about to be. A dead holder is not running: after {@link die} what IS, is
@@ -4810,7 +4822,9 @@ var AguiEmitterHolder = class {
       if (this.dead || !emitter || emitter.stopped)
         return;
       await this.holdForLive();
-      const runId = await emitter.closeRun({ timestamp, ...error51 ? { error: error51 } : {} });
+      const open5 = emitter.openRunId;
+      const cotal = open5 === void 0 ? void 0 : this.runMeta?.(open5);
+      const runId = await emitter.closeRun({ timestamp, ...cotal ? { cotal } : {}, ...error51 ? { error: error51 } : {} });
       if (runId !== null)
         this.onRunClosed?.(runId);
     });
@@ -19523,7 +19537,7 @@ import { isConcreteChannel as isConcreteChannel3, channelInAllow as channelInAll
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.65.0",
+  "version": "0.66.1",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -19594,7 +19608,7 @@ var DOCS_BUNDLE = {
       "title": "`cotal` CLI reference",
       "kind": "Reference: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract.",
       "summary": "cotal is the operator command line for the reference implementation: bring a mesh up, mint identities, launch agents, watch what they do, and tear it all down.",
-      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 22+)\ncotal --help              # every command, grouped\ncotal --version           # cotal-ai version + each installed extension's (also `cotal -v`)\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nAn undeclared flag is a usage error, and so is a flag given more than once unless it is\nrepeatable, as `--opt` and `down --session-store` are. The command prints the error and its help,\nexits 1, and does not run.\n\nCommand output, including error lines on stderr and the guided `setup` and `meshes add` prompts,\nis colored only when stdout is a terminal, so piped or redirected output is plain text. A non-empty\n`NO_COLOR` turns color off on a terminal too. `FORCE_COLOR` turns color on even when output is\npiped, unless it is `0` or `false`, and it takes precedence over `NO_COLOR`.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` installs any registry providers a package contributes: commands,\nruntimes, and local process lifecycle descriptors. The `web` dashboard and optional manager\nruntimes ship this way.\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`update`](#update) | Reconcile first-party extensions and check or opt into a coherent CLI upgrade |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop the whole stack, selected registered components, or a manifest deploy |\n| Set up & lifecycle | [`backup`](#backups) | Create an offline full-space or registry-only artifact from a preserved cut |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#mesh-registry) | List the running meshes on this machine |\n| Set up & lifecycle | [`sync`](#mesh-registry) | Refresh the signed-in account's advertised spaces |\n| Set up & lifecycle | [`use`](#mesh-registry) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#mesh-registry) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#managed-seats) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#managed-seats) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#managed-seats) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`input`](#input) | Type one line into a managed agent's terminal without attaching |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Agents & personas | [`service`](#service) | Run the manager as a user service (survives logout and reboot) |\n| Agents & personas | [`runtimes`](#runtimes) | List the agent runtimes the manager can spawn through and whether each is reachable |\n| Agents & personas | [`seats`](#seats) | List the pty seat custodians an earlier Linux manager left, and drain the ones whose agent has exited |\n| Agents & personas | [`reconcile-gate`](#reconcile-gate) | Unfreeze an issuance gate left frozen by a crashed restart when the successor cannot boot-heal it (holder gone, complete CONNZ sweep) |\n| Messaging & watching | [`endpoints`](#endpoints) | List every endpoint in the live presence roster, including infrastructure |\n| Messaging & watching | [`describe` / `invoke`](#endpoint-control) | Resolve a v0.4 service's command surface off the wire; invoke one command by name |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Workflow runs | [`run`](#run) | Operate durable workflow runs: start, resume, list, inspect, answer a checkpoint, check an edited program with migrate |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes] [--skills]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n| `--skills` | off | Reconcile Cotal skills only through installed connector providers, plus `~/.agents/skills`. Refused with `--full` or `--demo`. |\n\nGuided setup is **configure-only**: it checks prerequisites, invokes installed connectors' declared setup providers, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. `cotal status` points stale Claude skills and\nout-of-date `.agents` skills at `cotal setup --skills`, not unscoped `setup`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\nWhen a mesh resolves, setup seeds that mesh's recorded `.cotal/agents` catalog, the same catalog a\nfollowing `cotal spawn` reads. It prints the absolute destination. On a fresh machine with no mesh it\nuses this folder and says why; when several meshes are available and none is selected, it refuses\nrather than choosing a catalog.\n\n## update\n\n```bash\ncotal update [--self] [--space <s>] [--server <url>] [--creds <path>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--self` | off | If a newer release exists, install that exact validated `cotal-ai` version globally and reconcile through the newly installed binary |\n| `--space`, `--server`, `--creds` | resolved mesh | Select the running manager whose continuity state is reported |\n\nWithout `--self`, `update` keeps the installed first-party surfaces coherent with the running\nbinary: it force-reconciles the four built-in connectors, then reinstalls other `@cotal-ai/*`\noperator extensions at the binary's exact version. Each extension runs in an isolated child, so one\nfailure cannot poison later replays. It then checks npm; a newer binary is an informational notice\nwith `cotal update --self` as the next command, not an automatic install.\n\nAfter disk reconciliation, `update` reads the selected running manager. A machine with no recorded\nmesh has no running manager to observe, so that read is skipped and the command completes. The same\nholds when every recorded mesh is down and none is selected. A remote user mesh, registered with\n`cotal meshes add --mode user`, is named and skipped: its manager runs under another install, so\nthere is no custody on this machine to preserve, and a `legacy` verdict still comes only from a\nmanager this machine read. A recorded mesh that is down is still a\nrefusal when the command selects it, with `--space` or by running inside its project, and so is a\nnamed space that is not running. With several meshes running and no `--space`, `--server` or\n`--creds`, the install is machine-wide, so every running manager is reported in turn, each under its\nspace name, before anything is written; a `legacy` verdict on any of them makes the whole run not a\nhot update. A selector flag still reports one manager. A manager without a\ncustody generation is reported as `legacy`: it cannot preserve its manager-owned PTYs, so the\ncommand says that this is not a hot update and prints `exact`, `fork`, `fresh`, or `drain-only`\nfor every seat. This report sends no stop, preservation-commit, or replacement command.\nIt does not preserve a running PTY on a legacy manager. The built-in pty runtime spawns\nin-process on every platform and reports `legacy`. On Linux it still adopts seats that an earlier\nmanager left under a detached custodian, but it starts no new custodian. An incompatible native\n`@lydell/node-pty` or ConPTY ABI break remains an explicit per-seat maintenance cut.\n\nWith `--self`, the selected running manager is reported before any global install. When a newer\nrelease exists, Cotal then installs the exact version it validated, resolves and verifies that\npackage in npm's global root, then launches that binary with the same `--space` / `--server` /\n`--creds` selection to reconcile connectors and first-party extensions to the new generation. An npx\nor dev-clone invocation therefore installs and continues through a separate global copy; it never\nclaims the already-running process changed. If the binary is current, `--self` performs the normal\nlocal reconcile without reinstalling it.\n\nThird-party extensions are listed with their installed version and recorded spec but are not\nauto-updated in v1. Floating third-party updates require `@cotal-ai/*` peer-range validation and are\na future follow-up. A failed connector/extension install, npm metadata check, or requested global\ninstall is reported and makes the command exit nonzero. Independent extension attempts continue so\nthe output includes every failure; an unavailable npm registry does not undo a completed local\nreconcile, but the command still exits nonzero because it could not establish that the install is\ncurrent.\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>] [--runtime <name>]\ncotal up --user-auth --idp <url> [--exchange-public-port <n> --exchange-public-url <https://\u2026> [--exchange-trusted-proxy]]\ncotal up --tls-cert <cert.pem> --tls-key <key.pem>   # serve broker TLS (both, or neither)\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | none | Bind host override for a **fresh** broker boot: an IP or hostname only, never a URL (that is `--server`) and never `host:port` (the port comes from `--server` or its default); a URL or port-bearing value is refused pointing at the right flag. With no `--server`, the broker URL is derived from it, so `--host <addr>` alone is enough to make a mesh reachable at that address; a `--host`/`--server` pair naming different addresses is refused. A wildcard bind (`0.0.0.0`, `::`) keeps a dialable loopback URL. Recorded on the mesh and reused by every later manager launch, so a repair or resume keeps remote [`attach`](#managed-seats) working. A live refresh (`\u2713 mesh already running`) does not rewrite `.cotal/auth/server.conf` or rebind nats; stop the broker, then re-run `up --host` |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | none | JetStream store directory (recorded; a repair up reuses it) |\n| `--max-file-store <bytes>` | nats-server's dynamic cap | JetStream file storage cap in bytes (a positive integer, no unit suffix). Without it nats-server sizes the store at start as three quarters of the free space on its filesystem. The cap is fixed at broker start: a running broker cannot change it (`cotal down` first), `down --preserve-state` keeps it for the resume, and a resume with a different value is refused. Not accepted with `-f` |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--restore <dir>` | none | Restore a completed offline backup before exposing the normal listener |\n| `--restore-only registry` | artifact selection | Restore only the registry component |\n| `--accept-missing-source` | off | Explicit disaster consent when the inode-bound preserved source is absent |\n| `--accept-stale-checkpoint` | off | Explicit consent to resume a seat whose checkpoint was captured outside its recorded recency horizon |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | none | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--exchange-public-port <n>` | none | With `--user-auth`: add the public exchange face on this loopback port, for an HTTPS reverse proxy to forward to |\n| `--exchange-public-url <https://\u2026>` | none | With `--exchange-public-port`: advertise the reverse proxy's HTTPS URL in discovery |\n| `--exchange-trusted-proxy` | off | With `--exchange-public-port`: attribute public failure buckets to the last `X-Forwarded-For` hop. Enable only when the listener is reachable solely through a trusted proxy; otherwise the socket address is used |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--tls-cert <path>` | none | PEM certificate to serve TLS with. Must be given together with `--tls-key`. Before starting the broker, Cotal checks readability, private-key mode, key/certificate match, the validity window, and host coverage. `nats-server` accepts an expired certificate and leaves the failure to clients, so Cotal performs these checks first. The decision is recorded; a later bare `cotal up` keeps serving TLS |\n| `--tls-key <path>` | none | PEM private key for `--tls-cert`. Refused if group- or other-readable (tighten to `600`) |\n| `--file <cotal.yaml>`, `-f` | none | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <name>` | `pty` (or the manifest's, with `-f`) | Agent runtime for the mesh manager (`pty` built in; others are installed extensions, explicit-only). Resolved + probed before the broker starts; an uninstalled/unreachable runtime fails loud. With `-f`, overrides the manifest's runtime |\n| `--max-sessions <n>` | 64 | Live-session ceiling for the mesh manager. Each console pane and each `cotal attach` is one session, so size for agents \xD7 panes, not agent count. Recorded on the mesh and reused by every later manager launch, so a repair or resume does not silently drop back to 64. A running manager cannot change it: `cotal down` first, then `cotal up --max-sessions <n>` |\n| `--no-manager` | off | Broker-only boot: start the broker and, in auth mode, the delivery daemon, and no local manager. A refresh under the flag of a mesh whose manager is live refuses rather than keeping or stopping it (`cotal down manager` first). Cannot be combined with `--runtime`, `--max-sessions`, or an agent-declaring manifest |\n| `--rotate-sys` | off | Rotate the space's system account and re-mint its two `$SYS` creds. Needs a stopped mesh; refused with `--open` |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). `--no-manager` is the broker-only mode: it boots\nthe broker (and the delivery daemon in auth mode) and starts no manager, so there is no manager\npidfile to leave stale. A refresh under the flag of a mesh whose manager is live refuses rather\nthan keeping or stopping it: `cotal down manager` first. For a split topology with a manager, wait for `.cotal/manager.<spaceKey>.log` to contain `\u2713 manager up`, then `cotal down manager` on that\nhost and run [`supervise`](#supervise) against the remote broker; see\n[Run a mesh](run-a-mesh.md). `cotal up --detach` prints `\u2713 running in the background:` with\n`manager` listed (pidfile liveness, not a teardown boundary); with `--no-manager` the line lists\nonly what actually started. Ctrl-C on a foreground `up` stops the stack and reports managed agents\nunder the same rule as bare `cotal down` (see [`down`](#down)): when the manager cannot prove it can\nspare, Ctrl-C refuses the teardown, prints the refusal with the reap route, and leaves the stack\nrunning. The `-f` form is a\n[manifest deploy](#manifest-deploys).\n\nA repair `up` on a mesh whose broker died reopens the store its record names, and refuses a\ndifferent `--store-dir` rather than silently opening a second store.\n\nThe generated `.cotal/auth/server.conf` is written on a real broker boot and is not an\noperator-owned config. `--host` changes that file only when nats is actually started. A unit\nrestart that leaves an answering listener in place is a refresh, not a rebind.\n\nOn an existing mesh, `cotal up` reconciles the presence and lease bucket TTLs. It writes a reserved\ncanary and waits for the bucket to expire it before reporting success. If the broker accepts the\nstream update but the backing store does not persist or enforce it, `up` exits nonzero with a TTL\npersistence error instead of trusting the value returned by stream info. A refresh that restores a\nmissing manager says so with its pid (`\u2713 restored in the background: manager (pid N)`); a refresh\nthat finds everything already running prints only the `\u2713 mesh \"<space>\" already running` line.\n\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker: the NATS\nauth callout plus its capability-gated local exchange, and optionally the closed public exchange\nface configured by the three `--exchange-*` flags above. The service is torn down with `cotal down`,\nand a re-run of `cotal up` heals a dead service on a running broker. `up` waits for the service to\nfinish binding: while the daemon it launched (or found running) stays alive, the wait extends past\nthe base 15s up to 60s; a daemon that exits is refused at once with \"exited before becoming ready\",\nand one alive past 60s is refused as \"alive and still starting\" (wedged), naming the pid record and\nthe service log. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n`--rotate-sys` renews the two `$SYS` credentials (`membership-observer`, `connection-evictor`).\nThey carry a 30-day expiry and nothing re-signs them in place, because the system-account seed is\nnever persisted, so they are renewed by issuing a **new system account** under the same broker\noperator and minting fresh creds against it. A plain re-`up` does **not** do this: it reuses the\nexisting trust record, and its `$SYS` creds along with it.\n\nThe rotation is safe to run on a real space, with one operational cost. The data account, the account\nsigning key, every agent credential minted from it, and the JetStream store are all untouched; what\ndies is the retired system account, and with it any out-of-band copy of the old `$SYS` creds, on every\nbroker that loads the rotated config. The cost is that **earlier full backups stop being restorable**\n(see below), so this is not a no-consequence operation. It needs the broker to restart on the rewritten\nconfig, so it runs as part of a boot:\n\n```bash\ncotal down\ncotal up --rotate-sys --detach     # agents reconnect; nothing is re-provisioned\ncotal doctor auth                  # both $SYS creds healthy again, 30 days out\n```\n\nA rotation is a stopped, fresh boot, and anything that is not one refuses it, all for the same reason\n(the on-disk material and the broker it runs on must never end up on different generations):\n\n- a live mesh, because the running broker would keep serving the retired account;\n- an open mesh, whether that comes from `--open` or from `broker.auth: false` in a manifest, which\n  has no system account at all;\n- `--restore`, because reinstating a trust root and superseding it in one command leaves no way to\n  say which authority the mesh came up on;\n- an unfinished restore or resume attempt on this root, including one `cotal up` would recover on\n  its own, because those paths can adopt a live listener and return without booting a broker;\n- a root that hosts more than one space, because the system account lives in the shared broker\n  record and a rotation would retire every tenant's, while the root holds one `$SYS` cred pair\n  pinned to one data account.\n\nTwo things to know before you run it:\n\n- **The retirement is config-load-bound.** Old `$SYS` creds are refused by any broker that loads the\n  rotated config. A stale `nats-server` still running the *previous* config in memory would keep\n  honouring them, so stop every broker for this root first. `--rotate-sys` refuses if this root's\n  mesh is recorded as running, if anything unidentified is answering at the address it was given, or\n  if the root's pid file names a live (or unreadable) process. Those are Cotal's own ownership\n  records, not a scan of the process table: a `nats-server` you started by hand against this root's\n  `server.conf` on some other port writes none of them and will not be seen. Do not run one.\n- **It invalidates earlier full backups.** A full artifact binds to the trust chain it was taken\n  against, and that commitment covers the operator JWT and the system account. Every full backup\n  taken before a rotation refuses to restore afterwards, so take a fresh `cotal backup` once the\n  rotated mesh is up. `cotal up --restore` names this case when the data account still matches.\n\nThe commit is not atomic (a trust-record write plus two credential writes), so an interrupted\nrotation leaves the record ahead of the creds. That split is detected rather than silent: every\n`cotal up` on an auth mesh, and every `cotal doctor auth`, compares each `$SYS` cred's issuer against\nthe persisted record and names the retired account. `up` warns rather than refusing, because these\ncreds power the membership graph and live eviction, both of which degrade fail-soft; the mesh is not\nworth taking down over them. Re-running the rotation heals it, at the cost of one generation.\n\nWhile those creds are expired the mesh keeps delivering messages, but the\n[membership feed](delivery-daemon.md) and live connection eviction stay down; `cotal doctor auth`\nand the manager's log both name the credential and this repair.\n\n## down\n\n```bash\ncotal down\ncotal down --with-agents\ncotal down --preserve-state [--store-dir <dir>] [--session-store <dir> \u2026]\ncotal down manager [delivery auth web nats ...]\ncotal down web [--space <name>]\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | none | Tear down this manifest's deploy |\n| `--run <id>` | none | Tear down one `spawn -f` run by id |\n| `--space <name>` | current mesh | With components: the mesh whose target-addressed components (e.g. `web`) to stop |\n| `--dry-run` | off | Print the manifest teardown or selected components, mutate nothing |\n| `--with-agents` | off | Bare whole stack only: also stop and deprovision every managed agent |\n| `--preserve-state` | off | Bare whole stack only: fence the manager, retain principals and durable state, stop and prove the stack down, then publish `ready` |\n| `--store-dir <dir>` | `.cotal/nats` | With `--preserve-state`: the actual store path (required for a custom store) |\n| `--session-store <dir>` | none | With `--preserve-state`: a harness transcript store directory to capture with every continuation-capable retained seat. Repeatable. No default and never inferred from a connector name; a path that does not exist or is not a directory is refused before anything stops |\n\nBare `cotal down` stops the whole local stack in dependency order and leaves managed agents running\nwhen their runtime lets them outlive the manager. Before signalling the manager it verifies the spare\ncapability of the exact recorded manager, which records what that manager's stop does with its\nseats, and it reports the agents left behind plus `cotal down --with-agents` as the explicit reap.\nThe built-in pty runtime keeps each PTY inside the manager process, so those seats cannot outlive\nit: every manager stop stops and deprovisions them, and `down` reports them as stopped. Ctrl-C on a\nforeground `cotal up` follows the same rule: it verifies the spare capability, stops the stack, and\nprints the same report. When the capability cannot be verified, Ctrl-C\nrefuses the teardown and leaves the stack running; end it with `cotal down --with-agents`.\n`--with-agents` is a one-shot destructive policy bound to the exact verified manager process\nand the exact live `down` stop reservation; a stale, malformed, crashed, or different stop attempt\ncannot turn a later bare shutdown destructive. If a managed agent cannot be proven stopped within\nthe manager's stop timeout, the manager logs which one, still closes its broker connections and\nconsole listener, and exits with code 1. It does not release its pidfile, liveness lease or\nservice registration in that case, so no successor is handed authority while that agent may still\nrun; the lease lapses on its TTL. Positional component names stop\nonly those self-registered local processes; for example, `cotal down manager` leaves delivery and\nthe broker running, and `cotal down web` is available when the web extension is installed. A\ncomponent that starts target-resolved (the web dashboard) is stopped the same way: `cotal down web`\nresolves the mesh the same way as `cotal web` (registry current mesh first, `--space` to name one), so\nit works from any directory; the other components always stop under the folder you run it in. The\n`-f` / `--run` forms tear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh\nand cannot be combined with component names. Stopping `nats` alone is refused while an unselected\nregistered daemon is still live; include those components or use bare `cotal down`.\n\nA pinned manager with no spare-capability record is not signalled by bare `cotal down` or `cotal\ndown manager`. A current manager always publishes the record, so a missing one means an older\nmanager: one that predates capability reporting, or one whose pty runtime reported that it cannot\ndetach its agents. Stop each managed agent explicitly, then run `cotal down --with-agents` from the\nmesh root to stop the whole stack. An older manager does not understand\nthe reap request, which is why the agents must already be stopped.\n\nBare `cotal down` inventories by pidfile. When this folder's registered broker answers and no\n`nats.pid` records it, the command does not say nothing is running. It names the space and the\nbroker address, says no pidfile records that process, says it will not stop a process it did not\nstart, and exits 1. Stop that broker with whatever started it (an init unit, a container, or the\nhand-run process). `cotal meshes rm <space>` only drops the registration. The probe runs whether or\nnot other owned components were running: they stop and clear their artifacts first, then the broker\nis named. A component stop and `--dry-run` stay pidfile-only and do not probe.\n\n**Teardown verifies pinned process identity before signalling.** PIDs are recycled by every OS,\nso a recorded pid alone is not a durable target identity. `up` records each stack process's\ncreation identity in a sibling `<pidfile>.identity` pin, which holds the pid and the process start\nreported by the OS. Every stop path, including `down` for the broker, web and extension components,\nand the manager, delivery and auth-service stops, applies the same rule. A pin that names a different\nstart means the pid was reused, so teardown refuses and preserves it. A torn or unreadable pin also\nrefuses.\n\nThe pidfile and its pin are published by renames, and the pidfile rename is the commit point. Just\nbefore it, the pin holds two lines: the old process's and the new one's. A launcher that dies\nmid-publish therefore leaves the old record or the new one, each checked against its own pin line,\nnever a pidfile without its pin. An old record with no pin is legacy, so its line holds `-` in place\nof the token and it stays legacy until the commit. A CLI older than this change reads a two-line pin\nas torn and refuses.\n\nPublishes of one pidfile are serialized by a lock file beside it, `<pidfile>.publish.lock`, because\nthe launcher and the daemon it starts both publish the same record. The next publisher reclaims a\nlock left by a crashed one. When no start token can be read for the new process, its pin line holds\n`-` in place of the token, which reads as a legacy record, and the publish ends in the legacy shape:\na pidfile with no pin. Teardown, and a daemon removing its own record on exit, take the same lock and\nremove the record only while the pidfile still names the pid they stopped, so a stop that races a\npublish leaves the new record whole.\n\nThe pidfile pid and the pin pid are two coordinates. Automatic cleanup follows **proven death of\nthe pidfile target** (ESRCH on that pid): a torn sibling pin does not wedge a dead pidfile pid.\nA torn pairing where the pin names another pid, while the pidfile pid is still live or not proven\ndead, still refuses. Inspect both pids with `ps`. Do not delete `<pidfile>.identity` to force a\nstop; that weakens target-identity protection. Once the pidfile process is dead, rerunning\nteardown clears the stale record automatically.\n\nThe first teardown after upgrading a running pre-pin stack has a narrower guarantee. A live record\nwith no identity pin is signalled after a loud warning that it predates identity pinning. Restarting\nthe component writes the pin, so later teardowns receive full match and mismatch protection. The\nsame warning applies on platforms where no stable start token is available. For a legacy manager,\nbare `cotal down` also warns that agent sparing cannot be verified before it signals. Because the\nCLI cannot establish which SIGTERM handler that already-running binary carries, it never presents\nthe pre-signal seat inventory as confirmed spared; a genuinely older destructive handler may still\nreap those agents. `--with-agents` publishes a one-shot reduced-guarantee handoff bound to the\nrecorded manager pid and the live `.stopping` reservation's inode, then signals unconditionally.\nThat handoff cannot be replayed by a later stop attempt. A pin that exists and does not match the\nlive process still refuses before signal.\n\n`--with-agents` performs the old destructive logical teardown: managed processes stop and their\ncredentials, ACL rows, and delivery footprints are deprovisioned. `--preserve-state` is a different\nmaintenance transition: it stops retained processes while suppressing leave/deprovision cleanup, persists the manager's\nsame-principal resume inventory, stops the entire stack without removing run/auth artifacts, and\npublishes a stable inode-bound cut only after every recorded process is proven stopped and the exact\nrecorded NATS endpoint is unreachable. A missing or stale broker pidfile never counts as stopped. The\nattempt is bound durably before the manager is fenced, the resume document and attempt-bound\n`cut-intent` are fsynced before manager commit, and the manager's commitment itself is journaled\n(`cut-committed`) before any process stops. A retry after a crash at any of those boundaries reuses\nthe exact recorded attempt and finishes the remaining stop and endpoint proofs idempotently, without\nneeding the (by then intentionally dead) manager. A partial cut never publishes `ready`. It cannot\nbe combined with component names, manifest teardown, or `--dry-run`.\n\n**Seat checkpoints.** After the stack is proven down, the cut writes one checkpoint per retained\nseat under `.cotal/maintenance/v1/checkpoints/<attempt>/<seat>/`, and prints the path, the\ncontinuity class and the generation for each. The path carries the preservation attempt because a\ncheckpoint is immutable once sealed: a shared directory would make the second cut in a root refuse\non the first cut's leftovers, and clearing it would destroy an artifact a rollback still needs. The\ncapture happens only at that point because anything earlier races a harness that is still writing\nits transcript and its working tree.\n\nEach checkpoint directory is created 0700, refuses a destination that already exists, and holds:\n\n- `repo.bundle`, the seat `cwd`'s reachable history, anchored on the base commit the record names\n  by full object id;\n- `repo.index.diff` and `repo.worktree.diff`, the staging state as two diffs, base to index and\n  index to worktree. Two rather than one because a single combined diff restores a mixed tree with\n  the right bytes and the wrong index: a source reporting `MM README` would come back as ` M README`;\n- `repo.untracked.tar`, the untracked files in scope;\n- the harness session pointer, when the seat's connector declares one, and the transcript store\n  files the operator named with `--session-store`. Each records where the destination puts it back\n  as an anchor (the workspace root, the account home, or the seat's `cwd`) plus a relative path,\n  because the destination's root and home are its own and the source host's absolute spelling would\n  either miss them or write outside them;\n- `checkpoint.json`, written last, after every digest is computed over the bytes that landed.\n\nThe record carries the manager's resume entry unchanged as its first field, then the space, the seat\nname, the recovered `lifecycleUid`, the writer generation the cut was taken at, `capturedAt`, the\nrecency horizon, the applied profile revision, the seat's `git status --porcelain` as the cut read\nit, and the continuity class. Every captured file is\nlisted with its byte size and sha256, so an operator verifies the whole artifact with `sha256sum`\nand `git bundle verify`. No secret values, no operator keys and no source-host launch material\nenter it.\n\nThe continuity class is what the connector declares, capped by what the checkpoint carries. A\nconnector declaring session continuation classifies as `exact`, but reopening a session takes both\nhalves, the pointer that names it and the store that holds its transcript. A checkpoint missing\neither one cannot reopen that session, so it is recorded as `fresh` when the connector declares a\nfresh start and `drain-only` otherwise. A pointer with no store is capped the same way as a cut\ncarrying neither, because it names a session whose bytes the artifact does not contain. A class is a promise the destination is entitled\nto act on, so it never describes bytes the artifact does not contain. The transcript store stays an\noperator input: this repository does not know where a harness keeps its transcript, so `exact`\nrequires `--session-store` to name one.\n\nThe recorded status is read under the same selection rule as the untracked set, so it describes the\nstate the captured bytes can reproduce. The destination re-reads it in the promoted tree and refuses\na difference.\n\nThe untracked selection rule is recorded in the record and is\n`git ls-files --others --exclude-standard -z, excluding .cotal/`. It honors `.gitignore`, so an\nignored file the seat needs does not travel and has to be moved separately. The `.cotal/` exclusion\nis a secrecy boundary rather than a size one: when a seat's `cwd` is also the mesh root, the control\ndirectory is untracked, and without the exclusion the broker trust material, the space account, the\nmanager instance identity's private seed and the seat's own credentials would land inside the\nartifact. A checkpoint carries credential references only; the destination resolves that material\nitself.\n\nA seat whose launch options could not be resolved is refused rather than checkpointed, with the\nmanager's own wording: `imperative launch options have no non-secret durable source (<keys>)`. The\nrefusal arrives at prepare time, so the cut stops before any child does.\n\nA delegated seat (SPEC \xA713.17) is refused at prepare time too, with\n`a delegated seat is not resumed by a later manager; stop it before preserving`. A manager stop\nafter a refused cut retires that seat through its retirement path.\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\ncotal clean restore-attempt --attempt <id> --force\ncotal clean restore-fallback --attempt <id> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | none | Required: destructive, no prompting |\n| `--attempt <id>` | none | `restore-attempt`: exact stale pre-commit attempt; `restore-fallback`: matching healthy committed restore |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive or any same-root recorded broker endpoint remains reachable (run `cotal down` first). They\nalso refuse outright on a root that holds accounts for several spaces: the store and the broker\ntrust record are shared by every space on the broker, so both targets would take out all of them\nand no `--space` can narrow that. `down`, `backup` and `up --restore` refuse there for the same\nreason. `cotal status` lists the tenants on such a root. Personas\n(`.cotal/agents`) and logs are never touched. The mesh record now carries a custom\nstore location for `up`'s own repair, but `clean` still takes `--store-dir` itself; `clean` does\nnot read the record. Custom cleanup targets must contain either the Cotal store-generation marker or a\nreal `jetstream/` store directory; filesystem roots, project roots, and Cotal auth/maintenance trees\nare always refused.\n\n`store` and `all` also refuse every maintenance journal state. After a healthy committed restore,\n`restore-fallback` is the only supported way to remove the recorded unchanged old-store inode; it\nnever deletes the active target, requires both the exact attempt id and `--force`, and retires the\ncompleted restore journal so a later `down --preserve-state` can start a new backup cycle.\n\n## Backups\n\n```bash\ncotal down --preserve-state [--store-dir <dir>]\ncotal backup create <dir> [--only full|registry] [--store-dir <dir>]\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\n```\n\nBackup is offline-only. It requires the stable `ready` record from `down --preserve-state`, an exact\nstore match, no live recorded process, and an unreachable exact endpoint from the recorded cut.\nThat endpoint is probed immediately before cloning, so a live broker with a missing or stale pidfile\nis still refused. It claims the cut, reflink/copies the stopped source to a\nprivate attempt clone, and opens only that clone on a random loopback bootstrap broker with an\nindependent parent/deadline watchdog. It validates the canonical stream and pull-consumer inventory,\nwrites native snapshots with consumers excluded, and stores conservative contiguous ACK-floor\ncheckpoints separately. The presence bucket is memory-backed, so it does not survive the cut and\nthe clone may lack it. Every other stream must be present. The original store is never opened by\nthe backup broker, and the stack is not restarted implicitly. Artifact destinations must not overlap\nthe preserved source or maintenance\nattempt tree. Restore artifacts and targets likewise cannot nest inside or contain each other, the\npreserved source, or the maintenance attempt tree.\n\nStopped client-managed KV ordered consumers are ephemeral read residue, not backup state. Backup\nignores only the pinned client's exact stopped shapes: ordinary last-value watchers and the\nwhole-bucket scanner that uses all-history delivery to collapse concurrent tombstones. A bound\nconsumer or any lookalike with a different filter, inbox, lifetime, or other config is still refused.\n\n`full` is the default and indivisible: channel registry, CHAT/DM/TASK/INBOX/DLV, ACL, MEMBERS, and\nvalidated durable checkpoints. `registry` is the sole partial artifact. Presence, derived membership\nfeed, leases, native ephemeral/history consumers, credentials, keys, tokens, owner secrets, and actor\nledger files are excluded. `full` means every transferable message and registry stream, not every\nJetStream resource: endpoint submissions/facts/events/timers/workflow state, contract artifacts, and\nthe records/auth/session stores are nonportable control state. Restore recreates those streams empty\nwith their canonical configs before exposing the normal listener, so active endpoint runs,\nlifecycles, and sessions do not cross a backup. Artifacts are exclusively created `0700`;\nsnapshot/checkpoint files and\nthe manifest are `0600`; `manifest.json` is written last with exact sizes and SHA-256 values. The\ndirectory is trusted operator input: hashes detect corruption, not malicious rewriting.\n\nRestore validates and stages the exact allowlisted artifact bytes before moving or creating a store.\nIt requires the same space and existing trust state. The whole pre-commit window holds a journaled\nliveness claim (coordinator, watchdogs, brokers, absolute deadline): ordinary `up` and a repeated\n`up --restore` refuse while the claim is live, and a stale attempt is recovered only after the\ndeadline has elapsed and every recorded owner is proven dead. A retried `up --restore` handles this\nautomatically; an operator can also recover it explicitly with `cotal clean restore-attempt --attempt <id> --force`. Nothing\never rolls back a live attempt. A registry-only artifact restores as registry-only whether or not\n`--restore-only registry` is passed; omitted infrastructure is always created and the exact\npost-restore stream inventory is asserted before commit intent. Ordinary `up` from a preserved cut\nresumes only the exact recorded source store and runtime; a contradicting `--store-dir` or\n`--runtime` fails in preflight.\n\n**Admitting a seat checkpoint.** An ordinary `up` from a preserved cut admits that cut's seat\ncheckpoints before it journals the resume attempt and before any process starts, so a refusal costs\nnothing. Three gates run in order, each naming what it saw.\n\n1. *Integrity.* Every file the record names must be present, a regular non-symlink file, the\n   recorded byte size and the recorded sha256, re-stat'd after the read so a file that moved is a\n   refusal. Failure here consults no other gate.\n2. *Identity.* The recorded space must match, the recorded `lifecycleUid` must not belong to a live\n   incarnation, and the profile revision must match this host's or be resumed under deliberately\n   this host's. A differing revision is refused with both digests and the remedy, and there is no\n   override: the checkpoint carries the recorded digest and not the config bytes, so nothing could\n   run the seat under the recorded revision, and the manager re-digests the same file and refuses\n   drift on its own. This gate has no blanket override, which is the only reason the next one may\n   have one.\n3. *Recency.* `capturedAt` is compared to this host's clock against the horizon the record carries.\n   Inside it, the seat resumes. Outside it, `up` refuses and prints the capture instant, the clock\n   reading and the horizon; `--accept-stale-checkpoint` admits it anyway and the exercised consent\n   is printed with the actual age. An unreadable `capturedAt` is refused with no override, because a\n   freshness gate that fails open is not a gate.\n\nCustody transfers only after all three pass. The destination claims the recorded generation plus one\nby exclusive create, before it launches anything. A lost create means another destination is already\nclaiming that seat, and it refuses with `seat-writer-generation-create-lost` rather than adopting\nthe winner and becoming a second writer. The recorded `lifecycleUid` is reused and never minted, so\nthe resumed seat binds the same lifecycle-keyed durables.\n\nAdmission is reconciled against the inventory the resume is about to hand the manager, and that\nreconciliation finishes before the restore moves a single tree. A checkpoint whose recorded\n`lifecycleUid` is not the one the retained inventory carries describes a different incarnation of\nthat seat, and it refuses with both uids while every live working tree is still untouched and no\ngeneration is claimed. A retained\nseat with no admitted checkpoint refuses the resume by name: an absent checkpoint directory and an\nabsent record are indistinguishable from a seat that was never checkpointed, and a seat that starts\nwithout passing the gates has claimed no generation. `--accept-stale-checkpoint` is recorded in the\nresume journal with the seat, the capture instant, the admitted age and the horizon, so the consent\nsurvives the terminal it was typed into.\n\nThe whole admission is all or nothing. Coverage is settled first, then every gate runs over every\ncheckpoint, and only then is any generation claimed. A refusal at any point leaves every generation\nunclaimed, including a lost exclusive create during the claim itself: the claims that attempt made\nare removed before the refusal is raised, by the exact paths it wrote, so a generation another\ndestination holds is never touched. A claim is a create that can never be made again, so a refusal\nthat left one behind would consume the retry over the same checkpoint set.\n\n**Restoring a seat checkpoint.** Once every gate has passed over every checkpoint, and before a\nsingle generation is claimed, `up` puts each admitted seat's captured bytes back. A refusal here\ncosts nothing for the same reason a gate failure does: no claim has been made and nothing has\nstarted.\n\nA restore never moves or replaces the destination's own control directory. A checkpoint excludes\n`.cotal/` by design, so a seat whose `cwd` holds one, which is the layout an operator gets by\nrunning `up` and `spawn` in a single directory, is refused before anything is staged: promoting a\ntree that cannot contain `.cotal/` over that `cwd` would carry this host's live trust material and\nmaintenance state away with the superseded tree. The refusal names the control directory it found\nand the remedy, which is to give the seat a working tree that is not a workspace root.\n\nEach seat is staged beside its own `cwd`, in `<cwd>.incoming`:\n\n1. every recorded digest is verified again over the files as they are now;\n2. the bundle is cloned into `<cwd>.incoming`, which is refused when that path already exists;\n3. the recorded base commit is verified in the clone and checked out detached, so a bundle that does\n   not contain it stops the resume instead of continuing against a different history;\n4. the index diff is applied with `--index` and the worktree diff without it, both `--binary\n   --allow-empty`. That order is what puts staged content back in the index rather than only in the\n   worktree, and `--allow-empty` is why a seat with a clean tree is still restorable;\n5. the untracked archive is extracted.\n\nEvery seat stages before any seat is promoted. Promotion moves an existing `cwd` aside to\n`<cwd>.superseded.<timestamp>` and renames the staging directory into place, then puts the session\npointer and store files where the destination's connector reads them, then re-reads\n`git status --porcelain` in the promoted tree and compares it to the status the checkpoint recorded.\nA restore that applied without error and produced a different index is a refusal, not a warning. The\ntwo renames are the only steps that touch the path the seat will use, so a failure anywhere leaves\nevery seat's live `cwd` as it was.\n\nThe rename itself claims the superseded name, and a taken name gets a numeric suffix. The timestamp\nhas one-second resolution, so two promotions of the same seat within one second compute the same\npath; a rename onto a name that already holds a tree fails on every platform, and that failure is\nread as taken. Nothing creates the name ahead of the move, because Windows refuses to rename onto an\nexisting directory at all. A superseded tree is the thing that rename exists to keep.\n\n`git` and `tar` run as child processes with argument arrays, never a shell string.\n\nA leftover `<cwd>.incoming` refuses the resume by name. A staging directory from a failed run is the\nonly record of what failed, so nothing removes one automatically: inspect it, remove it by hand, and\nresume. A pre-existing `cwd` is renamed rather than deleted, so a wrong checkpoint costs a rename\ninstead of a tree. When a promotion fails, the renames that attempt made are undone and the staging\ntree is left where it is, as the evidence for what did not verify.\n\nA session pointer whose recorded `sessionId` is not the one the retained inventory reopens is\nrefused before anything is cloned. A session file already present at its destination is judged by\ncontent: bytes equal to the recorded digest are already restored, and different bytes under the path\nthe connector is about to read are refused with both digests rather than clobbered.\n\n`up --restore <dir>` reaches the same admission and the same restore, after the store is restored\nand validated and before commit intent is journaled. A registry-only restore resumes no seat, so it\nadmits and restores nothing.\n\nOne limit is worth stating plainly. The writer generation is claimed by exclusive create inside one\nworkspace root, so it fences two resumes on the same host and does not fence two independent\ndestinations: copy a checkpoint to two roots and both claim the same successor. A real cross-host\nfence needs a coordinate neither root owns.\n\nAuthenticated restores validate the complete\nspace trust bundle before staging, including nkeys, seed matches, JWTs, signers, and space binding;\nfull restores commit to the validated operator, system-account, data-account, and active-signer root\nchain in addition to the static/user authority fingerprint. Because the system account is part of that\ncommitment, a [`cotal up --rotate-sys`](#up) makes every full artifact taken before it unrestorable\nagainst this root: take a fresh full backup after each rotation. The composed commitment is revalidated\nimmediately before store mutation and never includes secret seeds. Restore never creates fresh auth.\nSame-path restores atomically retain the old\nsource at the journaled fallback path; alternate targets retain it in place; a missing canonical\nsource needs explicit `--accept-missing-source`. Quarantine and target restores use current canonical\nconfigs on isolated random-loopback brokers, never expose native snapshot consumers, and publish a\ncommit-intent immediately before the normal listener starts. Archive bytes never instantiate the real\ntarget: after quarantine validation, every stream is re-snapshotted from the validated quarantine\nstate into attempt-owned sanitized files, and the target is restored solely from those. Before that boundary, failure rolls back\nthe attempt-owned target; after it, ambiguity preserves both stores and records forward-repair\nrecourse. The cooperative maintenance lock excludes Cotal commands, not arbitrary raw NATS processes.\n\nBootstrap brokers in every auth mode, including open, mount the store under a local account with\nrandom operation-specific logins only, each carrying the exact per-phase subject permission matrix;\nnormal static credentials and user-auth sentinel/bearer connections are rejected, and no auth\nservice or callout starts. Open mode differs only in its account label, never in authority. Inventory, each stream snapshot,\nrestore initiation, exact upload id, validation, and each checkpoint recreation use separate exact\nauthorities. Every checkpoint carries the source stream's message/first/last sequence state and must\nmatch its snapshot record before mutation; core then derives and validates the only allowed start\npolicy. TASK is not a CLI exception: the same core checkpoint API recreates its canonical `DeliverAll`\nWorkQueue durable because acknowledged tasks are absent from retention and NATS forbids a\nstart-sequence policy there. Registry-only restore creates every omitted canonical stream and transient\nbucket on the isolated target before the normal listener is exposed. It deliberately does not resume\nretained agents or recreate their DM/DLV/TASK/ACL state; their identity material stays retained and\nstopped rather than being reprovisioned into a partial restore.\n\nAfter listener readiness, the manager starts attempt-bound, validates retained credentials/tokens\nwithout granting or reprovisioning, and resumes the exact persisted principals under cleanup\nsuppression. Registry-only restore uses the same flow with an empty agent set. On a user-auth mesh\nthese manager calls run as the logged-in operator's `cli` actor, the caller the preserve cut used, so\nthat actor needs a current `admin` grant. `commitResume` is an\nidempotent validation barrier only: success must be `awaitingFinalize` with an attempt-bound 64-hex\ncommit token and does not release suppression. Under the workspace lock, the CLI first fsyncs that\nexact evidence as `manager-committed` (restore) or `resume-committed` (ordinary resume), then calls\ntoken-bound `finalizeResume`; only an `active` response for the exact token releases suppression. The\nCLI records the same token in finalization evidence before a restore becomes `active`, or before an\nordinary resume retires and consumes the marker. Re-entry from either committed state skips the prior\nidempotent activation/commit phases, retries finalization with the durable token, and finishes the\nworkspace transition. Failure before finalization preserves the committed state and cleanup\nsuppression; it is not rewritten through a degraded transition. Re-entry between any two earlier\nboundaries reuses the same attempt and may retry the idempotent phases without deleting retained state. A missing or\nchanged per-agent dependency is a named fail-closed result; the journal becomes degraded and remains\navailable for forward repair. A retry from `resume-intent`,\n`resume-active`, or `resume-degraded` reuses the same attempt and inventory after the prior listener is\nproven stopped. A retained agent the lost manager already launched can still be running, for example\nin a tmux window, while the journal reads `resume-intent`. On a static mesh the replacement manager\ncloses that seat through the reference the lost manager recorded on the agent's slot, waits for the\nprincipal to leave presence, and launches it again. A live principal with no such record, or one that\nstays live after the seat is closed, is refused. Every normal restore listener has an unguessable\nattempt-bound NATS server name. The CLI fsyncs its exact name/nonce, canonical endpoint, process owner, and generation-bound target identity\nimmediately after spawn. Re-entry accepts a surviving listener only when its INFO server name, live PID\nrecord, endpoint, and target identity all match that proof; degraded restore repair then moves through\nthe guarded workspace transition only after manager commit. If an uncommitted bound owner is provably\ndead, recovery retires that exact proof under the maintenance lock and binds a fresh listener for the\nsame attempt, endpoint, and target with a new nonce and server name. A live foreign/mismatched listener\nor ambiguous owner is preserved and refused, never adopted by reachability alone. A reconstructed\ncommit/degraded attempt without either the exact bound proof or a durable dead-listener replacement\nrecord fails closed even when the recorded port is free. A later ordinary startup may pass an `active`\nrestore only when its details prove manager commit and its exact recorded listener is dead.\n\n## Mesh registry\n\n```bash\ncotal meshes [--json]\ncotal meshes add                      # guided, on a terminal\ncotal meshes add <space> --server <url> [--root <dir>] [--mode auth|open|user] [--tls] [--force]\ncotal meshes add <space> --mode user (--user-auth-file <bundle.json> | --from <https url>)\ncotal meshes rm <space> [<space> \u2026] [--force]\ncotal sync [--idp <auth base URL>]\ncotal use <space>\ncotal status [--space <s>] [--server <url>] [--components]\n```\n\n`meshes` lists the meshes this machine knows; a `*` marks the `current` default a bare\n`cotal spawn` joins. Entries learned from a signed-in account are marked `discovered`. Their\nregistration trust is stored under the account's private auth state, and the registry contains no\nsession token or sentinel credential bytes. Commands resolve the catalog `slug`; a different human\n`name` is rendered only as a label.\n\n`meshes --json` prints one JSON object per recorded mesh per line: `space`, `server`, `mode`,\n`root`, `default` (the `*`), and `origin` (`up`, `manual`, or `catalog` for a discovered entry). A\nlocal or hand-registered entry also carries `offline`. A discovered entry is never probed, so it has\nno `offline` field. `tlsRequired`, `events: \"required\"` and a discovered entry's `catalogName` appear\nonly when the record has them. An empty registry prints nothing and exits 0. The note about a default\nthat matches no record goes to stderr, so stdout carries only rows, on a first run too. The table is\npresentation and is not a stable parsing target. `meshes add` and `meshes rm` refuse `--json`.\n\nA registry record this build cannot use is refused by name, never rendered and never skipped. One\nthat does not parse, or is missing a field every consumer reads (`server`, `mode`, `root`, `ts`,\n`space`), makes every registry command exit 1 with the file's path and what is wrong with it.\nRemove the file or restore the record; nothing repairs or invents a field for you.\n\nAn IdP may advertise a same-origin space catalog during login. Cotal reads the complete snapshot and\nadds every valid registration without a separate `meshes add`. A snapshot younger than five seconds\nis used without a request. After that, commands that resolve a mesh target conditionally refresh the\nsaved catalogs. An operation targeting a discovered space refreshes only that space's account and\nrefuses if that account fails. Operations targeting local or manually registered meshes refresh every\naccount, print one warning for each failure, and continue. `cotal status` refreshes every account,\nnever refuses on a refresh failure, and lists each account as `fresh`, `updated`, `not-modified`,\n`no-catalog`, or `failed` with its error. `cotal sync` bypasses freshness and reports added, changed,\nremoved, unchanged, and name collisions. `--idp` limits it to one signed-in account. It never connects\nto a broker.\n\nThe registry is updated under the same lock that guards the catalog cache, so a command never lists\na discovered space set that another command is still writing. The cache records a fetched snapshot\nas not yet applied before the first registry write and as applied after the last. If a command dies\nor is stopped in between, the next command applies that snapshot again before it can use it, with\nno request inside the freshness window.\n\nThe shared dispatcher applies this preparation to every command that declares both `--space` and\n`--server` as mesh-target flags, including commands registered by other packages and commands that\ndeclare their own equivalent flag objects. Daemon and startup commands that use those names only as\nconfiguration explicitly opt out. Registry-local `meshes add` and `meshes rm` never refresh a catalog.\nWhile the registry holds a record this build cannot use, the preparation neither refreshes nor\napplies a catalog, so the command's own checks run first. A snapshot left unapplied is applied by the\nnext preparation after the record is restored or removed. A command that resolves its target through\nthe registry still refuses the record by name.\n\nRun on a terminal with the space or `--server` missing, **`meshes add` is guided**: it asks for the\none thing that cannot be derived (the broker URL), probes it, and tells you what answered - open or\nrequiring credentials. It then offers the spaces your `--root` already holds credentials for, states\nthe mode as a fact about that broker rather than asking, and shows the exact record before writing\nanything. A broker that does not answer, or a space name already registered, becomes a choice rather\nthan an error. Anything you pass on the command line is taken as given and not asked again. Without\na terminal - a script, an agent, CI - nothing prompts and the flag form's errors stand\n(`COTAL_NO_PROMPT=1` forces that too).\n\n`cotal up` and `cotal down` maintain their own records. `meshes add` registers a mesh they cannot\nspeak for: one running on another machine, a shared broker, a hosted space. `--root` is the folder\nwhose `.cotal/auth` holds that mesh's credentials and whose `.cotal/agents` holds its personas.\nThe default is the project you run it in. The registry stores that path, never a secret. `--mode`\ndefaults to `auth` when the root holds the space's account record and to `open` otherwise. The\nbroker is probed before anything is recorded, so a wrong address, or credentials that mesh will\nnot accept, fails here instead of at the first `spawn`; `--force` records without verifying (and\nreplaces an existing record).\n\nA hostname or public address is registrable only when the connection will **require TLS**. Pass\n`--tls`, or use a `tls://` URL. The scheme is recorded as enforced intent, so every later dial\nthrough the record demands the handshake (and `meshes add tls://\u2026` against a plaintext broker is\nrefused at registration). Without required TLS the fence admits loopback and private-overlay\nliterals only. RFC1918 addresses are refused in both modes because a cafe LAN is private but does not belong to you.\n\nA **user-auth** mesh registers from supplied pinned trust, never guessed: `--user-auth-file`\ntakes the bundle exported where the mesh runs; `--from` asks before it dials the address at all,\nthen fetches its `/.well-known/cotal-mesh` discovery document (HTTPS only), displays the pins, and\nasks again before adopting them. Neither fetch follows redirects: a 302 can move a pinned fetch\nonto plaintext or onto another host, so it is refused rather than followed, and the pinned\nexchange must itself be an `https://` URL, except for an exchange on this machine, where plain\n`http://` is accepted for a loopback *literal* (`127.0.0.1`, `::1`, any spelling of them) but not\nfor `localhost`, which is a name rather than an address. Registration verifies that the exchange\nanswers `/health` and `/jwks` as the pinned issuer. It also verifies that the broker refuses a bare\nconnect; that auth-required refusal is the pass. The sentinel credentials land in a 0600 file under\nthe entry's root; the registry records only the path.\n\n`meshes rm` drops records. It never stops a mesh. For a mesh running on this machine `cotal down`\nis the right verb, and `rm` says so unless you pass `--force`. A hand-added record is removed by\n`meshes rm`, by an `add --force` replacement, or by a `cotal up` that actually starts the broker for that same space, server and root, which becomes that\nmesh and so takes the record over (a `cotal up` for that space anywhere else refuses instead).\nNothing that merely *infers* a record is stale from a dead broker touches it: an\nunreachable broker is listed `offline` and stays, whether `cotal up` or `cotal meshes add`\nwrote the record; a foreground `up` whose broker exits unexpectedly keeps its record the same way.\nA bare command does not treat that offline record as a running mesh;\nname it with `--space` to restart it. `cotal down` / `cotal clean all` still drop an `up` record for the project\nthey tear down; a hand-added one they leave alone even when it shares a root, because nothing\non this machine could write it back.\n\nA discovered entry belongs to the normalized IdP origin and proved subject that supplied it. Local\nteardown, cleanup, and liveness pruning do not remove it. A manual or locally started entry with the\nsame name wins and remains untouched; that discovered name is reported as a collision. Logging out\nremoves only the discovered entries owned by that account.\n\n`cotal meshes` and `cotal status` print `events: required` for a registration carrying\n`policy: { events: \"required\" }`. On that space, foreground spawn, detached spawn, manager starts,\nand interactive `join` cannot opt out or join without an event plane. `--no-events` is refused with\nthe space named. A connector without an event plane is refused with both the space and connector\nnamed. A session whose own grant omits `events.<owner>.<actor>` is refused before joining and the\nmessage names a full-row `actor grant` repair.\n\n`use <space>` sets that default; the selection applies from every directory,\nincluding inside another mesh's project. `status` is a read-only report: machine prerequisites\n(starting with the installed `cotal-ai` version), the installed extensions and their versions, this\nfolder's `.cotal/`, the recorded meshes, and a live snapshot of the selected mesh (roster, channels,\nmembership feed). Stale Claude skills and out-of-date `.agents` skills recommend `cotal setup --skills`,\nnot unscoped `cotal setup`. `status` takes `--space` / `--server` to pick the mesh to inspect; it starts\nnothing. The manager row asks the service endpoint once: a live process that does not answer is\n`not serving`, and a probe that could not be made leaves the row `running \xB7 service unchecked`.\n\nIf a refresh fails, `status` may still show the kept catalog bytes for diagnosis. It labels them\nstale with the last successful snapshot timestamp and the refresh error. It never calls that state\nsynchronized or online. If a selected discovered space vanishes from a successful snapshot, the\nselection is cleared and the command reports that no default is selected.\n\nFor a user-auth mesh the selected-mesh section reports the login `status` works as: the signed-in\nsubject when this machine holds a cached session for the entry's pinned IdP, or the exact `cotal\nlogin --idp <url>` line when it does not, with no network round trip either way. A locally\nprovisioned space also shows the actor grant row; a discovered or registered remote entry reports\nthe grant as not checkable on this machine, because the ledger runs where the space was\nprovisioned. `--components` on a user-mode target probes as that same signed-in login (`ps`'s\ncredential), never a static mint; when the login cannot supply a credential, the row says why\ninstead of printing the broker's refusal of an unauthenticated probe.\n\nPersona rows name the catalog they describe. If this folder and the selected mesh use different\ncatalogs, status names both and marks which one spawn launches from. A green `default` means the file\npasses the same agent-file loader spawn uses; a present but invalid file is reported as invalid.\n\n`cotal status --components` adds a fail-loud per-component health pass. It reads **each\ncomponent's own control surface**, rather than treating a PID, a lease, or a successful probe of a\nsibling as proof that the component serves. It prints one of `serving`, `absent`, `not-serving`, or\n`refused` for each component and exits `0`, `1`, `2`, or `3` respectively (the highest observed\nstate wins):\n\n- **manager**: local PID record, its liveness-lease holder and PID, then the manager's own typed\n  `status` service reachability from this host. Manager builds that do not report static\n  reconciliation say `static reconciliation not reported by this manager build`; the line stays\n  visible even when the manager is otherwise `serving`.\n- **delivery**: local PID record, its ready lease (`ready` is the daemon's own bound-control\n  signal), and the latest `renewal.<spaceKey>.json` adoption verdict, the record of the space the\n  command was asked about, keyed per space the way the pidfiles are. A re-signed credential and a\n  broker-accepted adoption stay distinct facts. A root-only `renewal.json` left by an older build\n  names no space and is never read as any space's verdict (`doctor auth` names it as a leftover).\n- **web**: local PID record and the dashboard's own loopback `/api/meta` response, which must name\n  the same PID and its requested port. A different process on the port, an unreadable PID command,\n  or an unrecognizable process record is `refused`, not a green default-port guess.\n- **broker**: the registered mesh URL dialed from this host with its recorded TLS requirement.\n\n`absent` means Cotal has no live local component record (or has a stale record); `not-serving`\nmeans the component record is live but its service/readiness surface did not answer or is not ready.\nThose are intentionally separate exit cases. A failed or unreadable probe is `refused`, never an\nabsent component or a clean zero.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\nFor a foreground spawn onto a remote user-auth mesh, a launcher may supply a one-time enrollment\ninstead of a cached human login. Prefer a private file:\n\n```bash\nCOTAL_ENROLLMENT_FILE=/run/secrets/cotal-enrollment \\\n  cotal spawn --config ./seat.md --space main\n```\n\nThe file contains only the enrollment URL, ending with at most one line terminator, and must be\nmode `0600` on POSIX. An orchestrator that cannot mount a file may set `COTAL_ENROLLMENT_URL`\ninstead; that value is redeemed byte for byte, so a trailing newline in it is refused. Setting both\nis refused. Enrollment input\nrequires `--space` and applies only to a foreground persona spawn. If the mesh is not registered yet,\nthe enrollment response must carry the stock user-bundle fields and the command needs\n`--config <persona-file>` because there is no local remote-mesh persona catalog to read. The client\nredeems the URL once, registers the returned mesh material, exchanges the returned actor token at the\npinned auth service, and removes both enrollment variables before starting any child process.\n\nA cached login for the same IdP and an enrollment are conflicting proofs, so the command refuses\nrather than choosing one. An invalid enrollment never falls back to login provisioning. Unknown,\nexpired, revoked, and already-used enrollments all produce one response: ask the owner for a fresh\none. See [Enrollment redeem](identity-and-auth.md#enrollment-redeem) for the HTTP contract.\n\nA runtime that starts a managed seat outside the manager's filesystem hands the child a managed\nhandoff instead: one `0600` file named by `COTAL_MANAGED_HANDOFF_FILE`, carrying the lifecycle the\nmanager already enrolled. The runtime builds the command with `delegatedSeatCommand`:\n\n```bash\nCOTAL_MANAGED_HANDOFF_FILE=/run/seat/handoff.json \\\n  cotal spawn --config ./seat.md --space main --name <actor> --agent claude \\\n    --expect-owner <owner> --expect-lifecycle-uid <uid>\n```\n\nThe `cotal` entry reads the file, deletes it and drops the variable before it parses flags, prints\nhelp or loads extensions, so every outcome leaves no file. The variable is read under any letter\ncase; spellings that name different files are refused after every one of them was deleted. The\nspawn then refuses a malformed handoff, or one whose space, owner, actor or lifecycle UID differs\nfrom `--space`, `--expect-owner`, `--name` and `--expect-lifecycle-uid`, before any broker\nconnection or exchange request. Every refusal on this path names the field and never a value from\nthe handoff. The registration's server, exchange and enforcement checks, the local state this\nmachine keeps for the space (its mesh record, user-auth state and agent secret files), target\nresolution, the policy refresh, the broker preflight and the agent auth preflight quote the space,\nthe server, the exchange URL, the actor or a path named for one of them in their own diagnostics and\nin the filesystem errors under them. For a handoff each prints one fixed sentence that names the\nfield and the phase instead, whether its check fails or an error is thrown. The event-plane policy\nrefusals name the handoff's space field. An actor outside `[A-Za-z0-9_]` and a space that cannot\nname local state, such as `..`, are refused as malformed before any plane. A handoff conflicts with\nthe enrollment variables, `--detach`, `-f` and `--creds`, and needs `--config <persona-file>`. From\nthere it runs the enrollment consumer above without redeeming anything. See\n[Delegated seats](embedding.md#delegated-seats-outside-the-managers-filesystem).\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | none | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | none | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | persona's `agent:`, else `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `jcode`, `hermes`, and so on) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at. Refused before launch when the directory does not exist on the serving manager's host. |\n| `--prompt <text>` | none | Initial prompt auto-submitted at start |\n| `--resume <id>` | none | Fork an existing session id into the mesh; only connectors that declare resume support accept it (see [the matrix](connectors.md)). The manager records the source session id, and `ps --wide` shows it |\n| `--no-events` | event plane on where supported | Opt out of the session's structured event plane (`--events` only restates the default) |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--on <instance>` | class anycast | With `--detach` only: pin the launch to one manager instance id (the whole id, as `ps` prints it). Refused on a foreground spawn (no manager to pin), with `-f` (a manifest deploy launches through the manager class queue), and when empty |\n| `--file <cotal.yaml>`, `-f` | none | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | none | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime |\n| `--expect-owner <u_\u2026>` | none | With `COTAL_MANAGED_HANDOFF_FILE` only, and required there: the owner the handoff must carry |\n| `--expect-lifecycle-uid <uid>` | none | With `COTAL_MANAGED_HANDOFF_FILE` only, and required there: the lifecycle UID the handoff must carry |\n\nEach session uses its connector's **event plane** by default: a stream of structured events\ndescribing what the agent did, rather than the prose it wrote, on a channel of its own. The channel is named after\nthe agent's principal, `events.<owner>.<actor>`, never after its display name, because two live\nagents are allowed to share a display name and would then share a stream. The launch grants publish\nrights on that channel alone, foreground and detached alike. `--no-events` is the explicit opt-out\nunless the selected registration says `policy: { events: \"required\" }`. Required policy makes the\nevent arm and grant mandatory, so `--no-events` and connectors without an event plane are refused.\n\nThe launch decision and the grant are separate on purpose. Holding publish rights on a channel is\nnot a request to publish to it, so writing an event channel into an agent file's `allowPublish`\ndoes not override `--no-events`.\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. On a user-auth mesh the\neffective name is also the agent's actor token, so it must match the token grammar (no `-`); the\nspawn is refused with that explanation before any request is sent. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. Both modes get the\ndurable backstop on a mesh that runs the delivery daemon; `--live-only` skips it for a foreground\nspawn (messages posted while it is disconnected are then not replayed). A foreground exit retires\nthe agent's creds and broker footprint, like a manager despawn. On a user-auth mesh the two arms\ndiffer: a spawn against a mesh this machine provisioned revokes the actor row on exit, while a\nremote spawn (an enrollment or the advertised provisioning endpoint) removes only this machine's\ncredential files; its grant stays until the mesh operator revokes it, and the launch line says\nwhich arm you are on. A `--detach` spawn is an\n**action**: the manager accepts it and returns the allocated identity at once, then the launch\nfollows to a terminal outcome rather than blocking (see [the control surface](control-surface.md)).\nSee [Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\nA `--detach` spawn onto a manager from another Cotal release is refused before any request is sent\nwhen the manager's contract does not declare a field this CLI sends. The refusal names the field,\ncalls it version skew, and gives this CLI's version. A field you leave unset is not sent, so it\nnever causes that refusal.\n\nA manager has 50 seat slots, and each seat counts once. A slot is held by a managed seat (a row in\nthat manager's `cotal ps`, including a seat still joining), by a reserved launch the manager accepted\nbut has not started a process for, or by a cooling hold. A seat that ends within 10 seconds of\nstarting leaves its slot cooling until those 10 seconds pass, unless an operator stopped it. Such a\nseat holds only that cooling slot, even while its launch is still reporting the failure. A spawn\nrefused at the limit states that split and whether waiting can free a slot:\n\n```text\nat capacity (50 of 50 slots: 49 managed, 0 reserved, 1 cooling); waiting frees a cooling slot in 7s, or despawn one\n```\n\nA cooling slot frees at the stated time. A launch that has not settled frees its slot only if it\nfails, and a managed seat frees its slot only when it stops. The refusal counts a launch as pending\nonly while it holds a slot, so a launch whose seat already ended is not counted. The roster counts\npresence, which also includes peers no manager owns, so its total is a different number.\n\nRun from a managed seat's own shell on a static or open mesh, `cotal spawn --detach` launches as\nthat seat when it targets the seat's own space. Without `--space` it picks that target the way the\noperator path does, so a recorded mesh that is not running is skipped. The CLI reads the seat's\nlaunch identity (`COTAL_NAME`, `COTAL_ID`, `COTAL_LIFECYCLE_UID`, `COTAL_SPACE`, and on a static\nmesh the seat's own credential), so the manager records the seat as the spawner, the same as for\nthe seat's `cotal_spawn` tool. On a static mesh that credential also proves the seat's space, so a\nlaunch without `COTAL_SPACE` still runs as the seat, and a target space holding no credential for\nthe seat is refused. An open mesh acts as the seat only when `COTAL_SPACE` names its space. The\nseat can then stop the child with `cotal_despawn`, and the manager stops the child when the seat\nexits. On a static mesh a seat whose agent file lacks `capabilities: [spawn]` is refused, because\nits credential holds no spawn subject.\n`--on <instance>` keeps its pin: the seat's own credential has no instance route, so on a static\nmesh the CLI mints a one-shot `manager-caller` view for the seat, pinned to that instance and\ncarrying the spawn subject only when the seat's credential holds it. On an open mesh the call keeps\nthe TLS requirement the mesh records. `--creds`, `--server` with an unregistered `--space`, and a\nuser-auth mesh keep the operator path.\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one. OpenCode and Codex query harness/provider surfaces; Jcode reads\nproviders that enable `model_catalog = true` in the operator Jcode `config.toml`. Jcode's listed\neffort tiers render as `variants (declared, not provider-verified)`, and launch can still refuse one.\nA connector without a catalog says so. Pick a result with `cotal spawn --model <id> --variant <v>`,\nwhere `<id>` is the model id as the catalog printed it. OpenCode and Codex ids are the full\n`provider/model`; Jcode ids are bare (`opus-5`, not `cliproxy/opus-5`), because the provider is\nselected by the operator's Jcode config and a prefixed id is refused at launch with the bare form\nnamed.\n\n## endpoints\n\n```bash\ncotal endpoints [--space <s>] [--server <url>] [--creds <path>]\n```\n\nLists the mesh presence roster: agents, the manager, and any other protocol endpoint, with each\nendpoint's role, kind, status, and current activity. Unlike `ps`, this is a read-only presence view;\nit is not limited to child processes owned by the manager.\n\n## Endpoint control\n\n```bash\ncotal describe <endpoint> [--on <instance>]                        [--space <s>]\ncotal invoke <endpoint> <command> [--args '<json>']              [--space <s>]\ncotal invoke <endpoint> <command> --name <agent> [--admin]       [--space <s>]\n```\n\nThe generic v0.4 service surface. `describe` resolves a registered endpoint's command set off the\nwire - the reserved `describe` command answers the registered contract digests, the schemas are\nfetched from the space's content-addressed contract store, recompiled, and verified against those\ndigests - and prints each command with its capability class and targeting shape. `--on <instance>`\npins `describe` to one manager instance's rail (the whole id, as `ps` prints it under its\n`manager <id>` headers), so an operator can read what that instance serves in a multi-manager space;\nunpinned, the class queue answers and the attribution line names whichever instance did. `invoke`\ncalls one command by name: `--args` is a JSON object validated against the fetched input schema\n*before*\npublish; a targeted command takes `--name <agent>` (resolved to the agent's current principal through\n`inspect`) or `--self`. `--admin` uses the admin instrument credential, whose cross-agent reach rides\nthe operator-only `any` authorization mode. Neither command has compile-time knowledge of any\nendpoint's schemas - this is the same trust chain every built-in control command now uses. Needs an\nauth mesh: the manager registers its service on both static and per-user meshes (a signed-in user\nrides their bearer; each visible or invoked command still requires its existing grant, and cross-agent\nreach needs the `admin` scope). An open mesh has no service registry.\n\n## Managed seats\n\n```bash\ncotal ps [--on <instance>] [--wide | --json] [--slots] [--space <s>]\ncotal stop --name <n> [--on <instance>] [--space <s>]\ncotal attach --name <n> [--on <instance>] [--no-reconnect] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | none | Managed agent to stop / attach (required) |\n| `--on <instance>` | class anycast (`ps`: class scatter) | Pin to one manager instance id (multi-manager space); takes the whole id as `ps` prints it, not a prefix. An empty value (`--on \"\"`, an unset shell variable) is refused, never treated as absent. A roster principal id (`local.\u2026`) is refused with a message naming the instance id `ps` prints |\n| `--wide` (`ps`) | off | After each seat's compact row, print extra operational facts the manager records: the provider the connector reported serving the model, `cwd`, `pid`, spawner, lifecycle uid, the owning manager's instance id and host, and for a `--resume` seat the session it forked (`forked from <id>`, with the source title and transcript SHA-256 once a Hermes or Jcode seat has recorded its fork). Model and requested variant stay in the identity row rather than printing twice. A fact the manager did not record (for example a runtime with no real process, or a connector that reported no provider) prints nothing, never a placeholder |\n| `--json` (`ps`) | off | Machine-readable: one JSON object per seat per line, copied unchanged from the manager row. Instance headers and errors go to stderr, so stdout contains only rows. Mutually exclusive with `--wide` |\n| `--slots` (`ps`) | off | List the durable static slot rows this manager owns instead of live seats, through the `slots` command. Mutually exclusive with `--wide`. A row that is not in the live roster still prints, with `live=false`; a retired row never prints |\n| `--no-reconnect` (`attach`) | off | End the attach when its session ends, instead of re-establishing it. For scripts that want one run and one exit code |\n\nA raw `--creds` file is refused by `ps`, `stop`, `attach` and the other control commands, because\nthat route mints no endpoint-caller triple; the project folder, or `--space` against the registry\nentry, is the route that does.\n\nThe human `ps` row is presentation text and is not a stable parsing target. Scripts use `--json`,\nwhich is the machine-readable row contract.\n\n`--slots --wide` is refused: `--slots` lists durable static slot rows, `--wide` prints live seat facts, and the two answer different questions. Across a multi-manager scatter, `--slots` prints each manager's rows under its own instance header, the same way the plain `ps` scatter does.\n\nThese are operator clients over the running manager's control plane. The default row includes the\nconnector, model pin, optional requested variant, and runtime as operational descriptors for the\nmanaged row. They do not make a shared display name a unique protocol identity; use `--json` when\nunambiguous owner+actor attribution is required. An omitted variant means no override was requested;\nCotal does not invent an effective provider default it cannot observe. `ps` also prints two state\nfacts per managed agent, because they answer different questions: the process fact from the manager's\nown runtime handle (`running` with its uptime, or `exited` with how long it ran), and the mesh fact\nfrom the roster (`idle` / `working` / `waiting` / `mesh offline`, or `not in roster` when the seat has\nno presence row at all: a seat that has not joined yet, or one that never did). When the seat's\nconnector relays a harness-reported condition, the mesh fact carries its code and how long it has\nheld, so a seat whose turn died on a provider rate limit reads `waiting (rate_limit for 40m)` rather\nthan a bare `waiting`, and `--json` carries the whole `condition` object. When the connector reports\nthe seat's last work event (presence `activeAt`), the mesh fact ends with its age, such as\n`\xB7 active 3s ago`, and `--json` carries `activeAt`. A seat whose turn stopped advancing keeps\nheartbeating, so its presence row stays fresh and this age is what shows the stall. A seat can be\n`running` and `mesh offline` at once: the process is alive and its presence has lapsed. That row says\nhow long, as in `mesh offline for <age>` with an age such as `3.5h`, counted from the seat's last\npresence heartbeat, which `--json` carries as `offlineSince` (epoch ms). The age is read only from\nthe seat's own presence record, matched on its principal and lifecycle uid, so a same-named peer or\nan older lifecycle never dates it. The manager log names each managed seat that is offline on the\nmesh while its slot is held\n(`seat offline on the mesh: <name> - last heartbeat <time>; process <state>`), including one its\nwatch first sees offline after a reconnect, and each one that comes back\n(`seat back on the mesh: <name>`), so a watchdog that only checks process liveness has a line to\nact on. The manager does not reap or re-key such a seat. The mesh fact is only a verdict while the\nmanager's own presence watch is fresh: when that watch has been silent past the liveness window, or\nhas not replayed the bucket yet, every row prints `mesh unknown` with the reason instead (`--json`\ncarries it as `meshView: stale | unpopulated`), because `offline` and `not in roster` would then\ndescribe the manager's watch rather than the seat. The manager rebinds a watch that goes\nsilent under a live connection on its own, so `mesh unknown` normally clears within a liveness window.\nOn a user-auth mesh `ps` also renders each managed agent's last credential-refresh outcome, fail-closed.\n\n**Mode split (chosen up front, never try-scatter-then-degrade):**\n\n- **Static / open mesh.** Bare `ps` is a **class scatter**: it freezes the live manager class from\n  the records registry, merges every registered instance's agents grouped and attributed per\n  instance, and a non-answering instance is shown as `registered, no answer within the deadline`\n  (never silently omitted). A refused list or a missing answer makes the census incomplete: rows\n  from other instances remain visible, but `ps` prints an incomplete-census warning on stderr and\n  exits non-zero, including with `--json`. Those rows are not a complete seat count. A contract\n  mismatch prints one plain comparison of the requested and served input/output digest pairs and\n  advises aligning manager versions. The no-answer label means only that the instance is registered\n  and did not answer. It does not say the host is down, because a dead host never deregisters itself and a\n  live one can be slow; if it is gone, deregister it.\n  `--on <instance>` pins the read to one exact instance id instead. A wrong pin fails loud\n  rather than falling through: a well-formed id that no live manager carries is reported as\n  `manager instance <id> did not answer` (nothing else is asked), and a credential without that\n  instance's rail is reported as refused by the broker, not as an unresponsive manager. A manager\n  that answers with a refusal is shown with its own cause; \"no manager reachable\" is said only when\n  nothing answered at all. If the scatter's own registry read fails (the freeze or the reconcile),\n  `ps` says the manager registry could not be read rather than pronouncing on the managers, which\n  may all be up.\n\n**The verdict is scoped to the endpoint rail the request rode.** An issued caller rides the\nversioned `ep.v1` rail, a separate subject space from the legacy `ep` rail, and an endpoint serves\nboth (SPEC 13.15). A manager older than the versioned rail serves `ep` alone, so it can be running,\nregistered and answering while an issued caller's request reaches nobody. Silence on `ep.v1` is\nreported as `no manager answered on the <rail> rail` with `ep.v1` as the rail, and names both causes\nit is consistent with: no manager running, or one older than the rail. The CLI cannot tell them\napart, because the service registry records no package version, so check whether a manager is\nrunning and, if it is, its version. The same scoping applies to `cotal run`'s hosted verbs, which\ndrop the `--local` suggestion there, since `--local` drives the run from the calling process and\nnames the caller as its answerer.\n\n**`stop` and `attach` route by seat locality.** A seat can only be stopped or attached by the\nmanager actually running it, and the class queue does not know which one that is. So on a\nstatic/open mesh both verbs first ask every registered instance which one hosts the named seat, then\naddress that instance directly. This happens by default; you do not need `--on`.\n\n`--on <instance>` remains the override, for when you already know where the seat lives or the\nlookup itself is degraded. On a **user-auth mesh**, the exchange selects one authorized manager\nfor a short-lived `manager-caller` view. `--on` requests a specific instance; without it, selection\nmust be unique. Discovery and the command use that instance route. The caller gains no registry\nread or scatter permission. An absent, ambiguous or unauthorized selection refuses before sending\nthe command.\n\nA seat is reported as **not found** only when every reachable instance answered for itself. An\ninstance that stayed silent past the deadline, or that refused the read rather than answering, said\nnothing about which seats it hosts, so the seat may be running on it. That case reports that the\nlocation could not be established, names the instances that did not answer, and states outright\nthat it is not a report that the seat is gone. Read it as unknown and retry with\n`--on <instance>`; a retry loop that treats it as \"already gone\" stops looking for a seat that is\nstill running. A single manager cannot tell \"hosted elsewhere\" from \"does not exist\": it answers\n`not-found` for both, which is why the search asks all of them and why an incomplete search\nconcludes nothing.\n- **User-auth mesh.** `cotal ps` reports what **one** authorized manager knows about your agents\n  (an instance-addressed read against its in-memory roster, owner-filtered). It does **not** report\n  other manager instances or establish whether they are reachable. Completeness across a\n  multi-manager user-auth space is not claimed.\n  A manager that does not answer fails the command outright (exit non-zero), rather than printing\n  an empty list that could be read as \"no agents\". Your ledger row needs the `admin` scope to\n  reach `ps` at all; `spawn` alone is refused by the broker (the ep tier boundary).\n\n`attach` streams and drives an agent's terminal on the `pty` runtime; detach with the escape key\n(Ctrl-] by default; see [`COTAL_DETACH_KEY`](config.md)). The key is recognised as the legacy\ncontrol byte and as the kitty keyboard protocol and xterm modifyOtherKeys encodings of the same\npress, so a terminal with either protocol enabled detaches too. It does so over a one-use, holder-bound\nmesh session ([SPEC](../SPEC.md) \xA713.6): the manager replies with a signed session grant (never a\n`127.0.0.1` URL), the CLI redeems it once over the broker, and the browser console (`cotal console`)\ndrives the same session. `stop` and `attach` need a running manager to talk to. On a static mesh\nthey are cross-agent admin operations. On a user-auth mesh, your own agents (any agent under your\nowner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger row\n([identity & auth](identity-and-auth.md)). Launch detached agents with [`spawn --detach`](#spawn).\n\n**`attach` reconnects when the link dies.** A session lives on a network link, and a laptop that\nsleeps, a VPN that drops or a wifi handover kills it. When that happens `attach` prints\n`[cotal: connection lost, reconnecting]` on stderr and starts asking the manager for a new session:\na fresh grant, a fresh per-session credential, a fresh connection, so every attempt re-runs the same\nauthorization the first attach did. On success it prints `[cotal: reconnected]`, the manager repaints\nthe seat's current screen the way it does for any attach, and you carry on in the same terminal.\nRetries wait 1s, 2s, 5s, 10s, then 30s, for as long as the seat exists. The detach key is read the\nwhole time the loop runs, the waits and the attempts alike, so a reconnect never traps you: press it\nwhile a session is being established and the attach ends there, and a session that lands behind the\npress is handed back to the manager rather than left holding a slot. Everything else you type while\nthere is no session is dropped rather than queued, so keystrokes aimed at a terminal that turned out\nto be frozen, Ctrl-C included, are not delivered to the agent by a reconnect you did not know had\nhappened. That starts before the first session, not at the first reconnect: at a terminal, `attach`\nreads and drops what you type while it is still resolving the mesh, so a key struck at a prompt that\nhas not come up yet does not reach the agent when it does.\nThe terminal is in raw mode for the whole reconnect, including when the link died before the first\nsession finished opening, so the detach key works there too instead of echoing as `^]`.\n\nA **pipe** carries script input. For example, `printf 'ls\\n' | cotal attach --name web` is\nbuffered until the session opens. Buffering continues across reconnects, so\n`tail -f log | cotal attach --name web` does not lose the part of its feed written while the link was\ndown. Only a terminal gets the reader; `--no-reconnect` keeps the old behaviour on both.\n\nIt stops on its own when reconnecting cannot help, and says why: a manager that refuses the attach\nexits non-zero with the manager's own message, and a reconnect that finds the seat no longer there\n(despawned, or its agent exited while the link was down) exits cleanly with `seat <name> is gone`.\nA local connect refusal that retrying cannot fix, such as a static-auth mesh whose seed is now\nmissing, also exits non-zero with the refusal's own sentence. A broker that is still unreachable\nkeeps the loop trying in silence.\nA refusal that could still pass, such as a manager at its session ceiling, is relayed in the\nmanager's own words while the loop keeps trying, once per refusal rather than once per attempt.\nPressing the detach key, or the agent's process exiting while you are attached, ends the attach as\nit always did. `--no-reconnect` turns all of this off and restores the single-session behaviour,\nwhich is what a script wants.\n\nEach reconnect also hands the abandoned session back to the manager, over the first link that can\ncarry the message, so an attach that flaps does not eat the manager's session slots one outage at a\ntime. If that message never gets a link, the attach says so when it ends. The live-session ceiling\ndefaults to 64 concurrent sessions (`--max-sessions`); the browser console opens one session per\npane, so a dashboard over a large mesh should size for agents \xD7 panes. Hitting the ceiling refuses\nbefore a credential is minted and names `--max-sessions`.\n\nWhich mesh `attach` resolves also decides **how it redeems the grant**. On a registered open mesh\nthere is no local seed. The CLI connects bare, the same way other control commands already do, and\nthe session rail is the caller rail that a real open-mode connection already reaches. Telling the\noperator to re-register the root is false: the registered root is already the contract. On a\nstatic-auth mesh the grant is still redeemed by minting a short-lived\nsession-scoped credential from the seed at the root the mesh resolved to, never from a `.cotal`\nfound by walking up from whichever directory you happen to be standing in. The difference is not\nhypothetical: `~/.cotal` exists on every install because the mesh registry lives there, so a command\nrun anywhere under your home directory but outside a project used to mint from your home\ndirectory's trust and present it to a broker that trusts a different chain, which surfaced as a\nbare authorization failure that named nothing. A directory that does hold another chain for the\nsame space is now reported on the way past, and not obeyed:\n\n```text\n! this directory resolves to /Users/you, whose .cotal/auth holds a DIFFERENT trust chain for space \"team\".\n  attach used /Users/you/projects/app, the root this mesh resolved to. The other one is not being used, and is worth a look.\n```\n\nWhen a **static-auth** mesh holds no seed at the resolved root, `attach` refuses and names what it\nresolved, the broker and the root, instead of describing a directory it did not use and instead of\ntaking the open-mode path. An authenticated registry entry with a missing seed is still\nauthenticated. On a USER-AUTH mesh `attach` reads no seed. It sends your login and the session grant to\nthe auth service, which issues a `session-caller` bearer only if your owner and actor hold that\nsession. The connection it opens expires with the session grant.\n\nTerminal bytes stream over the mesh; the manager's own HTTP/WS face serves the console. That endpoint binds\n**loopback by default**, so nothing is exposed by accident; `cotal up --host <addr>` passes its bind\naddress down, which is what lets you reach the browser console (`cotal console`) for an agent whose manager runs on another machine.\n`attach` does not use that face: it redeems a signed mesh session grant over the broker instead (see above), so it reaches a\nremote manager regardless of the bind address. A\nbare `cotal supervise` and an embedded manager stay machine-local. Set it directly with\n`supervise --console-host <host>`.\n\nThat address is **recorded on the mesh** and carried forward, because it is a decision rather than\nsomething later commands can work out for themselves (a broker dial address is not a manager bind\naddress). Every later manager launch for the same mesh reuses it, including a same-root `cotal up` repair,\nan adopted preserved or restored listener, and a `spawn -f` manifest deploy. A manager replacement\ndoes not quietly move a reachable attach face back to loopback. Passing `--host` again overrides it,\nso you can widen or narrow exposure whenever you like; a mesh that never asked stays loopback-only\nand records nothing.\n\nBecause that face mints terminal read and write authority for every managed agent's browser session, it is credentialed in two\ntiers. A mesh caller receives a **ticket** bound to the single agent the manager just authorized,\nsingle-use and short-lived, so one authorized attach can never be re-pointed at someone else's\nagent. The **console token** is the operator's own, reaches every agent, and is printed only to the\nmanager's output. The roster, the live feed, and the PTY stream all answer `401` without one; the\nstatic console shell is served openly, since it describes no agent.\n\n## input\n\n```bash\ncotal input --name <n> --text <text> [--no-enter] [--on <instance>] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | | Managed agent to type into (required) |\n| `--text <text>` | | The text to type, taken verbatim (required) |\n| `--no-enter` | off | Type the text and stop there, without pressing Enter |\n| `--on <instance>` | class anycast | Pin to one manager instance id using the same rules as [`attach`](#managed-seats) |\n\nTypes one line into a running agent's terminal, as if you had typed it there, and returns. This is\nthe half of [`attach`](#managed-seats) that a program wants: `attach` is a live stream that holds a\nsession open and expects a terminal on your side, so a script, a cron job or a web UI cannot use it\nto send a single line. `input` is one authorized call.\n\nWhat it is for is **harness commands**. A line beginning with `/` is not chat and not a message: it\nis something the agent's own harness handles, and the only way in is the keyboard.\n\n```bash\ncotal input --name reviewer --text \"/compact\"          # ask the harness to compact its context\ncotal input --name reviewer --text \"/model opus\"       # switch its model\ncotal input --name reviewer --text \"hold on that PR\"   # ordinary typing works too\n```\n\n**Quoting.** `--text` takes a value, so a payload starting with `/` survives as written. A payload\nstarting with a dash needs the `=` form, because the shell-style `--text --foo` is ambiguous and is\nrefused rather than guessed:\n\n```bash\ncotal input --name reviewer --text=--verbose          # dash-leading text: use --text=<value>\n```\n\nEnter is pressed by default, since a command typed but never submitted has not been delivered.\n`--no-enter` types the text and leaves it sitting at the prompt, which is how you stage a line and\nsend it later.\n\nNothing comes back but a delivery receipt (`\u2713 sent 9 bytes to reviewer`, counting the trailing\ncarriage return). Whatever the agent does next shows up where its output already goes: the mesh, its\ntranscript, or an `attach`.\n\n**This one is operator-only, and more narrowly than `stop` or `attach`.** Those two are granted to\nanything holding `spawn`, so an agent can stop and attach to seats under its own owner. `input` is\nnot: it is granted only to operator credentials, which on a user-auth mesh means your ledger row\nneeds the `admin` scope, the same scope [`ps`](#managed-seats) already needs there. The reason is\nthat a write into a terminal is control of whatever is running in it, and on a user-auth mesh the\nown-owner rule covers every seat under you, not only the ones you launched: a `spawn`-scoped agent\ncould otherwise type into a sibling it never started. Seat locality is still resolved for you.\n\nOnly the `pty` runtime can be typed into. The external terminal runtimes (`tmux`, `cmux`, `orca`,\n`herdr`) attach to a process they do not own, so they have no input stream for it and the command\nrefuses by name rather than dropping the keystroke.\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | none | `new`: the persona's role |\n| `--model <m>` | none | `new`: the persona's model |\n| `--prompt <t>` | none | `new`: the persona's prompt text |\n| `--from <f>` | none | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | none | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under the resolved mesh root's `.cotal/agents/`, the same catalog\n`cotal spawn` launches from. `--space` and `--server` therefore move every list, read, write, delete\nand completion operation to the selected mesh. An unresolved target refuses rather than falling back\nto the current directory. See [Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <name>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | hosting mesh, or matching registered mesh | Broker URL. A registered mesh supplies it when omitted; a different explicit value is refused before anything is dialed. |\n| `--runtime <name>` | `pty` | Agent runtime (`pty` built in; extension runtimes are explicit-only) |\n| `--console-port <n>` | none | Protocol-console port |\n| `--console-host <host>` | loopback | Bind host for the console endpoint. Loopback keeps it machine-local; `cotal up` passes the address it bound the broker to, which is what lets the browser console reach this manager from another machine. `cotal attach` does not use this face: it redeems a mesh session grant over the broker |\n| `--max-sessions <n>` | 64 | Live-session ceiling. Each console pane and each `cotal attach` is one session, so size for agents \xD7 panes, not agent count. A capacity refusal names this flag. `cotal up --max-sessions` records the same number on the mesh so a later `supervise` started by repair or `spawn -f` keeps it |\n| `--roster <file>` | none | Declarative roster to boot at startup |\n| `--launch <spec>` | none | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | none | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; install an\noptional provider first (`cotal ext add @cotal-ai/orca`, `@cotal-ai/tmux`, `@cotal-ai/cmux`, or `@cotal-ai/herdr`) and\nselect it explicitly. A missing provider or app fails loudly; there is no fallback. See [Deploy](deploy.md).\nBoot inventory decides whether this process takes unpinned `spawn`/`launch` on the class rail:\nif every declared connector is unavailable, those commands stay on this instance rail only\n(`status` reports `classSpawn: false`). `describe` still answers on the class rail, so an\nunpinned spawn can bind-fence against a skip member; re-issue, or pin `--on`. A partial\ninventory keeps the class rail and names `--on` on a harness refusal, because sibling\ninventories are not readable from the serve credential. See [control surface](control-surface.md#instance-routing).\n\nOn a normal `SIGINT`/`SIGTERM`, the manager stops every seat and requires the selected runtime to\nprove the seat is gone before it releases the manager lease or service registration. A stop that\ncannot prove exit fails loud and keeps manager authority instead of reporting a clean shutdown while\nan orphan still holds broker rails. After an abrupt manager death, the same logical successor\nterminalizes only its own durable static slots, verify-evicts the predecessor's broker principal,\nrecords that result in the lifecycle's caller-readable audit detail, reaps the predecessor's seat\nprocess through the runtime's custody reference recorded on the slot (the pty runtime verifies the\nprocess start identity in its seat record, so a reused pid is never signalled), and only then\nretires the lifecycle and frees the alias. A runtime that custodies its seats reserves that\nreference before it launches one, and the manager records it on the slot's first durable row, so a\nmanager that dies part-way through a spawn also leaves a seat its successor can address. A spawn\nthat launched its seat and then failed is rolled back by the manager that launched it, and that\nrollback reaps the seat through the same reserved reference before the lifecycle retires. Missing or unverified broker evidence keeps the slot\nterminalizing, and so does a runtime that cannot reap by reference.\n\nA `meshes add --mode user` entry is a **participant** registration, not hosting authority. A\nparticipant may run `supervise` only when the host advertises the remote manager authority service\nand the signed-in actor has the dedicated `supervise` ledger scope. The CLI obtains the closed,\nloopback-only `manager-service` view; `spawn` and `admin` do not substitute for that scope. The\nhost issues the manager's public-nkey JWT material through its lifecycle-bound prepare \u2192 activate\n\u2192 renew protocol, never by handing the participant a signer or static provisioner credential.\nThe host also performs instance-scoped eviction and guarded gate reconciliation. A remote manager\nrefreshes its short-lived registration executor before clean deregistration, so a long-running\nprocess removes its service row on `SIGINT` or `SIGTERM`. After an unclean stop, the same instance\nverify-evicts its superseded family and advances the process epoch. If an abandoned frozen gate\nholds the manager governance slot, a different supervise-scoped manager asks the host to reconcile\nthat holder after a complete gone verdict, then retries its registration once.\n\nA remote supervise never uses local signing trust: with host-issued authority in hand, the\nmanager mints from that authority alone and consults local records only to refuse a conflict,\nnamely the supervised space's own trust records under the cwd root. A root that hosts another\nstatic space beside the sign-in is a normal configuration and is never read as this space's\ntrust.\n\nThe broker URL in the registry entry decides the transport. A remote broker is often published\nover a `wss://` edge rather than a raw `nats://` port, and `supervise` dials whichever scheme the\nrecord holds, starting with the manager-authority registration it runs before the manager exists.\nThe record also decides whether that registration requires TLS, so a participant never downgrades\nthe credential exchange to a plaintext connection the registry did not describe.\n\nWithout that advertised host service or scope, `supervise` refuses before it starts a manager.\nRun `cotal spawn` without `--detach` to launch a foreground agent, or ask the space host to enable\nthe authority service and grant `supervise` for detached agents. If a running remote manager loses\nrenewal, it reports degraded state and refuses unsafe new starts and restarts; live agents are not\nsilently replaced. Do not run `cotal down` or `cotal up` on a participant machine to repair this\ncondition.\n\n## service\n\n```bash\ncotal service install [--mesh <name>] [--linger]\ncotal service status [--mesh <name>] [--json]\ncotal service uninstall [--mesh <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--mesh <name>` | this folder's mesh | The mesh whose manager the service runs; one unit per mesh |\n| `--linger` | off | install: when lingering is off, ask logind to enable it so the user manager starts at boot and the service survives logout. Never enabled silently |\n| `--json` | off | status: machine-readable output |\n\nRuns the manager as a user service so it survives logout and reboot. On Linux this installs a\nsystemd user unit (`~/.config/systemd/user/cotal-manager@<key>.service`, where `<key>` is the\ncase-safe mesh key); on macOS a launchd agent plist under `~/Library/LaunchAgents/`. Any other\nplatform, or an absent systemd/launchd user session, fails with a message naming what is missing.\n\n`install` resolves the mesh from the registry and binds the unit to that entry's root and broker\naddress, so it can be run from any directory. The mesh must be registered (`cotal up` or\n`cotal meshes add`) before installing; an unregistered name refuses before anything is written.\n\nThe unit's `ExecStart` is the bare `supervise` command. The mesh facts travel in a `0600`\n`EnvironmentFile` (`COTAL_SPACE`, `COTAL_SERVER` pinned to the registered broker URL, whatever\nport it listens on) rather than the command line, because command lines are readable by every\nuser on a multi-user host. The same file gives the service a private `COTAL_HOME` and\n`XDG_CONFIG_HOME` under the unit directory, so the service manager never touches the login\nuser's `~/.cotal`. First-run connector seeding runs synchronously inside `service install`,\nagainst that private config root; the unit itself starts with `COTAL_SKIP_CONNECTOR_SEED=1`\nso a manager is never interrupted mid-seed by a restart. An install whose pre-seed cannot\ncomplete (network unreachable, registry error) refuses instead of deferring.\n\nThe same file pins `PATH` to the `PATH` of the shell that ran `install`, and on macOS the plist's\n`EnvironmentVariables` carry it too. Without it the unit inherits the service manager's own short\n`PATH`, which usually lacks `~/.local/bin` and Homebrew, so the manager's boot inventory would\nreport a harness unavailable that your shell resolves. Install from a shell that resolves every\nharness the service should launch, and reinstall after moving one. A relative entry, including\nan empty one, is resolved against the directory you ran `install` from, because the unit starts in\nthe mesh root where the same spelling names another directory. An entry with a `..` segment is\npinned as the directory your shell reaches through it, with symlinks followed, and refuses when it\nreaches none. A `PATH` set to the empty string is one empty entry, so it pins that directory. An\nunset `PATH` refuses.\n\nEvery value the unit derives from a path (`WorkingDirectory`, the `EnvironmentFile` path, the\n`ExecStart` tokens) is escaped for systemd specifiers (`%` becomes `%%`), so a mesh root that\ncontains `%` starts over its real path instead of a path systemd rewrote by expanding it. The\nprovenance comment records the root unescaped.\n\nOn Linux a user unit starts at boot and survives logout only while the user lingers. Without\nlingering, systemd starts no user manager at boot, so an enabled unit stays inert until the next\nlogin and stops at the last logout. `install` checks lingering before it writes anything, and when\nlingering is off it fails with the root command that turns it on (`sudo loginctl enable-linger\n<user>`). With `--linger` it first asks logind to enable lingering for the current user, and fails\nwith the same command when logind refuses (unprivileged users over SSH get `Access denied`).\n`service status` prints that command while lingering is off. A Linger query that does not answer\n`yes` or `no` (logind unreachable, no `loginctl`) is never read as off: `install` refuses with\nthe query's own error and enables nothing, and `service status` shows lingering as unknown with\nthat error (`--json` gives `\"linger\": { \"error\": ... }`).\n\n`service install` also refuses while a manager is already running for the mesh (`cotal down\nmanager` first). The restart policy is `Restart=always` with `RestartSec=20s`, chosen for\nmanager units in production: a manager exits for reasons that are not failures (broker\nrestarts, host suspend), where `on-failure` with a short interval thrashes.\n\nThe unit also sets a start limit (`StartLimitIntervalSec=30min`, `StartLimitBurst=20`). A manager\nthat keeps failing to start stops after 20 attempts, about seven minutes at 20 seconds apart, and\nthe unit is left `failed` instead of restarting forever. One such failure is deliberate. After an\nunclean stop, a manager that cannot verify eviction of its predecessor's credentials exits 1 and\nleaves the issuance gate frozen, because starting without that proof could let two incarnations\nserve at once (SPEC 13.1). It first waits up to 60 seconds for the delivery daemon to answer, so a\ndaemon that is still starting does not fail the start. The log names the cause. When the delivery\ndaemon is down, it says the daemon is not reachable on the `ctl.delivery-admin` rail. When the\ndaemon answers and refuses, for example because the space is missing a `$SYS` cred, it prints the\ndaemon's own reason and repair step. Fix that cause, then run `systemctl --user reset-failed\n<unit>` and `systemctl --user start <unit>`. The macOS agent has no start limit: launchd's\n`ThrottleInterval` only spaces restarts.\n\n`service status` reports the unit state from systemd/launchd, the manager's own health read from\nits pidfile at the unit's recorded root, and the machine facts a hosting side asks for:\narchitecture, OS (the platform, never the hostname), whether `/dev/kvm` is present and\naccessible, CPU count, and total memory. `--json` returns the same fields as one object.\n\n`service uninstall` stops and disables the unit and removes it plus the private state directory.\nIt works from any directory: the unit's own records name the mesh and root it serves, and an\nexplicit `--mesh <name>` selects it. It refuses any unit that was not written by `service\ninstall` (the files carry a provenance comment), whose recorded mesh is missing, or that was\ninstalled for a different mesh, so operator-written units are never destroyed; `service status`\napplies the same rule and never reports a mesh a unit does not record.\n\nThis command installs only the manager. The per-space auth service and the delivery daemon are\nnot installed by it: on a shared broker an operator runs three units per space with `After=`\nedges (auth service, then manager, then delivery) and stops them in reverse. A broker-side `cotal\nup` unit is a separate unit documented in [Run a mesh](run-a-mesh.md).\n\n## reconcile-gate\n\n```bash\ncotal reconcile-gate [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the frozen gate lives in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint whose gate is frozen |\n| `--instance <id>` | this folder's persisted manager instance | Instance id |\n\n**When you need this.** A manager restart killed after deregistration begins but before the new\nincarnation finishes leaves the endpoint's issuance gate *frozen*, held by a\nprocess that no longer exists. The freeze is what stops two incarnations serving at once, which is\ncorrect. The successor manager now completes that dead registration itself on boot, including on\nthe remote user-auth path. A foreign remote manager blocked by this gate also asks the host to repair\nit before one registration retry. Both use the same guard this command uses: they act only when the freeze-holder is affirmatively gone under a complete\nCONNZ sweep (`gone` and `sweepComplete=true`). If that registration's spec write already committed,\nit finishes the same freeze at the committed registration revision. If the spec did not advance, it\nabort-reopens the gate at generation+1 with processEpoch unchanged and continues the normal takeover.\nLive, unknown, unestablishable, and\nwrong-op-kind still refuse; there is no TTL.\n\nUse this command when the automatic path cannot run: the delivery daemon is down, the repair targets a\nnon-manager endpoint, or you want to lift the freeze without starting a manager. It checks that the\nholder really is gone, prints what it found, and then finishes the dead operation the same way as the\ninterrupted restart would have: revoke the old credentials, evict their holders with verification,\nand reopen the gate.\n\nThe command revokes the old credentials 16 at a time. It then verifies the holders' eviction in\nshared sweeps of up to 256 holders on the delivery daemon. Each sweep scans the broker a fixed number\nof times and kicks live connections 16 at a time, so holders that are already gone add almost\nnothing and live ones add one broker round trip per 16 connections. The daemon must serve the\n`evictPrincipals` verb; an older daemon refuses it and the gate stays frozen.\n\nEach sweep durably records the holders it verified before the next sweep starts. If a holder is not\nverified gone, the command leaves the gate frozen with those records kept. An interrupted sweep\nrecords nothing, and the sweeps before it stay recorded. A retry still repeats the freeze-holder\nliveness check, then skips only progress bound to the same registration operation, frozen-gate\nrevision, and holder set.\nThe output reports holders completed before this attempt, completed now, and still remaining. A new\nfreeze or changed holder set starts from zero. Cursor cleanup happens only after reopen; a retained\ncursor is harmless because its old gate revision cannot authorize a later freeze.\n\n**It refuses far more often than it acts, on purpose**, and always says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `holder-alive` | The freeze-holder still has a live connection: a manager *is* running | Stop that process first. Reconciling would evict a live manager's credentials |\n| `holder-unknown` | The connection sweep could not prove the holder absent | Not safe to proceed: an unprovable holder is treated as a live one. Re-run once the broker answers completely |\n| `liveness-unestablishable` | The delivery daemon gave no verdict: it was unreachable, timed out, or refused | Act on the delivery lease line in the refusal (below). Silence is never read as death |\n| `not-frozen` / `no-gate` | The gate is open, or there is no gate at that coordinate | Nothing to repair: check `--endpoint` / `--instance` |\n| `wrong-op-kind` | Frozen under a takeover or retirement, not a registration | Out of scope for this command; it will not reinterpret another operation's intent |\n| `eviction-unverified` | The holder looked gone but eviction could not be verified | The gate is left frozen, unchanged. Investigate the broker before retrying |\n| `raced` | A newer manager moved the gate mid-repair | Re-run `cotal doctor` and look again |\n\nWhen the daemon gives no verdict, the refusal also reads the delivery lease (`lease.0`) and names\nwhat is blocking the rail:\n\n| Lease reading | What to do |\n|---|---|\n| absent | No daemon is running. Start it (`cotal up` runs it) and re-run |\n| unreadable | The daemon cannot be named, so do not assume none is running. Fix the lease read, then re-run |\n| held, not ready | That holder claimed the shard and has not bound its rails. Wait for it, or stop it so its lease lapses |\n| held, ready, no answer | The query may have gone to another daemon still subscribed to the rail, such as a stopped one whose lease lapsed. Re-run before stopping anything. If no run gets an answer, stop any other delivery daemon for the space, then stop or restart the holder |\n| changed hands | The holder took the shard after the query was sent, so it was never asked. Re-run before stopping anything |\n\nThe command reads the lease before it sends the query and again after the query fails. It names a\nholder as the blocker only when the same run of the same daemon held the lease both times, and two\nrows from a daemon too old to record its run never count as the same run. Even then a ready holder\nmay not have been asked: the rail is queue-grouped, so any daemon still subscribed to it can take\nthe query. A row whose times are not valid dates reads as unreadable.\n\nA daemon that answered and refused keeps its own reason, followed by the same lease line. The lease\nline names the holder, whether it is ready, the space account that holds the lease bucket, when that\nholder acquired the shard, and when the row was last written. A ready holder rewrites the row on\nevery renewal and keeps its acquisition time, which only a successful acquisition sets. A row\nwritten by a daemon that predates the acquisition time reports it as unknown. The lease reads never\nchange the outcome: the gate stays frozen and the command exits 2. A manager's boot self-heal uses\nthe same check and reports the same line.\n\nThere is no `--force`, and no path that discards gate state: the only way this reopens a gate is by\nproving the holder is gone and then completing the operation properly.\n\n**What reopening the gate does for the endpoint's governance slot.** A registration takes the\nendpoint-wide governance slot before it publishes its spec, and holds it until its gate reopens. An\ninstance that died between those two points leaves the slot held with no registration behind it.\nThis command does not write that slot and never has; the registration path is its only writer. What\nthe reopen does is advance the holder's gate past the generation the slot is stamped with, which is\nwhat marks the slot abandoned. The next registration for that endpoint then reclaims it as part of\nits ordinary start. So the repair here is still one command followed by starting the manager, and\nthe slot needs no separate step.\n\n## deregister-instance\n\n```bash\ncotal deregister-instance [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the instance is registered in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint the instance serves |\n| `--instance <id>` | this folder's persisted manager instance | Instance id, the whole id as `cotal ps` prints it |\n\n**When you need this.** The service registry records *registration*, not liveness, and nothing in\nthe model expires a row. A manager that stops cleanly removes its own registration. One whose host\ndied without writing anything cannot, so its record goes on claiming a live instance forever: every\nclass scatter in that space freezes the dead slot in, and `cotal ps`, `stop` and `attach` each pay\ntheir whole deadline waiting for a machine that is never coming back. A laptop that was reimaged, a\ncontainer that was deleted, a box that will not be back on the network: those registrations have no\nother exit.\n\nThis command is that exit. It asks the instance first, and it removes a record only when the broker\naffirms the instance's own rail is empty: nothing subscribed there. Then it deletes the\nregistration's two records keys, each pinned to the revision it read, and prints what it removed.\n\n**Silence alone never passes.** An unanswered describe is what a dead host, a wedged process and a\nslow one all look like, and a hung process still holds its subscriptions, so the broker sees\ninterest on its rail. That instance is refused and the observation is printed. A dead process holds\nno connection and therefore no subscription, so a real corpse is still removed.\n\n**Every refusal names the failed check:**\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `instance-answered` | The instance answered a pinned describe. It is alive | Nothing to repair. If it is wedged rather than gone, stop the process first; its own clean stop removes the record |\n| `instance-not-affirmed-gone` | It did not answer, and the broker did not report its rail empty, which is what a held subscription looks like: slow or hung, not affirmed gone | Nothing was removed. Stop the process; its record goes on its own clean stop, or re-run this once it is down |\n| `liveness-unestablishable` | The probe itself failed, so nothing was learned | Fix the probe's path (credential, broker) and re-run. A probe that could not run is never read as death |\n| `not-registered` | No registration at that coordinate | Check `--instance` and `--endpoint`. This takes the whole id, never a prefix |\n| `registration-in-flight` | The instance holds the endpoint governance slot at the live issuance-gate generation, so a registration is still completing | Nothing was removed. Wait for that registration to finish, then re-run |\n| `superseded` | The record moved between the read and the delete | Something is writing to it. Nothing was removed; re-observe before retrying |\n\nThere is no `--force` and no sweep: silence is not death, and a rule that removed rows on silence\nwould eventually remove a live instance that was merely slow. An operator names one instance, the\nbroker's verdict on its rail is what authorizes the removal, and the guard's job is to show them\nthey named a dead one. Removal is not a one way door either. The same instance re-registers over\nthe tombstone on its next start, under the same identity.\n\n## runtimes\n\n```bash\ncotal runtimes\n```\n\nLists every agent runtime the manager can spawn through: the built-in `pty`, the official providers\n(`orca`, `tmux`, `cmux`, `herdr`), and any custom provider installed via `cotal ext add`. Each installed\nprovider is probed so you can see what is actually reachable on this machine before selecting it:\n\n```\npty    built in\norca   installed \xB7 reachable   @cotal-ai/orca\ntmux   available \xB7 cotal ext add @cotal-ai/tmux\ncmux   available \xB7 cotal ext add @cotal-ai/cmux\nherdr  available \xB7 cotal ext add @cotal-ai/herdr\n```\n\n`installed \xB7 reachable` / `unreachable` is the provider's own `available()` probe; `available` means\nit is a known runtime you can add with the shown command. Selecting an unknown or uninstalled runtime\nvia `up`/`spawn --runtime <name>` fails loud and, for a known one, points at the exact `cotal ext add`\npackage. There is no silent fallback to `pty`.\n\n## seats\n\n```bash\ncotal seats [--drain]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--drain` | off | Retire every seat whose agent has exited. A seat whose agent still runs is kept |\n\nThe pty runtime used to start a detached custodian process for every Linux seat. It now spawns\nin-process, but custodians that an earlier manager started keep running, and one whose agent has\nexited stays resident while a manager still holds its connection. This command lists the custody\nrecords under `COTAL_SEAT_ROOT` (default `~/.cotal/seats`), one line per seat:\n\n| State | Meaning |\n|---|---|\n| `live-child` | The agent process still runs. The seat is never signalled, and a manager can still adopt it |\n| `childless` | The agent has exited. `--drain` retires the seat |\n| `drained` | `--drain` proved the custodian and the agent gone and removed the record |\n| `refused` | The record cannot be read, carries no start or boot identity, comes from an earlier boot, or the reap could not prove the processes gone. The record stays on disk |\n\nA drain signals only a custodian whose recorded start identity still matches the live process, so\na reused pid is never touched. A record whose identity cannot tie its pids to this boot's processes\nis refused with or without `--drain`, and is never reported as running or exited. That refusal and\nan unreadable record signal nothing. A refusal from the reap itself can come after the drain already\nsent `SIGKILL` to the custodian. Its detail names the pid or process group the reap could not prove\ngone, so check those processes before you retry. The command exits non-zero when any record is\nrefused. It is Linux-only and throws on other platforms.\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\nA `send dm` prints one line naming three facts: `\u2192 <name>  stored seq <N>; recipient <status>\nat send; delivery not confirmed  <text>`. `stored seq N` is the JetStream sequence the broker\nassigned to the publish; `recipient <status> at send` is the roster status (`idle`, `working`,\nor `offline`) resolved right before the publish, which can change the instant after; the send\nnever prints `delivered`, because the sender's credential cannot read the recipient's durable\nto confirm it. Inspect what the broker actually holds for a recipient with\n[`cotal deliver pending`](#deliver).\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n`cotal send` works from an operator shell or from a seat. Its display name is `<login>@<host>` of\nthe shell that ran it, so the recipient can tell one operator's send from another's; it is taken\nfrom the operating system, never from `COTAL_NAME`. The wire principal comes from the resolved\noperator credential or user bearer, not from `COTAL_NAME`, `COTAL_ID`, `COTAL_OWNER`, or\n`COTAL_ACTOR`. On an open mesh the transient endpoint self-mints its principal.\n\nThe transient endpoint never joins the roster and binds no inbox. A recipient can still answer a\n`send dm` or `send ask` with `cotal_dm`, by the sender's name or by the id on the message it\nholds: the reply is stored under the sender's id in the space's DM history, which an operator's DM\nview such as the dashboard's Direct messages lens shows. The `cotal send` that asked has already\nexited, so the reply never reaches that shell.\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | none | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | none | `set`: replay window size |\n| `--desc <s>` | none | `set`: one-line channel description |\n| `--instructions <s>` | none | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived\nchannel-writer view, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\nOn a remote user-auth mesh that view is served by the public exchange; space-history `purger`\nand the read-only admin view are not.\n\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | none | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. Inside the TUI, operator control (`D` kill, `:spawn`, `:status`, `:purge`) rides the\nsame per-action instrument path as `cotal stop` and `cotal ps`, never the observer; a raw\n`--creds` file cannot drive it. `a` (or `:attach <agent>`) runs\n[`cotal attach`](#managed-seats) in place and returns to the console on detach. See\n[Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal web [--detach] [--host <host>] [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--host <host>` | `127.0.0.1` | Concrete HTTP bind and browser host; wildcard addresses are refused |\n| `--port <n>` | `7799` | HTTP port |\n| `--detach` | off | Run in the background; stop with `cotal down web` or bare `cotal down` |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships inside `cotal-ai` as the `@cotal-ai/web` extension, seeded automatically on first\nrun (like the built-in connectors) so it always matches your CLI version. It self-registers `cotal web`\ninto this surface and serves\n`http://cotal.localhost:7799` by default (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. The public exchange serves `channel-purger` for a remote owner; it still\nrefuses the startup admin view, so a remote `cotal web` is not a complete channel-management\nsurface. Detached mode re-execs the current Cotal installation, writes diagnostics to\nthe mesh root's `.cotal/web.log`, and reports success only after the HTTP server answers. It requires\na recorded mesh root, but can be launched from any directory once `cotal up` has recorded the mesh.\nSee [Watch a mesh](watch-a-mesh.md).\n\n## deliver\n\n```bash\ncotal deliver [--space <s>] [--server <url>] [--tls] [--creds <file>] [--root <dir>] [--shard <n>] [--shards <n>] [--dev-mint]\ncotal deliver pending <name> [--limit <n>] [--durable <name>] [--json]\n```\n\nWith no positional, `cotal deliver` runs the delivery daemon (see\n[the delivery daemon](delivery-daemon.md)). `deliver pending <name>` never starts the daemon: it\nis an operator-only read over one recipient's DM durable, for the moment after a send when the\nquestion is \"what does the broker actually hold for them.\" It resolves `<name>` against a short\npresence watch (an `offline` card still counts, since the recipient may be dead, that is what\nthe verb exists to inspect); when neither a card nor the durable can be found, it prints\n`\u2717 not-found: no agent \"<name>\" and no DM durable for it in space <s>` and exits non-zero, never\n`pending 0`. On a match it prints the durable name and one fact per line: `pending`,\n`ack-pending`, `delivered`, `ack-floor`, `created`, `frontier`, and the stream's `max_age` /\n`max_msgs_per_subject` / `discard` limits (`--json` prints the same facts as one object), followed\nby a bounded, unacked read of up to `--limit` (default 20) recent candidate message ids under the\nheading `recent candidate ids (from the ack floor; not proof of a hole)`, a list of what is\nthere, not proof that nothing was lost.\n\nThe verb needs the `admin` credential profile: it runs through the same static-mesh route as\n`cotal mint --profile admin`, and refuses a user-mode mesh, naming the retired static credential,\nbecause there is no user-mode inspection authority yet. Pass `--creds <file>` for an off-registry\nadmin credential. A same-name respawn never inherits a predecessor's held DMs (the durable is\nlifecycle-keyed); an old lifecycle's durable is reachable only by the name a live read printed\n(the `<durable>` line on the first line of this verb's output). Pass that name with `--durable\n<name>` to read it directly once the lifecycle's card is gone from the roster. This skips the\npresence watch on `<name>` entirely, so `<name>` is required but only echoed in error text.\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\ncotal mint <name> --provision [--role <role>] [--space <s>] [--server <url>]\ncotal mint <name> --expires-in <seconds> | --expires-at <unix-seconds>\ncotal mint <name> --identity <creds> [--expires-in <seconds>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/space.<key>/<name>.creds` | Output path - the default sits under the resolved space's segment (`<key>` is that space's hex encoding, as in [Project files](config.md#project-files)) |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | the agent file's, else subscribe | Read-ACL override, **agent profile only**: `observer` and `admin` carry a fixed read set, and `mint` refuses this flag there rather than narrowing nothing |\n| `--allow-publish <a,b>` | the agent file's, else deny | Post-ACL override, **agent profile only** |\n| `--role <role>` | the agent file's | Agent profile: the anycast task queue the identity pulls (`svc_<role>`) |\n| `--provision` | off | Agent profile: also pre-create the identity's bind-only DM/deliver durables (and its role's task queue) on the live mesh, so the credential can consume |\n| `--expires-in <seconds>` | unbounded | Bound the credential's lifetime: the JWT `exp` is `iat + <seconds>`. A positive integer; refused together with `--expires-at` |\n| `--expires-at <unix-seconds>` | unbounded | Bound the credential to an absolute `exp` (unix seconds). Refused together with `--expires-in` |\n| `--identity <creds>` | a fresh identity | Re-mint for the nkey carried by this creds file, keeping the principal and every durable keyed to it. The file is read by the same loader the endpoint uses; a file with no seed is refused by name |\n| `--space <s>`, `--server <url>` | the resolved mesh | Which root supplies the agent file, static trust and default credential storage; with `--provision`, also which live mesh receives the durables |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\nFor an agent profile, the resolved mesh root supplies the persona ACL, the signing material and the\ndefault credential destination as one authority. If the current folder also holds trust for a\ndifferent space or account, mint refuses before writing and names both roots. It never combines a\npersona from one root with credentials signed or stored under another.\n\nA plain mint is creds only: the identity can publish within its post ACL at once, but on an authed\nmesh its DM inbox and task queue are provisioner-pre-created and bind-only, so a **consuming**\nconnect fails until they exist. `--provision` performs that pre-create in the same command (a\nprovisioner cred is minted from the space's trust material, used, and dropped), so a long-running\nclient you start yourself can receive DMs and role anycasts like a spawned seat. The command prints\nthe identity's principal (its wire id) and lifecycle uid; a consuming client passes that uid as its\n`lifecycleUid`. Agent profile only; an open mesh needs none of this (peers self-create there). The\nsame resolved authority is used for both the credential and `--provision`, so the broker\nfootprint cannot be created under a different root's trust material.\n\nThe CLI-mintable profiles carry no default TTL: without a lifetime flag the credential is\nunbounded, and a standing-renewal consumer refuses it. `--expires-in <seconds>` (or\n`--expires-at`) is the door the renewal seam's own error names. `--identity <creds>` re-mints for\nthe nkey the file already carries, so the new credential presents the SAME principal and every\ndurable keyed to it survives; combine it with a lifetime flag to rotate an expiring credential\nwithout churning the identity.\n\n## Login\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. When the trusted\n`/token` response advertises a same-origin space catalog, login validates and records that account's\nspaces immediately. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session, clears its cache, and removes only that\naccount's discovered registry entries. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\n# an upsert of the WHOLE row: name all three ACL flags, or pass --full for the wide defaults below\ncotal actor grant <actor> --sub <IdP subject> --scope a,b --allow-subscribe a,b --allow-publish a,b [--role <r>] [--label <l>]\ncotal actor grant <actor> --sub <IdP subject> --full [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | none | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | none | The derived owner token (alternative to `--sub`) |\n| `--full` | off | Fill each ACL flag left off with its wide default; without it, `grant` refuses unless all three are named |\n| `--scope <a,b>` | `spawn,role:default` with `--full` | Capability scope (`''` = none; `spawn` = may run agents; `role:<r>` = may delegate role r; `admin` = cross-agent control; `supervise` = eligible for the closed remote manager-service view when the host enables it) |\n| `--allow-subscribe <a,b>` | `>` (all channels) with `--full` | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) with `--full` | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | none | Role (scopes the task-queue consumer) |\n| `--label <l>` | none | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\n`grant --full` is the **full** envelope (all channels; scope `spawn,role:default`, so it may spawn and may delegate the default role). A\n`grant` that leaves off `--scope`, `--allow-subscribe` or `--allow-publish` without `--full` is\nrefused and writes nothing. A re-grant **replaces the whole row**, not the one field you name, so to add a capability spell\nevery field out: the new scope plus the row's current read set, post set, role and label\n(`cotal actor list` shows what a row holds). Under `--full`, a field left off does not stay as it\nwas: it reverts to the wide default in the table above. A re-grant retires the current interactive lifecycle through the running auth\nservice before it rotates the row, so copied bearers cannot cross an authorization update. If that\nretirement cannot be confirmed, the row is left unchanged and the command fails with the recovery\naction. `revoke` uses the same retirement before deleting the row, which lets a later grant create a\nreal successor instead of colliding with a live predecessor. `supervise` is separate from `spawn` and `admin`: it only makes a signed-in\nperson eligible for the host-provided closed remote manager-service view; it does not grant\nmanagement of another owner or a general host profile. `revoke` denies the next exchange and\nthe next connect with no restart, and evicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at. `--fix` takes the mesh's renewal lease when the broker answers and refuses while\na manager or another doctor holds it; with no broker it repairs offline and says so.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | none | Your presence name |\n| `--role <r>` | none | Your role |\n| `--channel <c>` | none | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | none | Join link (`cotal://\u2026`) |\n| `--token <t>` | none | Join token |\n| `--lifecycle-uid <uid>` | none | Required with `--creds`: the lifecycle UID minted alongside the credential (`COTAL_LIFECYCLE_UID` works too). A credential's durable grants name exact lifecycle-keyed resources, so `join` refuses to invent one |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext                 # same as `list`\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\ncotal ext root            # print just the install prefix (scriptable)\ncotal ext seed [--repair|--reset|--force]\n```\n\nOperator-installed extensions: `add` installs an npm package into a cotal-owned prefix and records\nevery registry provider it contributes. Commands appear in help, completion, and dispatch; runtime\nproviders are lazy-loaded by commands such as `supervise`; local process providers participate in\n`status` and selective `down`. `remove` and `list` manage them. The `@cotal-ai/web` dashboard is the\ncanonical command/process example. Installed packages and their location are described in\n[config](config.md).\n\nBare `cotal ext` lists the inventory, headed by the install prefix. That prefix is a cotal-owned npm\nroot kept **separate** from npm's own global tree. These packages never show up in `npm list -g`,\n`cotal ext` (or the Extensions section of `cotal status`) is the canonical inventory. `cotal ext root`\nprints only the path, for scripts. The versions shown are the manifest pin recorded at add time.\n\nRemoving an extension that owns a running local process is refused with the mesh root and its\n`cotal down <component>` command; stop it first so uninstalling the package never strands a process\nwhose lifecycle provider is gone.\n\n### Built-in connectors are seeded extensions\n\nThe first-party agent connectors (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`) are not compiled into\nthe binary. They are seeded on first run through the **same** `ext add` path a third party uses, and\nappear in `cotal ext list` like any other extension. So you can remove one you do not want\n(`cotal ext remove @cotal-ai/connector-hermes`), and a deliberately-removed connector STAYS removed\nacross upgrades. `cotal ext add <your-package>` adds a third-party connector the same way. The web\ndashboard (`@cotal-ai/web`, providing `command:web`) is the seventh built-in seeded on the same path.\n\n`cotal ext seed` is the maintenance entry for that seeding (it runs automatically on the first real\ncommand of each boot, so you rarely call it). Each seeded connector's `\u2713 added` line goes to stderr,\nso the command that triggered the seed keeps stdout to itself:\n\n| Flag | Meaning |\n|---|---|\n| (none) | Reconcile: seed any never-seeded built-in, refresh a seeded one whose version the binary bumped, leave a removed one removed. A no-op once current. |\n| `--repair` | Recover after an interrupted seed or a lost authority (rebuilds the interrupted connector; restores the removed-vs-never-seeded record from its durable backup). |\n| `--reset` | Discard the record and re-seed all seven built-ins (the six connectors plus the web dashboard). **Resurrects any you removed.** Rebuilds cleanly over corrupt seed state. |\n| `--force` | Re-seed the built-ins even when the version stamp is current or a downgrade. |\n\nWhen a newer `cotal` advances the operator-global seed store to its generation, it prints one\nmigration line naming the old and new generations, the exact CLI entry that wrote the store, the\ncommit timestamp, and `seed/stamp.json`. That writer and timestamp are kept in the stamp, so a later\nolder CLI refusal can say which executable wrote the generation it will not overwrite and when.\nLegacy generation-only stamps remain readable; their refusal simply has no writer provenance to add.\n\nAn older `cotal` refuses a seed store written by a newer version. When it can verify a sufficient\n`cotal` executable on PATH or at the installer's `~/.local/bin/cotal` location, the refusal names\nthat absolute path so a reduced service PATH does not select the older binary again. Otherwise it\nkeeps the generic newer-version instruction. `--force` rebuilds the store for the running older\nversion without discarding the ever-seeded authority. `--reset` still exists for corrupt state and\nresurrects deliberately-removed connectors.\n\nA source-checkout CLI (`pnpm cotal`, `tsx bin/cotal.ts`, `node bin/cotal.ts`, or a suite child of\nthose) refuses to write or garbage-collect that store. The refusal names the path, the generation\nit declined, and `$XDG_CONFIG_HOME` as the isolation remedy. `COTAL_HOME` does not relocate this\nstore. An entry that cannot be proven as a released install is refused the same way. Isolated\nrelease tests that must seed from a checkout-shaped `bin/` set `COTAL_ALLOW_CHECKOUT_SEED=1` after\npointing `$XDG_CONFIG_HOME` at a scratch dir; that override is documented here, not on the refusal\nline. An opt-in write still records the checkout path in `seed/stamp.json` as `writtenBy`.\n\nThe default connector for a bare `cotal spawn` (no `--agent`) is the persona's `agent:` pin if it\nhas one, else `claude`; set `COTAL_DEFAULT_AGENT` (e.g. `opencode`) to change the fallback. It is\na default, so a persona that pins its harness still wins over it. An `--agent` naming a removed\nconnector fails loud with the exact\n`cotal ext add` to restore it. Set `COTAL_SKIP_CONNECTOR_SEED=1` to turn off the automatic first-run\nseed/refresh entirely (for a controlled or offline setup that manages connectors by hand); `cotal ext\nseed` still runs on request. `cotal agent-bearer` never takes the seed at all: it is exec'd by\nspawned seats on every bearer refresh, so it neither reconciles nor is refused by the store's\ngeneration (see [Plumbing](#plumbing)).\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | none | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | none | Longer free-form details |\n| `--severity <s>` | none | `low` \\| `medium` \\| `high` |\n| `--area <a>` | none | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | none | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## run\n\nOperate durable workflow runs (cotal-lang programs) from the terminal.\n\n```bash\ncotal run start --file <program> [--timeout <dur>] [--local]\ncotal run resume <runId> [--local --file <program>]\ncotal run ps [--endpoint <ep>] [--json]\ncotal run journal <runId> [--endpoint <ep>] [--json]\ncotal run answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>]\ncotal run amend <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>]\ncotal run migrate <runId> --local --file <program> [--endpoint <ep>]\n```\n\n`start` hands the program to the mesh's manager, which validates it, mints the run id (the record\nnever takes a caller-supplied one), drives it in its own process, and answers with the id once the\nrun is recorded; a program that does not validate is refused with every problem listed. `resume`\nasks the manager to take an existing run back and continue it from its step journal; the source is\nthe recorded program, so no `--file` is taken. Neither takes `--endpoint`: the manager records\nits runs under its own endpoint, and naming another is refused. `ps` lists the run records and\n`journal` renders one run's durable records; both only inspect. An open pause prints its question.\nA pause settled with an accepted answer prints its value as JSON plus the recorded answerer,\nartifact when present, time, and answer id, then one `amended` line per later amendment, in the\norder the store committed them, so the last is the current position.\nExpired pauses and ordinary steps print no answer line.\n`--json` on `ps` or `journal` prints each row the manager answers with (or `--local` reads) as one\nJSON object per line. A `ps` row carries `runId`, `endpoint`, `state`, `holder`, `epoch`,\n`journalHigh`, `forkedFrom`, `startedAt` and `programHash` (the values the program's `run()`\nreports; `programHash` is absent for a run with no recorded program), and `revoked` or\n`revocationUnreadable` when the marker says so. A `journal` row is an `activation` or a `step`. A\nstep row carries its `step` key, the `effect` kind and its `name`, `state`, `outcome`, the recorded\n`status` and `errorCode` once settled, and `startedAt` and `endedAt` in epoch milliseconds. An open\npause adds its `asks`, its `deadlineAt`, and for a checkpoint the `onExpiry` it was armed with; a\nsettled pause adds its `answer` and its `amendments`, as the text view prints them. A field the\njournal does not record is absent: a checkpoint opened before `onExpiry` was recorded carries none.\nThe run header and errors go to stderr, so stdout carries only rows; an unreadable revocation marker\nprints its reason there and still exits 1. The text view is presentation and is not a stable\nparsing target. `--json` on any other verb is refused.\n`answer` resolves an open\ncheckpoint through the manager, presenting as the holder that armed it; the manager records the\nanswerer from your credential, so no `--by` is taken there. A settled step refuses a second\n`answer`. `amend` records a changed position on a settled checkpoint or `ask`: it files a new\nanswer beside the accepted one, naming it, and the journal lists it under the step. The pause stays\nsettled and the run keeps the answer it acted on. A step that is still open or settled without an\nanswer refuses an amend. A spawned seat may amend only an answer recorded under its own name. `migrate` runs the migrate check of an\nedited program against a run's journal, from this terminal under a read credential (`--local`\nonly; the manager serves no run-migrate command): it prints whether the migration is admissible,\nevery orphaned step with its verdict and code, and exits 0 on admissible and non-zero on not. It\nwrites nothing: the commit that would file the migration is not reachable yet, and the report\nsays so. `--timeout` sets the default\ncheckpoint timeout for a drive (default 1h). `--local` drives in this process instead, over one\nconnection per invocation under the run's own credential minted from the project folder's trust\nmaterial, and is the path on a bare broker with no manager or for a run with no recorded program\n(`cotal run resume <runId> --local --file <program>`); `answer --local` and `amend --local` take\n`--by <who>`. On a\nuser-auth mesh the host's own manager refuses the family by name, and `--local` has no credential\nthere. A participant's manager started with `cotal supervise` hosts a logged-in user's runs through\nits issuing host: the auth callout issues the user's manager connection, and every `run` verb rides\nthe versioned rail under that issuance.\n[User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path. The guide is [workflows](workflows.md).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>] [--root <dir>]\ncotal auth-service --space <s> --server <url> [--port <n>] [--exchange-public-port <n>] [--exchange-public-url <https://\u2026>] [--exchange-trusted-proxy]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane: the NATS auth callout, the\ncapability-gated local exchange and JWKS, and, when `--exchange-public-port` is set, the closed public\nexchange/discovery face forwarded by an HTTPS reverse proxy. `--exchange-public-url` is the proxy URL\nadvertised to clients; `--exchange-trusted-proxy` opts into last-hop `X-Forwarded-For` attribution.\n`cotal up --user-auth` starts and supervises the service for you, so you run it directly only to\nrecover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. `--creds` can start a\ndaemon that already looks healthy, but production renewal is not that file alone: the manager and\nthe daemon must address one credential store. On a stock split host with two project roots, a\ndirect `deliver` is not an independent repair; keep the daemon under `cotal up` on the broker\nhost, or inject the same store into both processes ([embedding](embedding.md#supervisor-signing-authority)).\nTyped by hand on the workstation, `deliver` dials the broker recorded for `--space` in the mesh\nregistry (a mismatching `--server` is refused before any dial, and a record for a different\nworkspace root is refused outright); with no record for the space it falls back to the local mesh.\nThe daemon serves the workspace root that `--root <dir>` names, which must hold `.cotal/`, or else\nthe nearest `.cotal/` above its working directory. With neither, it refuses at start and names the\ndirectory it searched from, before it reads a credential or dials a broker.\nSee the [delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. Its local arm uses `--dir` to discover the\ncapability-gated loopback service. A remotely enrolled, already-granted agent instead receives\n`--exchange-url <https://base>` in its launch argv: that arm sends `{owner, actor, actorToken}` to the\npinned public exchange with no local capability, follows no redirects, and refuses every non-HTTPS\nURL because the actor token is the credential in the request body. Because a seat execs it on every\nbearer refresh, it skips the connector-seed boot gate entirely: it reads one 0600 token file,\nexchanges it and prints the bearer without consulting or writing the operator-global seed store, so\na newer store generation cannot refuse a live seat's refresh. `--manager-call` asks for the\ninstance-bound `manager-caller` view; `--manager-instance <id>` selects an explicit live candidate.\nThat mode still prints only the raw token and does not update `--health-file`. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
+      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 22+)\ncotal --help              # every command, grouped\ncotal --version           # cotal-ai version + each installed extension's (also `cotal -v`)\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nAn undeclared flag is a usage error, and so is a flag given more than once unless it is\nrepeatable, as `--opt` and `down --session-store` are. The command prints the error and its help,\nexits 1, and does not run.\n\nCommand output, including error lines on stderr and the guided `setup` and `meshes add` prompts,\nis colored only when stdout is a terminal, so piped or redirected output is plain text. A non-empty\n`NO_COLOR` turns color off on a terminal too. `FORCE_COLOR` turns color on even when output is\npiped, unless it is `0` or `false`, and it takes precedence over `NO_COLOR`.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` installs any registry providers a package contributes: commands,\nruntimes, and local process lifecycle descriptors. The `web` dashboard and optional manager\nruntimes ship this way.\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`update`](#update) | Reconcile first-party extensions and check or opt into a coherent CLI upgrade |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop the whole stack, selected registered components, or a manifest deploy |\n| Set up & lifecycle | [`backup`](#backups) | Create an offline full-space or registry-only artifact from a preserved cut |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#mesh-registry) | List the running meshes on this machine |\n| Set up & lifecycle | [`sync`](#mesh-registry) | Refresh the signed-in account's advertised spaces |\n| Set up & lifecycle | [`use`](#mesh-registry) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#mesh-registry) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#managed-seats) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#managed-seats) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#managed-seats) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`input`](#input) | Type one line into a managed agent's terminal without attaching |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Agents & personas | [`service`](#service) | Run the manager as a user service (survives logout and reboot) |\n| Agents & personas | [`runtimes`](#runtimes) | List the agent runtimes the manager can spawn through and whether each is reachable |\n| Agents & personas | [`seats`](#seats) | List the pty seat custodians an earlier Linux manager left, and drain the ones whose agent has exited |\n| Agents & personas | [`reconcile-gate`](#reconcile-gate) | Unfreeze an issuance gate left frozen by a crashed restart when the successor cannot boot-heal it (holder gone, complete CONNZ sweep) |\n| Messaging & watching | [`endpoints`](#endpoints) | List every endpoint in the live presence roster, including infrastructure |\n| Messaging & watching | [`describe` / `invoke`](#endpoint-control) | Resolve a v0.4 service's command surface off the wire; invoke one command by name |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Workflow runs | [`run`](#run) | Operate durable workflow runs: start, resume, list, inspect, answer a checkpoint, check an edited program with migrate |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes] [--skills]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n| `--skills` | off | Reconcile Cotal skills only through installed connector providers, plus `~/.agents/skills`. Refused with `--full` or `--demo`. |\n\nGuided setup is **configure-only**: it checks prerequisites, invokes installed connectors' declared setup providers, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. `cotal status` points stale Claude skills and\nout-of-date `.agents` skills at `cotal setup --skills`, not unscoped `setup`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\nWhen a mesh resolves, setup seeds that mesh's recorded `.cotal/agents` catalog, the same catalog a\nfollowing `cotal spawn` reads. It prints the absolute destination. On a fresh machine with no mesh it\nuses this folder and says why; when several meshes are available and none is selected, it refuses\nrather than choosing a catalog.\n\n## update\n\n```bash\ncotal update [--self] [--space <s>] [--server <url>] [--creds <path>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--self` | off | If a newer release exists, install that exact validated `cotal-ai` version globally and reconcile through the newly installed binary |\n| `--space`, `--server`, `--creds` | resolved mesh | Select the running manager whose continuity state is reported |\n\nWithout `--self`, `update` keeps the installed first-party surfaces coherent with the running\nbinary: it force-reconciles the four built-in connectors, then reinstalls other `@cotal-ai/*`\noperator extensions at the binary's exact version. Each extension runs in an isolated child, so one\nfailure cannot poison later replays. It then checks npm; a newer binary is an informational notice\nwith `cotal update --self` as the next command, not an automatic install.\n\nAfter disk reconciliation, `update` reads the selected running manager. A machine with no recorded\nmesh has no running manager to observe, so that read is skipped and the command completes. The same\nholds when every recorded mesh is down and none is selected. A remote user mesh, registered with\n`cotal meshes add --mode user`, is named and skipped: its manager runs under another install, so\nthere is no custody on this machine to preserve, and a `legacy` verdict still comes only from a\nmanager this machine read. A recorded mesh that is down is still a\nrefusal when the command selects it, with `--space` or by running inside its project, and so is a\nnamed space that is not running. With several meshes running and no `--space`, `--server` or\n`--creds`, the install is machine-wide, so every running manager is reported in turn, each under its\nspace name, before anything is written; a `legacy` verdict on any of them makes the whole run not a\nhot update. A selector flag still reports one manager. A manager without a\ncustody generation is reported as `legacy`: it cannot preserve its manager-owned PTYs, so the\ncommand says that this is not a hot update and prints `exact`, `fork`, `fresh`, or `drain-only`\nfor every seat. This report sends no stop, preservation-commit, or replacement command.\nIt does not preserve a running PTY on a legacy manager. The built-in pty runtime spawns\nin-process on every platform and reports `legacy`. On Linux it still adopts seats that an earlier\nmanager left under a detached custodian, but it starts no new custodian. An incompatible native\n`@lydell/node-pty` or ConPTY ABI break remains an explicit per-seat maintenance cut.\n\nWith `--self`, the selected running manager is reported before any global install. When a newer\nrelease exists, Cotal then installs the exact version it validated, resolves and verifies that\npackage in npm's global root, then launches that binary with the same `--space` / `--server` /\n`--creds` selection to reconcile connectors and first-party extensions to the new generation. An npx\nor dev-clone invocation therefore installs and continues through a separate global copy; it never\nclaims the already-running process changed. If the binary is current, `--self` performs the normal\nlocal reconcile without reinstalling it.\n\nThird-party extensions are listed with their installed version and recorded spec but are not\nauto-updated in v1. Floating third-party updates require `@cotal-ai/*` peer-range validation and are\na future follow-up. A failed connector/extension install, npm metadata check, or requested global\ninstall is reported and makes the command exit nonzero. Independent extension attempts continue so\nthe output includes every failure; an unavailable npm registry does not undo a completed local\nreconcile, but the command still exits nonzero because it could not establish that the install is\ncurrent.\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>] [--runtime <name>]\ncotal up --user-auth --idp <url> [--exchange-public-port <n> --exchange-public-url <https://\u2026> [--exchange-trusted-proxy]]\ncotal up --tls-cert <cert.pem> --tls-key <key.pem>   # serve broker TLS (both, or neither)\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | none | Bind host override for a **fresh** broker boot: an IP or hostname only, never a URL (that is `--server`) and never `host:port` (the port comes from `--server` or its default); a URL or port-bearing value is refused pointing at the right flag. With no `--server`, the broker URL is derived from it, so `--host <addr>` alone is enough to make a mesh reachable at that address; a `--host`/`--server` pair naming different addresses is refused. A wildcard bind (`0.0.0.0`, `::`) keeps a dialable loopback URL. Recorded on the mesh and reused by every later manager launch, so a repair or resume keeps remote [`attach`](#managed-seats) working. A live refresh (`\u2713 mesh already running`) does not rewrite `.cotal/auth/server.conf` or rebind nats; stop the broker, then re-run `up --host` |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | none | JetStream store directory (recorded; a repair up reuses it) |\n| `--max-file-store <bytes>` | nats-server's dynamic cap | JetStream file storage cap in bytes (a positive integer, no unit suffix). Without it nats-server sizes the store at start as three quarters of the free space on its filesystem. The cap is fixed at broker start: a running broker cannot change it (`cotal down` first), `down --preserve-state` keeps it for the resume, and a resume with a different value is refused. Not accepted with `-f` |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--restore <dir>` | none | Restore a completed offline backup before exposing the normal listener |\n| `--restore-only registry` | artifact selection | Restore only the registry component |\n| `--accept-missing-source` | off | Explicit disaster consent when the inode-bound preserved source is absent |\n| `--accept-stale-checkpoint` | off | Explicit consent to resume a seat whose checkpoint was captured outside its recorded recency horizon |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | none | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--exchange-public-port <n>` | none | With `--user-auth`: add the public exchange face on this loopback port, for an HTTPS reverse proxy to forward to |\n| `--exchange-public-url <https://\u2026>` | none | With `--exchange-public-port`: advertise the reverse proxy's HTTPS URL in discovery |\n| `--exchange-trusted-proxy` | off | With `--exchange-public-port`: attribute public failure buckets to the last `X-Forwarded-For` hop. Enable only when the listener is reachable solely through a trusted proxy; otherwise the socket address is used |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--tls-cert <path>` | none | PEM certificate to serve TLS with. Must be given together with `--tls-key`. Before starting the broker, Cotal checks readability, private-key mode, key/certificate match, the validity window, and host coverage. `nats-server` accepts an expired certificate and leaves the failure to clients, so Cotal performs these checks first. The decision is recorded; a later bare `cotal up` keeps serving TLS |\n| `--tls-key <path>` | none | PEM private key for `--tls-cert`. Refused if group- or other-readable (tighten to `600`) |\n| `--file <cotal.yaml>`, `-f` | none | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <name>` | `pty` (or the manifest's, with `-f`) | Agent runtime for the mesh manager (`pty` built in; others are installed extensions, explicit-only). Resolved + probed before the broker starts; an uninstalled/unreachable runtime fails loud. With `-f`, overrides the manifest's runtime |\n| `--max-sessions <n>` | 64 | Live-session ceiling for the mesh manager. Each console pane and each `cotal attach` is one session, so size for agents \xD7 panes, not agent count. Recorded on the mesh and reused by every later manager launch, so a repair or resume does not silently drop back to 64. A running manager cannot change it: `cotal down` first, then `cotal up --max-sessions <n>` |\n| `--no-manager` | off | Broker-only boot: start the broker and, in auth mode, the delivery daemon, and no local manager. A refresh under the flag of a mesh whose manager is live refuses rather than keeping or stopping it (`cotal down manager` first). Cannot be combined with `--runtime`, `--max-sessions`, or an agent-declaring manifest |\n| `--rotate-sys` | off | Rotate the space's system account and re-mint its two `$SYS` creds. Needs a stopped mesh; refused with `--open` |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). `--no-manager` is the broker-only mode: it boots\nthe broker (and the delivery daemon in auth mode) and starts no manager, so there is no manager\npidfile to leave stale. A refresh under the flag of a mesh whose manager is live refuses rather\nthan keeping or stopping it: `cotal down manager` first. For a split topology with a manager, wait for `.cotal/manager.<spaceKey>.log` to contain `\u2713 manager up`, then `cotal down manager` on that\nhost and run [`supervise`](#supervise) against the remote broker; see\n[Run a mesh](run-a-mesh.md). `cotal up --detach` prints `\u2713 running in the background:` with\n`manager` listed (pidfile liveness, not a teardown boundary); with `--no-manager` the line lists\nonly what actually started. Ctrl-C on a foreground `up` stops the stack and reports managed agents\nunder the same rule as bare `cotal down` (see [`down`](#down)): when the manager cannot prove it can\nspare, Ctrl-C refuses the teardown, prints the refusal with the reap route, and leaves the stack\nrunning. The `-f` form is a\n[manifest deploy](#manifest-deploys).\n\nA repair `up` on a mesh whose broker died reopens the store its record names, and refuses a\ndifferent `--store-dir` rather than silently opening a second store.\n\nThe generated `.cotal/auth/server.conf` is written on a real broker boot and is not an\noperator-owned config. `--host` changes that file only when nats is actually started. A unit\nrestart that leaves an answering listener in place is a refresh, not a rebind.\n\nOn an existing mesh, `cotal up` reconciles the presence and lease bucket TTLs. It writes a reserved\ncanary and waits for the bucket to expire it before reporting success. If the broker accepts the\nstream update but the backing store does not persist or enforce it, `up` exits nonzero with a TTL\npersistence error instead of trusting the value returned by stream info. A refresh that restores a\nmissing manager says so with its pid (`\u2713 restored in the background: manager (pid N)`); a refresh\nthat finds everything already running prints only the `\u2713 mesh \"<space>\" already running` line.\n\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker: the NATS\nauth callout plus its capability-gated local exchange, and optionally the closed public exchange\nface configured by the three `--exchange-*` flags above. The service is torn down with `cotal down`,\nand a re-run of `cotal up` heals a dead service on a running broker. `up` waits for the service to\nfinish binding: while the daemon it launched (or found running) stays alive, the wait extends past\nthe base 15s up to 60s; a daemon that exits is refused at once with \"exited before becoming ready\",\nand one alive past 60s is refused as \"alive and still starting\" (wedged), naming the pid record and\nthe service log. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n`--rotate-sys` renews the two `$SYS` credentials (`membership-observer`, `connection-evictor`).\nThey carry a 30-day expiry and nothing re-signs them in place, because the system-account seed is\nnever persisted, so they are renewed by issuing a **new system account** under the same broker\noperator and minting fresh creds against it. A plain re-`up` does **not** do this: it reuses the\nexisting trust record, and its `$SYS` creds along with it.\n\nThe rotation is safe to run on a real space, with one operational cost. The data account, the account\nsigning key, every agent credential minted from it, and the JetStream store are all untouched; what\ndies is the retired system account, and with it any out-of-band copy of the old `$SYS` creds, on every\nbroker that loads the rotated config. The cost is that **earlier full backups stop being restorable**\n(see below), so this is not a no-consequence operation. It needs the broker to restart on the rewritten\nconfig, so it runs as part of a boot:\n\n```bash\ncotal down\ncotal up --rotate-sys --detach     # agents reconnect; nothing is re-provisioned\ncotal doctor auth                  # both $SYS creds healthy again, 30 days out\n```\n\nA rotation is a stopped, fresh boot, and anything that is not one refuses it, all for the same reason\n(the on-disk material and the broker it runs on must never end up on different generations):\n\n- a live mesh, because the running broker would keep serving the retired account;\n- an open mesh, whether that comes from `--open` or from `broker.auth: false` in a manifest, which\n  has no system account at all;\n- `--restore`, because reinstating a trust root and superseding it in one command leaves no way to\n  say which authority the mesh came up on;\n- an unfinished restore or resume attempt on this root, including one `cotal up` would recover on\n  its own, because those paths can adopt a live listener and return without booting a broker;\n- a root that hosts more than one space, because the system account lives in the shared broker\n  record and a rotation would retire every tenant's, while the root holds one `$SYS` cred pair\n  pinned to one data account.\n\nTwo things to know before you run it:\n\n- **The retirement is config-load-bound.** Old `$SYS` creds are refused by any broker that loads the\n  rotated config. A stale `nats-server` still running the *previous* config in memory would keep\n  honouring them, so stop every broker for this root first. `--rotate-sys` refuses if this root's\n  mesh is recorded as running, if anything unidentified is answering at the address it was given, or\n  if the root's pid file names a live (or unreadable) process. Those are Cotal's own ownership\n  records, not a scan of the process table: a `nats-server` you started by hand against this root's\n  `server.conf` on some other port writes none of them and will not be seen. Do not run one.\n- **It invalidates earlier full backups.** A full artifact binds to the trust chain it was taken\n  against, and that commitment covers the operator JWT and the system account. Every full backup\n  taken before a rotation refuses to restore afterwards, so take a fresh `cotal backup` once the\n  rotated mesh is up. `cotal up --restore` names this case when the data account still matches.\n\nThe commit is not atomic (a trust-record write plus two credential writes), so an interrupted\nrotation leaves the record ahead of the creds. That split is detected rather than silent: every\n`cotal up` on an auth mesh, and every `cotal doctor auth`, compares each `$SYS` cred's issuer against\nthe persisted record and names the retired account. `up` warns rather than refusing, because these\ncreds power the membership graph and live eviction, both of which degrade fail-soft; the mesh is not\nworth taking down over them. Re-running the rotation heals it, at the cost of one generation.\n\nWhile those creds are expired the mesh keeps delivering messages, but the\n[membership feed](delivery-daemon.md) and live connection eviction stay down; `cotal doctor auth`\nand the manager's log both name the credential and this repair.\n\n## down\n\n```bash\ncotal down\ncotal down --with-agents\ncotal down --preserve-state [--store-dir <dir>] [--session-store <dir> \u2026]\ncotal down manager [delivery auth web nats ...]\ncotal down web [--space <name>]\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | none | Tear down this manifest's deploy |\n| `--run <id>` | none | Tear down one `spawn -f` run by id |\n| `--space <name>` | current mesh | With components: the mesh whose target-addressed components (e.g. `web`) to stop |\n| `--dry-run` | off | Print the manifest teardown or selected components, mutate nothing |\n| `--with-agents` | off | Bare whole stack only: also stop and deprovision every managed agent |\n| `--preserve-state` | off | Bare whole stack only: fence the manager, retain principals and durable state, stop and prove the stack down, then publish `ready` |\n| `--store-dir <dir>` | `.cotal/nats` | With `--preserve-state`: the actual store path (required for a custom store) |\n| `--session-store <dir>` | none | With `--preserve-state`: a harness transcript store directory to capture with every continuation-capable retained seat. Repeatable. No default and never inferred from a connector name; a path that does not exist or is not a directory is refused before anything stops |\n\nBare `cotal down` stops the whole local stack in dependency order and leaves managed agents running\nwhen their runtime lets them outlive the manager. Before signalling the manager it verifies the spare\ncapability of the exact recorded manager, which records what that manager's stop does with its\nseats, and it reports the agents left behind plus `cotal down --with-agents` as the explicit reap.\nThe built-in pty runtime keeps each PTY inside the manager process, so those seats cannot outlive\nit: every manager stop stops and deprovisions them, and `down` reports them as stopped. Ctrl-C on a\nforeground `cotal up` follows the same rule: it verifies the spare capability, stops the stack, and\nprints the same report. When the capability cannot be verified, Ctrl-C\nrefuses the teardown and leaves the stack running; end it with `cotal down --with-agents`.\n`--with-agents` is a one-shot destructive policy bound to the exact verified manager process\nand the exact live `down` stop reservation; a stale, malformed, crashed, or different stop attempt\ncannot turn a later bare shutdown destructive. If a managed agent cannot be proven stopped within\nthe manager's stop timeout, the manager logs which one, still closes its broker connections and\nconsole listener, and exits with code 1. It does not release its pidfile, liveness lease or\nservice registration in that case, so no successor is handed authority while that agent may still\nrun; the lease lapses on its TTL. Positional component names stop\nonly those self-registered local processes; for example, `cotal down manager` leaves delivery and\nthe broker running, and `cotal down web` is available when the web extension is installed. A\ncomponent that starts target-resolved (the web dashboard) is stopped the same way: `cotal down web`\nresolves the mesh the same way as `cotal web` (registry current mesh first, `--space` to name one), so\nit works from any directory; the other components always stop under the folder you run it in. The\n`-f` / `--run` forms tear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh\nand cannot be combined with component names. Stopping `nats` alone is refused while an unselected\nregistered daemon is still live; include those components or use bare `cotal down`.\n\nA pinned manager with no spare-capability record is not signalled by bare `cotal down` or `cotal\ndown manager`. A current manager always publishes the record, so a missing one means an older\nmanager: one that predates capability reporting, or one whose pty runtime reported that it cannot\ndetach its agents. Stop each managed agent explicitly, then run `cotal down --with-agents` from the\nmesh root to stop the whole stack. An older manager does not understand\nthe reap request, which is why the agents must already be stopped.\n\nBare `cotal down` inventories by pidfile. When this folder's registered broker answers and no\n`nats.pid` records it, the command does not say nothing is running. It names the space and the\nbroker address, says no pidfile records that process, says it will not stop a process it did not\nstart, and exits 1. Stop that broker with whatever started it (an init unit, a container, or the\nhand-run process). `cotal meshes rm <space>` only drops the registration. The probe runs whether or\nnot other owned components were running: they stop and clear their artifacts first, then the broker\nis named. A component stop and `--dry-run` stay pidfile-only and do not probe.\n\n`down` reads each process record once. A component that exits and removes its own record while\n`down` runs counts as having no record, so the stop goes on. Any other failed read is an error.\n\n**Teardown verifies pinned process identity before signalling.** PIDs are recycled by every OS,\nso a recorded pid alone is not a durable target identity. `up` records each stack process's\ncreation identity in a sibling `<pidfile>.identity` pin, which holds the pid and the process start\nreported by the OS. Every stop path, including `down` for the broker, web and extension components,\nand the manager, delivery and auth-service stops, applies the same rule. A pin that names a different\nstart means the pid was reused, so teardown refuses and preserves it. A torn or unreadable pin also\nrefuses.\n\nThe pidfile and its pin are published by renames, and the pidfile rename is the commit point. Just\nbefore it, the pin holds two lines: the old process's and the new one's. A launcher that dies\nmid-publish therefore leaves the old record or the new one, each checked against its own pin line,\nnever a pidfile without its pin. An old record with no pin is legacy, so its line holds `-` in place\nof the token and it stays legacy until the commit. A CLI older than this change reads a two-line pin\nas torn and refuses.\n\nPublishes of one pidfile are serialized by a lock file beside it, `<pidfile>.publish.lock`, because\nthe launcher and the daemon it starts both publish the same record. The next publisher reclaims a\nlock left by a crashed one. When no start token can be read for the new process, its pin line holds\n`-` in place of the token, which reads as a legacy record, and the publish ends in the legacy shape:\na pidfile with no pin. Teardown, and a daemon removing its own record on exit, take the same lock and\nremove the record only while the pidfile still names the pid they stopped, so a stop that races a\npublish leaves the new record whole.\n\nThe pidfile pid and the pin pid are two coordinates. Automatic cleanup follows **proven death of\nthe pidfile target** (ESRCH on that pid): a torn sibling pin does not wedge a dead pidfile pid.\nA torn pairing where the pin names another pid, while the pidfile pid is still live or not proven\ndead, still refuses. Inspect both pids with `ps`. Do not delete `<pidfile>.identity` to force a\nstop; that weakens target-identity protection. Once the pidfile process is dead, rerunning\nteardown clears the stale record automatically.\n\nThe first teardown after upgrading a running pre-pin stack has a narrower guarantee. A live record\nwith no identity pin is signalled after a loud warning that it predates identity pinning. Restarting\nthe component writes the pin, so later teardowns receive full match and mismatch protection. The\nsame warning applies on platforms where no stable start token is available. For a legacy manager,\nbare `cotal down` also warns that agent sparing cannot be verified before it signals. Because the\nCLI cannot establish which SIGTERM handler that already-running binary carries, it never presents\nthe pre-signal seat inventory as confirmed spared; a genuinely older destructive handler may still\nreap those agents. `--with-agents` publishes a one-shot reduced-guarantee handoff bound to the\nrecorded manager pid and the live `.stopping` reservation's inode, then signals unconditionally.\nThat handoff cannot be replayed by a later stop attempt. A pin that exists and does not match the\nlive process still refuses before signal.\n\n`--with-agents` performs the old destructive logical teardown: managed processes stop and their\ncredentials, ACL rows, and delivery footprints are deprovisioned. `--preserve-state` is a different\nmaintenance transition: it stops retained processes while suppressing leave/deprovision cleanup, persists the manager's\nsame-principal resume inventory, stops the entire stack without removing run/auth artifacts, and\npublishes a stable inode-bound cut only after every recorded process is proven stopped and the exact\nrecorded NATS endpoint is unreachable. A missing or stale broker pidfile never counts as stopped. The\nattempt is bound durably before the manager is fenced, the resume document and attempt-bound\n`cut-intent` are fsynced before manager commit, and the manager's commitment itself is journaled\n(`cut-committed`) before any process stops. A retry after a crash at any of those boundaries reuses\nthe exact recorded attempt and finishes the remaining stop and endpoint proofs idempotently, without\nneeding the (by then intentionally dead) manager. A partial cut never publishes `ready`. It cannot\nbe combined with component names, manifest teardown, or `--dry-run`.\n\n**Seat checkpoints.** After the stack is proven down, the cut writes one checkpoint per retained\nseat under `.cotal/maintenance/v1/checkpoints/<attempt>/<seat>/`, and prints the path, the\ncontinuity class and the generation for each. The path carries the preservation attempt because a\ncheckpoint is immutable once sealed: a shared directory would make the second cut in a root refuse\non the first cut's leftovers, and clearing it would destroy an artifact a rollback still needs. The\ncapture happens only at that point because anything earlier races a harness that is still writing\nits transcript and its working tree.\n\nEach checkpoint directory is created 0700, refuses a destination that already exists, and holds:\n\n- `repo.bundle`, the seat `cwd`'s reachable history, anchored on the base commit the record names\n  by full object id;\n- `repo.index.diff` and `repo.worktree.diff`, the staging state as two diffs, base to index and\n  index to worktree. Two rather than one because a single combined diff restores a mixed tree with\n  the right bytes and the wrong index: a source reporting `MM README` would come back as ` M README`;\n- `repo.untracked.tar`, the untracked files in scope;\n- the harness session pointer, when the seat's connector declares one, and the transcript store\n  files the operator named with `--session-store`. Each records where the destination puts it back\n  as an anchor (the workspace root, the account home, or the seat's `cwd`) plus a relative path,\n  because the destination's root and home are its own and the source host's absolute spelling would\n  either miss them or write outside them;\n- `checkpoint.json`, written last, after every digest is computed over the bytes that landed.\n\nThe record carries the manager's resume entry unchanged as its first field, then the space, the seat\nname, the recovered `lifecycleUid`, the writer generation the cut was taken at, `capturedAt`, the\nrecency horizon, the applied profile revision, the seat's `git status --porcelain` as the cut read\nit, and the continuity class. Every captured file is\nlisted with its byte size and sha256, so an operator verifies the whole artifact with `sha256sum`\nand `git bundle verify`. No secret values, no operator keys and no source-host launch material\nenter it.\n\nThe continuity class is what the connector declares, capped by what the checkpoint carries. A\nconnector declaring session continuation classifies as `exact`, but reopening a session takes both\nhalves, the pointer that names it and the store that holds its transcript. A checkpoint missing\neither one cannot reopen that session, so it is recorded as `fresh` when the connector declares a\nfresh start and `drain-only` otherwise. A pointer with no store is capped the same way as a cut\ncarrying neither, because it names a session whose bytes the artifact does not contain. A class is a promise the destination is entitled\nto act on, so it never describes bytes the artifact does not contain. The transcript store stays an\noperator input: this repository does not know where a harness keeps its transcript, so `exact`\nrequires `--session-store` to name one.\n\nThe recorded status is read under the same selection rule as the untracked set, so it describes the\nstate the captured bytes can reproduce. The destination re-reads it in the promoted tree and refuses\na difference.\n\nThe untracked selection rule is recorded in the record and is\n`git ls-files --others --exclude-standard -z, excluding .cotal/`. It honors `.gitignore`, so an\nignored file the seat needs does not travel and has to be moved separately. The `.cotal/` exclusion\nis a secrecy boundary rather than a size one: when a seat's `cwd` is also the mesh root, the control\ndirectory is untracked, and without the exclusion the broker trust material, the space account, the\nmanager instance identity's private seed and the seat's own credentials would land inside the\nartifact. A checkpoint carries credential references only; the destination resolves that material\nitself.\n\nA seat whose launch options could not be resolved is refused rather than checkpointed, with the\nmanager's own wording: `imperative launch options have no non-secret durable source (<keys>)`. The\nrefusal arrives at prepare time, so the cut stops before any child does.\n\nA delegated seat (SPEC \xA713.17) is refused at prepare time too, with\n`a delegated seat is not resumed by a later manager; stop it before preserving`. A manager stop\nafter a refused cut retires that seat through its retirement path.\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\ncotal clean restore-attempt --attempt <id> --force\ncotal clean restore-fallback --attempt <id> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | none | Required: destructive, no prompting |\n| `--attempt <id>` | none | `restore-attempt`: exact stale pre-commit attempt; `restore-fallback`: matching healthy committed restore |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive or any same-root recorded broker endpoint remains reachable (run `cotal down` first). They\nalso refuse outright on a root that holds accounts for several spaces: the store and the broker\ntrust record are shared by every space on the broker, so both targets would take out all of them\nand no `--space` can narrow that. `down`, `backup` and `up --restore` refuse there for the same\nreason. `cotal status` lists the tenants on such a root. Personas\n(`.cotal/agents`) and logs are never touched. The mesh record now carries a custom\nstore location for `up`'s own repair, but `clean` still takes `--store-dir` itself; `clean` does\nnot read the record. Custom cleanup targets must contain either the Cotal store-generation marker or a\nreal `jetstream/` store directory; filesystem roots, project roots, and Cotal auth/maintenance trees\nare always refused.\n\n`store` and `all` also refuse every maintenance journal state. After a healthy committed restore,\n`restore-fallback` is the only supported way to remove the recorded unchanged old-store inode; it\nnever deletes the active target, requires both the exact attempt id and `--force`, and retires the\ncompleted restore journal so a later `down --preserve-state` can start a new backup cycle.\n\n## Backups\n\n```bash\ncotal down --preserve-state [--store-dir <dir>]\ncotal backup create <dir> [--only full|registry] [--store-dir <dir>]\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\n```\n\nBackup is offline-only. It requires the stable `ready` record from `down --preserve-state`, an exact\nstore match, no live recorded process, and an unreachable exact endpoint from the recorded cut.\nThat endpoint is probed immediately before cloning, so a live broker with a missing or stale pidfile\nis still refused. It claims the cut, reflink/copies the stopped source to a\nprivate attempt clone, and opens only that clone on a random loopback bootstrap broker with an\nindependent parent/deadline watchdog. It validates the canonical stream and pull-consumer inventory,\nwrites native snapshots with consumers excluded, and stores conservative contiguous ACK-floor\ncheckpoints separately. The presence bucket is memory-backed, so it does not survive the cut and\nthe clone may lack it. Every other stream must be present. The original store is never opened by\nthe backup broker, and the stack is not restarted implicitly. Artifact destinations must not overlap\nthe preserved source or maintenance\nattempt tree. Restore artifacts and targets likewise cannot nest inside or contain each other, the\npreserved source, or the maintenance attempt tree.\n\nStopped client-managed KV ordered consumers are ephemeral read residue, not backup state. Backup\nignores only the pinned client's exact stopped shapes: ordinary last-value watchers and the\nwhole-bucket scanner that uses all-history delivery to collapse concurrent tombstones. A bound\nconsumer or any lookalike with a different filter, inbox, lifetime, or other config is still refused.\n\n`full` is the default and indivisible: channel registry, CHAT/DM/TASK/INBOX/DLV, ACL, MEMBERS, and\nvalidated durable checkpoints. `registry` is the sole partial artifact. Presence, derived membership\nfeed, leases, native ephemeral/history consumers, credentials, keys, tokens, owner secrets, and actor\nledger files are excluded. `full` means every transferable message and registry stream, not every\nJetStream resource: endpoint submissions/facts/events/timers/workflow state, contract artifacts, and\nthe records/auth/session stores are nonportable control state. Restore recreates those streams empty\nwith their canonical configs before exposing the normal listener, so active endpoint runs,\nlifecycles, and sessions do not cross a backup. Artifacts are exclusively created `0700`;\nsnapshot/checkpoint files and\nthe manifest are `0600`; `manifest.json` is written last with exact sizes and SHA-256 values. The\ndirectory is trusted operator input: hashes detect corruption, not malicious rewriting.\n\nRestore validates and stages the exact allowlisted artifact bytes before moving or creating a store.\nIt requires the same space and existing trust state. The whole pre-commit window holds a journaled\nliveness claim (coordinator, watchdogs, brokers, absolute deadline): ordinary `up` and a repeated\n`up --restore` refuse while the claim is live, and a stale attempt is recovered only after the\ndeadline has elapsed and every recorded owner is proven dead. A retried `up --restore` handles this\nautomatically; an operator can also recover it explicitly with `cotal clean restore-attempt --attempt <id> --force`. Nothing\never rolls back a live attempt. A registry-only artifact restores as registry-only whether or not\n`--restore-only registry` is passed; omitted infrastructure is always created and the exact\npost-restore stream inventory is asserted before commit intent. Ordinary `up` from a preserved cut\nresumes only the exact recorded source store and runtime; a contradicting `--store-dir` or\n`--runtime` fails in preflight.\n\n**Admitting a seat checkpoint.** An ordinary `up` from a preserved cut admits that cut's seat\ncheckpoints before it journals the resume attempt and before any process starts, so a refusal costs\nnothing. Three gates run in order, each naming what it saw.\n\n1. *Integrity.* Every file the record names must be present, a regular non-symlink file, the\n   recorded byte size and the recorded sha256, re-stat'd after the read so a file that moved is a\n   refusal. Failure here consults no other gate.\n2. *Identity.* The recorded space must match, the recorded `lifecycleUid` must not belong to a live\n   incarnation, and the profile revision must match this host's or be resumed under deliberately\n   this host's. A differing revision is refused with both digests and the remedy, and there is no\n   override: the checkpoint carries the recorded digest and not the config bytes, so nothing could\n   run the seat under the recorded revision, and the manager re-digests the same file and refuses\n   drift on its own. This gate has no blanket override, which is the only reason the next one may\n   have one.\n3. *Recency.* `capturedAt` is compared to this host's clock against the horizon the record carries.\n   Inside it, the seat resumes. Outside it, `up` refuses and prints the capture instant, the clock\n   reading and the horizon; `--accept-stale-checkpoint` admits it anyway and the exercised consent\n   is printed with the actual age. An unreadable `capturedAt` is refused with no override, because a\n   freshness gate that fails open is not a gate.\n\nCustody transfers only after all three pass. The destination claims the recorded generation plus one\nby exclusive create, before it launches anything. A lost create means another destination is already\nclaiming that seat, and it refuses with `seat-writer-generation-create-lost` rather than adopting\nthe winner and becoming a second writer. The recorded `lifecycleUid` is reused and never minted, so\nthe resumed seat binds the same lifecycle-keyed durables.\n\nAdmission is reconciled against the inventory the resume is about to hand the manager, and that\nreconciliation finishes before the restore moves a single tree. A checkpoint whose recorded\n`lifecycleUid` is not the one the retained inventory carries describes a different incarnation of\nthat seat, and it refuses with both uids while every live working tree is still untouched and no\ngeneration is claimed. A retained\nseat with no admitted checkpoint refuses the resume by name: an absent checkpoint directory and an\nabsent record are indistinguishable from a seat that was never checkpointed, and a seat that starts\nwithout passing the gates has claimed no generation. `--accept-stale-checkpoint` is recorded in the\nresume journal with the seat, the capture instant, the admitted age and the horizon, so the consent\nsurvives the terminal it was typed into.\n\nThe whole admission is all or nothing. Coverage is settled first, then every gate runs over every\ncheckpoint, and only then is any generation claimed. A refusal at any point leaves every generation\nunclaimed, including a lost exclusive create during the claim itself: the claims that attempt made\nare removed before the refusal is raised, by the exact paths it wrote, so a generation another\ndestination holds is never touched. A claim is a create that can never be made again, so a refusal\nthat left one behind would consume the retry over the same checkpoint set.\n\n**Restoring a seat checkpoint.** Once every gate has passed over every checkpoint, and before a\nsingle generation is claimed, `up` puts each admitted seat's captured bytes back. A refusal here\ncosts nothing for the same reason a gate failure does: no claim has been made and nothing has\nstarted.\n\nA restore never moves or replaces the destination's own control directory. A checkpoint excludes\n`.cotal/` by design, so a seat whose `cwd` holds one, which is the layout an operator gets by\nrunning `up` and `spawn` in a single directory, is refused before anything is staged: promoting a\ntree that cannot contain `.cotal/` over that `cwd` would carry this host's live trust material and\nmaintenance state away with the superseded tree. The refusal names the control directory it found\nand the remedy, which is to give the seat a working tree that is not a workspace root.\n\nEach seat is staged beside its own `cwd`, in `<cwd>.incoming`:\n\n1. every recorded digest is verified again over the files as they are now;\n2. the bundle is cloned into `<cwd>.incoming`, which is refused when that path already exists;\n3. the recorded base commit is verified in the clone and checked out detached, so a bundle that does\n   not contain it stops the resume instead of continuing against a different history;\n4. the index diff is applied with `--index` and the worktree diff without it, both `--binary\n   --allow-empty`. That order is what puts staged content back in the index rather than only in the\n   worktree, and `--allow-empty` is why a seat with a clean tree is still restorable;\n5. the untracked archive is extracted.\n\nEvery seat stages before any seat is promoted. Promotion moves an existing `cwd` aside to\n`<cwd>.superseded.<timestamp>` and renames the staging directory into place, then puts the session\npointer and store files where the destination's connector reads them, then re-reads\n`git status --porcelain` in the promoted tree and compares it to the status the checkpoint recorded.\nA restore that applied without error and produced a different index is a refusal, not a warning. The\ntwo renames are the only steps that touch the path the seat will use, so a failure anywhere leaves\nevery seat's live `cwd` as it was.\n\nThe rename itself claims the superseded name, and a taken name gets a numeric suffix. The timestamp\nhas one-second resolution, so two promotions of the same seat within one second compute the same\npath; a rename onto a name that already holds a tree fails on every platform, and that failure is\nread as taken. Nothing creates the name ahead of the move, because Windows refuses to rename onto an\nexisting directory at all. A superseded tree is the thing that rename exists to keep.\n\n`git` and `tar` run as child processes with argument arrays, never a shell string.\n\nA leftover `<cwd>.incoming` refuses the resume by name. A staging directory from a failed run is the\nonly record of what failed, so nothing removes one automatically: inspect it, remove it by hand, and\nresume. A pre-existing `cwd` is renamed rather than deleted, so a wrong checkpoint costs a rename\ninstead of a tree. When a promotion fails, the renames that attempt made are undone and the staging\ntree is left where it is, as the evidence for what did not verify.\n\nA session pointer whose recorded `sessionId` is not the one the retained inventory reopens is\nrefused before anything is cloned. A session file already present at its destination is judged by\ncontent: bytes equal to the recorded digest are already restored, and different bytes under the path\nthe connector is about to read are refused with both digests rather than clobbered.\n\n`up --restore <dir>` reaches the same admission and the same restore, after the store is restored\nand validated and before commit intent is journaled. A registry-only restore resumes no seat, so it\nadmits and restores nothing.\n\nOne limit is worth stating plainly. The writer generation is claimed by exclusive create inside one\nworkspace root, so it fences two resumes on the same host and does not fence two independent\ndestinations: copy a checkpoint to two roots and both claim the same successor. A real cross-host\nfence needs a coordinate neither root owns.\n\nAuthenticated restores validate the complete\nspace trust bundle before staging, including nkeys, seed matches, JWTs, signers, and space binding;\nfull restores commit to the validated operator, system-account, data-account, and active-signer root\nchain in addition to the static/user authority fingerprint. Because the system account is part of that\ncommitment, a [`cotal up --rotate-sys`](#up) makes every full artifact taken before it unrestorable\nagainst this root: take a fresh full backup after each rotation. The composed commitment is revalidated\nimmediately before store mutation and never includes secret seeds. Restore never creates fresh auth.\nSame-path restores atomically retain the old\nsource at the journaled fallback path; alternate targets retain it in place; a missing canonical\nsource needs explicit `--accept-missing-source`. Quarantine and target restores use current canonical\nconfigs on isolated random-loopback brokers, never expose native snapshot consumers, and publish a\ncommit-intent immediately before the normal listener starts. Archive bytes never instantiate the real\ntarget: after quarantine validation, every stream is re-snapshotted from the validated quarantine\nstate into attempt-owned sanitized files, and the target is restored solely from those. Before that boundary, failure rolls back\nthe attempt-owned target; after it, ambiguity preserves both stores and records forward-repair\nrecourse. The cooperative maintenance lock excludes Cotal commands, not arbitrary raw NATS processes.\n\nBootstrap brokers in every auth mode, including open, mount the store under a local account with\nrandom operation-specific logins only, each carrying the exact per-phase subject permission matrix;\nnormal static credentials and user-auth sentinel/bearer connections are rejected, and no auth\nservice or callout starts. Open mode differs only in its account label, never in authority. Inventory, each stream snapshot,\nrestore initiation, exact upload id, validation, and each checkpoint recreation use separate exact\nauthorities. Every checkpoint carries the source stream's message/first/last sequence state and must\nmatch its snapshot record before mutation; core then derives and validates the only allowed start\npolicy. TASK is not a CLI exception: the same core checkpoint API recreates its canonical `DeliverAll`\nWorkQueue durable because acknowledged tasks are absent from retention and NATS forbids a\nstart-sequence policy there. Registry-only restore creates every omitted canonical stream and transient\nbucket on the isolated target before the normal listener is exposed. It deliberately does not resume\nretained agents or recreate their DM/DLV/TASK/ACL state; their identity material stays retained and\nstopped rather than being reprovisioned into a partial restore.\n\nAfter listener readiness, the manager starts attempt-bound, validates retained credentials/tokens\nwithout granting or reprovisioning, and resumes the exact persisted principals under cleanup\nsuppression. Registry-only restore uses the same flow with an empty agent set. On a user-auth mesh\nthese manager calls run as the logged-in operator's `cli` actor, the caller the preserve cut used, so\nthat actor needs a current `admin` grant. `commitResume` is an\nidempotent validation barrier only: success must be `awaitingFinalize` with an attempt-bound 64-hex\ncommit token and does not release suppression. Under the workspace lock, the CLI first fsyncs that\nexact evidence as `manager-committed` (restore) or `resume-committed` (ordinary resume), then calls\ntoken-bound `finalizeResume`; only an `active` response for the exact token releases suppression. The\nCLI records the same token in finalization evidence before a restore becomes `active`, or before an\nordinary resume retires and consumes the marker. Re-entry from either committed state skips the prior\nidempotent activation/commit phases, retries finalization with the durable token, and finishes the\nworkspace transition. Failure before finalization preserves the committed state and cleanup\nsuppression; it is not rewritten through a degraded transition. Re-entry between any two earlier\nboundaries reuses the same attempt and may retry the idempotent phases without deleting retained state. A missing or\nchanged per-agent dependency is a named fail-closed result; the journal becomes degraded and remains\navailable for forward repair. A retry from `resume-intent`,\n`resume-active`, or `resume-degraded` reuses the same attempt and inventory after the prior listener is\nproven stopped. A retained agent the lost manager already launched can still be running, for example\nin a tmux window, while the journal reads `resume-intent`. On a static mesh the replacement manager\ncloses that seat through the reference the lost manager recorded on the agent's slot, waits for the\nprincipal to leave presence, and launches it again. A live principal with no such record, or one that\nstays live after the seat is closed, is refused. Every normal restore listener has an unguessable\nattempt-bound NATS server name. The CLI fsyncs its exact name/nonce, canonical endpoint, process owner, and generation-bound target identity\nimmediately after spawn. Re-entry accepts a surviving listener only when its INFO server name, live PID\nrecord, endpoint, and target identity all match that proof; degraded restore repair then moves through\nthe guarded workspace transition only after manager commit. If an uncommitted bound owner is provably\ndead, recovery retires that exact proof under the maintenance lock and binds a fresh listener for the\nsame attempt, endpoint, and target with a new nonce and server name. A live foreign/mismatched listener\nor ambiguous owner is preserved and refused, never adopted by reachability alone. A reconstructed\ncommit/degraded attempt without either the exact bound proof or a durable dead-listener replacement\nrecord fails closed even when the recorded port is free. A later ordinary startup may pass an `active`\nrestore only when its details prove manager commit and its exact recorded listener is dead.\n\n## Mesh registry\n\n```bash\ncotal meshes [--json]\ncotal meshes add                      # guided, on a terminal\ncotal meshes add <space> --server <url> [--root <dir>] [--mode auth|open|user] [--tls] [--force]\ncotal meshes add <space> --mode user (--user-auth-file <bundle.json> | --from <https url>)\ncotal meshes rm <space> [<space> \u2026] [--force]\ncotal sync [--idp <auth base URL>]\ncotal use <space>\ncotal status [--space <s>] [--server <url>] [--components]\n```\n\n`meshes` lists the meshes this machine knows; a `*` marks the `current` default a bare\n`cotal spawn` joins. Entries learned from a signed-in account are marked `discovered`. Their\nregistration trust is stored under the account's private auth state, and the registry contains no\nsession token or sentinel credential bytes. Commands resolve the catalog `slug`; a different human\n`name` is rendered only as a label.\n\n`meshes --json` prints one JSON object per recorded mesh per line: `space`, `server`, `mode`,\n`root`, `default` (the `*`), and `origin` (`up`, `manual`, or `catalog` for a discovered entry). A\nlocal or hand-registered entry also carries `offline`. A discovered entry is never probed, so it has\nno `offline` field. `tlsRequired`, `events: \"required\"` and a discovered entry's `catalogName` appear\nonly when the record has them. An empty registry prints nothing and exits 0. The note about a default\nthat matches no record goes to stderr, so stdout carries only rows, on a first run too. The table is\npresentation and is not a stable parsing target. `meshes add` and `meshes rm` refuse `--json`.\n\nA registry record this build cannot use is refused by name, never rendered and never skipped. One\nthat does not parse, or is missing a field every consumer reads (`server`, `mode`, `root`, `ts`,\n`space`), makes every registry command exit 1 with the file's path and what is wrong with it.\nRemove the file or restore the record; nothing repairs or invents a field for you.\n\nAn IdP may advertise a same-origin space catalog during login. Cotal reads the complete snapshot and\nadds every valid registration without a separate `meshes add`. A snapshot younger than five seconds\nis used without a request. After that, commands that resolve a mesh target conditionally refresh the\nsaved catalogs. An operation targeting a discovered space refreshes only that space's account and\nrefuses if that account fails. Operations targeting local or manually registered meshes refresh every\naccount, print one warning for each failure, and continue. `cotal status` refreshes every account,\nnever refuses on a refresh failure, and lists each account as `fresh`, `updated`, `not-modified`,\n`no-catalog`, or `failed` with its error. `cotal sync` bypasses freshness and reports added, changed,\nremoved, unchanged, and name collisions. `--idp` limits it to one signed-in account. It never connects\nto a broker.\n\nThe registry is updated under the same lock that guards the catalog cache, so a command never lists\na discovered space set that another command is still writing. The cache records a fetched snapshot\nas not yet applied before the first registry write and as applied after the last. If a command dies\nor is stopped in between, the next command applies that snapshot again before it can use it, with\nno request inside the freshness window.\n\nThe shared dispatcher applies this preparation to every command that declares both `--space` and\n`--server` as mesh-target flags, including commands registered by other packages and commands that\ndeclare their own equivalent flag objects. Daemon and startup commands that use those names only as\nconfiguration explicitly opt out. Registry-local `meshes add` and `meshes rm` never refresh a catalog.\nWhile the registry holds a record this build cannot use, the preparation neither refreshes nor\napplies a catalog, so the command's own checks run first. A snapshot left unapplied is applied by the\nnext preparation after the record is restored or removed. A command that resolves its target through\nthe registry still refuses the record by name.\n\nRun on a terminal with the space or `--server` missing, **`meshes add` is guided**: it asks for the\none thing that cannot be derived (the broker URL), probes it, and tells you what answered - open or\nrequiring credentials. It then offers the spaces your `--root` already holds credentials for, states\nthe mode as a fact about that broker rather than asking, and shows the exact record before writing\nanything. A broker that does not answer, or a space name already registered, becomes a choice rather\nthan an error. Anything you pass on the command line is taken as given and not asked again. Without\na terminal - a script, an agent, CI - nothing prompts and the flag form's errors stand\n(`COTAL_NO_PROMPT=1` forces that too).\n\n`cotal up` and `cotal down` maintain their own records. `meshes add` registers a mesh they cannot\nspeak for: one running on another machine, a shared broker, a hosted space. `--root` is the folder\nwhose `.cotal/auth` holds that mesh's credentials and whose `.cotal/agents` holds its personas.\nThe default is the project you run it in. The registry stores that path, never a secret. `--mode`\ndefaults to `auth` when the root holds the space's account record and to `open` otherwise. The\nbroker is probed before anything is recorded, so a wrong address, or credentials that mesh will\nnot accept, fails here instead of at the first `spawn`; `--force` records without verifying (and\nreplaces an existing record).\n\nA hostname or public address is registrable only when the connection will **require TLS**. Pass\n`--tls`, or use a `tls://` URL. The scheme is recorded as enforced intent, so every later dial\nthrough the record demands the handshake (and `meshes add tls://\u2026` against a plaintext broker is\nrefused at registration). Without required TLS the fence admits loopback and private-overlay\nliterals only. RFC1918 addresses are refused in both modes because a cafe LAN is private but does not belong to you.\n\nA **user-auth** mesh registers from supplied pinned trust, never guessed: `--user-auth-file`\ntakes the bundle exported where the mesh runs; `--from` asks before it dials the address at all,\nthen fetches its `/.well-known/cotal-mesh` discovery document (HTTPS only), displays the pins, and\nasks again before adopting them. Neither fetch follows redirects: a 302 can move a pinned fetch\nonto plaintext or onto another host, so it is refused rather than followed, and the pinned\nexchange must itself be an `https://` URL, except for an exchange on this machine, where plain\n`http://` is accepted for a loopback *literal* (`127.0.0.1`, `::1`, any spelling of them) but not\nfor `localhost`, which is a name rather than an address. Registration verifies that the exchange\nanswers `/health` and `/jwks` as the pinned issuer. It also verifies that the broker refuses a bare\nconnect; that auth-required refusal is the pass. The sentinel credentials land in a 0600 file under\nthe entry's root; the registry records only the path.\n\n`meshes rm` drops records. It never stops a mesh. For a mesh running on this machine `cotal down`\nis the right verb, and `rm` says so unless you pass `--force`. A hand-added record is removed by\n`meshes rm`, by an `add --force` replacement, or by a `cotal up` that actually starts the broker for that same space, server and root, which becomes that\nmesh and so takes the record over (a `cotal up` for that space anywhere else refuses instead).\nNothing that merely *infers* a record is stale from a dead broker touches it: an\nunreachable broker is listed `offline` and stays, whether `cotal up` or `cotal meshes add`\nwrote the record; a foreground `up` whose broker exits unexpectedly keeps its record the same way.\nA bare command does not treat that offline record as a running mesh;\nname it with `--space` to restart it. `cotal down` / `cotal clean all` still drop an `up` record for the project\nthey tear down; a hand-added one they leave alone even when it shares a root, because nothing\non this machine could write it back.\n\nA discovered entry belongs to the normalized IdP origin and proved subject that supplied it. Local\nteardown, cleanup, and liveness pruning do not remove it. A manual or locally started entry with the\nsame name wins and remains untouched; that discovered name is reported as a collision. Logging out\nremoves only the discovered entries owned by that account.\n\n`cotal meshes` and `cotal status` print `events: required` for a registration carrying\n`policy: { events: \"required\" }`. On that space, foreground spawn, detached spawn, manager starts,\nand interactive `join` cannot opt out or join without an event plane. `--no-events` is refused with\nthe space named. A connector without an event plane is refused with both the space and connector\nnamed. A session whose own grant omits `events.<owner>.<actor>` is refused before joining and the\nmessage names a full-row `actor grant` repair.\n\n`use <space>` sets that default; the selection applies from every directory,\nincluding inside another mesh's project. `status` is a read-only report: machine prerequisites\n(starting with the installed `cotal-ai` version), the installed extensions and their versions, this\nfolder's `.cotal/`, the recorded meshes, and a live snapshot of the selected mesh (roster, channels,\nmembership feed). Stale Claude skills and out-of-date `.agents` skills recommend `cotal setup --skills`,\nnot unscoped `cotal setup`. `status` takes `--space` / `--server` to pick the mesh to inspect; it starts\nnothing. The manager row asks the service endpoint once: a live process that does not answer is\n`not serving`, and a probe that could not be made leaves the row `running \xB7 service unchecked`.\nA process row whose PID record exists but cannot be read reads `pidfile unreadable` with the error,\nand the other rows still print.\n\nIf a refresh fails, `status` may still show the kept catalog bytes for diagnosis. It labels them\nstale with the last successful snapshot timestamp and the refresh error. It never calls that state\nsynchronized or online. If a selected discovered space vanishes from a successful snapshot, the\nselection is cleared and the command reports that no default is selected.\n\nFor a user-auth mesh the selected-mesh section reports the login `status` works as: the signed-in\nsubject when this machine holds a cached session for the entry's pinned IdP, or the exact `cotal\nlogin --idp <url>` line when it does not, with no network round trip either way. A locally\nprovisioned space also shows the actor grant row; a discovered or registered remote entry reports\nthe grant as not checkable on this machine, because the ledger runs where the space was\nprovisioned. `--components` on a user-mode target probes as that same signed-in login (`ps`'s\ncredential), never a static mint; when the login cannot supply a credential, the row says why\ninstead of printing the broker's refusal of an unauthenticated probe.\n\nPersona rows name the catalog they describe. If this folder and the selected mesh use different\ncatalogs, status names both and marks which one spawn launches from. A green `default` means the file\npasses the same agent-file loader spawn uses; a present but invalid file is reported as invalid.\n\n`cotal status --components` adds a fail-loud per-component health pass. It reads **each\ncomponent's own control surface**, rather than treating a PID, a lease, or a successful probe of a\nsibling as proof that the component serves. It prints one of `serving`, `absent`, `not-serving`, or\n`refused` for each component and exits `0`, `1`, `2`, or `3` respectively (the highest observed\nstate wins):\n\n- **manager**: local PID record, its liveness-lease holder and PID, then the manager's own typed\n  `status` service reachability from this host. Manager builds that do not report static\n  reconciliation say `static reconciliation not reported by this manager build`; the line stays\n  visible even when the manager is otherwise `serving`.\n- **delivery**: local PID record, its ready lease (`ready` is the daemon's own bound-control\n  signal), and the latest `renewal.<spaceKey>.json` adoption verdict, the record of the space the\n  command was asked about, keyed per space the way the pidfiles are. A re-signed credential and a\n  broker-accepted adoption stay distinct facts. A root-only `renewal.json` left by an older build\n  names no space and is never read as any space's verdict (`doctor auth` names it as a leftover).\n- **web**: local PID record, then the `/api/meta` response at the address the dashboard recorded in\n  `web.session` once it was listening, which must name the same PID. A live PID with no readable\n  recorded address (the dashboard is still writing it, or an earlier build started it), or an\n  unrecognizable process record, is `refused`, not a green default-port guess.\n- **broker**: the registered mesh URL dialed from this host with its recorded TLS requirement.\n\n`absent` means Cotal has no live local component record (or has a stale record); `not-serving`\nmeans the component record is live but its service/readiness surface did not answer or is not ready.\nThose are intentionally separate exit cases. A failed or unreadable probe is `refused`, never an\nabsent component or a clean zero. A PID record that exists but cannot be read refuses only its own\nrow. A record that its component removes while the pass runs reads as `absent`.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\nFor a foreground spawn onto a remote user-auth mesh, a launcher may supply a one-time enrollment\ninstead of a cached human login. Prefer a private file:\n\n```bash\nCOTAL_ENROLLMENT_FILE=/run/secrets/cotal-enrollment \\\n  cotal spawn --config ./seat.md --space main\n```\n\nThe file contains only the enrollment URL, ending with at most one line terminator, and must be\nmode `0600` on POSIX. An orchestrator that cannot mount a file may set `COTAL_ENROLLMENT_URL`\ninstead; that value is redeemed byte for byte, so a trailing newline in it is refused. Setting both\nis refused. Enrollment input\nrequires `--space` and applies only to a foreground persona spawn. If the mesh is not registered yet,\nthe enrollment response must carry the stock user-bundle fields and the command needs\n`--config <persona-file>` because there is no local remote-mesh persona catalog to read. The client\nredeems the URL once, registers the returned mesh material, exchanges the returned actor token at the\npinned auth service, and removes both enrollment variables before starting any child process.\n\nA cached login for the same IdP and an enrollment are conflicting proofs, so the command refuses\nrather than choosing one. An invalid enrollment never falls back to login provisioning. Unknown,\nexpired, revoked, and already-used enrollments all produce one response: ask the owner for a fresh\none. See [Enrollment redeem](identity-and-auth.md#enrollment-redeem) for the HTTP contract.\n\nA runtime that starts a managed seat outside the manager's filesystem hands the child a managed\nhandoff instead: one `0600` file named by `COTAL_MANAGED_HANDOFF_FILE`, carrying the lifecycle the\nmanager already enrolled. The runtime builds the command with `delegatedSeatCommand`:\n\n```bash\nCOTAL_MANAGED_HANDOFF_FILE=/run/seat/handoff.json \\\n  cotal spawn --config ./seat.md --space main --name <actor> --agent claude \\\n    --expect-owner <owner> --expect-lifecycle-uid <uid>\n```\n\nThe `cotal` entry reads the file, deletes it and drops the variable before it parses flags, prints\nhelp or loads extensions, so every outcome leaves no file. The variable is read under any letter\ncase; spellings that name different files are refused after every one of them was deleted. The\nspawn then refuses a malformed handoff, or one whose space, owner, actor or lifecycle UID differs\nfrom `--space`, `--expect-owner`, `--name` and `--expect-lifecycle-uid`, before any broker\nconnection or exchange request. Every refusal on this path names the field and never a value from\nthe handoff. The registration's server, exchange and enforcement checks, the local state this\nmachine keeps for the space (its mesh record, user-auth state and agent secret files), target\nresolution, the policy refresh, the broker preflight and the agent auth preflight quote the space,\nthe server, the exchange URL, the actor or a path named for one of them in their own diagnostics and\nin the filesystem errors under them. For a handoff each prints one fixed sentence that names the\nfield and the phase instead, whether its check fails or an error is thrown. The event-plane policy\nrefusals name the handoff's space field. An actor outside `[A-Za-z0-9_]` and a space that cannot\nname local state, such as `..`, are refused as malformed before any plane. A handoff conflicts with\nthe enrollment variables, `--detach`, `-f` and `--creds`, and needs `--config <persona-file>`. From\nthere it runs the enrollment consumer above without redeeming anything. See\n[Delegated seats](embedding.md#delegated-seats-outside-the-managers-filesystem).\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | none | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | none | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | persona's `agent:`, else `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `jcode`, `hermes`, and so on) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at. Refused before launch when the directory does not exist on the serving manager's host. |\n| `--prompt <text>` | none | Initial prompt auto-submitted at start |\n| `--resume <id>` | none | Fork an existing session id into the mesh; only connectors that declare resume support accept it (see [the matrix](connectors.md)). The manager records the source session id, and `ps --wide` shows it |\n| `--no-events` | event plane on where supported | Opt out of the session's structured event plane (`--events` only restates the default) |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--on <instance>` | class anycast | With `--detach` only: pin the launch to one manager instance id (the whole id, as `ps` prints it). Refused on a foreground spawn (no manager to pin), with `-f` (a manifest deploy launches through the manager class queue), and when empty |\n| `--file <cotal.yaml>`, `-f` | none | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | none | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime |\n| `--expect-owner <u_\u2026>` | none | With `COTAL_MANAGED_HANDOFF_FILE` only, and required there: the owner the handoff must carry |\n| `--expect-lifecycle-uid <uid>` | none | With `COTAL_MANAGED_HANDOFF_FILE` only, and required there: the lifecycle UID the handoff must carry |\n\nEach session uses its connector's **event plane** by default: a stream of structured events\ndescribing what the agent did, rather than the prose it wrote, on a channel of its own. The channel is named after\nthe agent's principal, `events.<owner>.<actor>`, never after its display name, because two live\nagents are allowed to share a display name and would then share a stream. The launch grants publish\nrights on that channel alone, foreground and detached alike. On an open mesh, which issues no\ncredentials, the launch still allocates the agent an id, so the channel names a stable actor.\n`--no-events` is the explicit opt-out unless the selected registration says\n`policy: { events: \"required\" }`. Required policy makes the\nevent arm and grant mandatory, so `--no-events` and connectors without an event plane are refused.\n\nThe launch decision and the grant are separate on purpose. Holding publish rights on a channel is\nnot a request to publish to it, so writing an event channel into an agent file's `allowPublish`\ndoes not override `--no-events`.\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. On a user-auth mesh the\neffective name is also the agent's actor token, so it must match the token grammar (no `-`); the\nspawn is refused with that explanation before any request is sent. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. Both modes get the\ndurable backstop on a mesh that runs the delivery daemon; `--live-only` skips it for a foreground\nspawn (messages posted while it is disconnected are then not replayed). A foreground exit retires\nthe agent's creds and broker footprint, like a manager despawn. On a user-auth mesh the two arms\ndiffer: a spawn against a mesh this machine provisioned revokes the actor row on exit, while a\nremote spawn (an enrollment or the advertised provisioning endpoint) removes only this machine's\ncredential files; its grant stays until the mesh operator revokes it, and the launch line says\nwhich arm you are on. A `--detach` spawn is an\n**action**: the manager accepts it and returns the allocated identity at once, then the launch\nfollows to a terminal outcome rather than blocking (see [the control surface](control-surface.md)).\nSee [Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\nA `--detach` spawn onto a manager from another Cotal release is refused before any request is sent\nwhen the manager's contract does not declare a field this CLI sends. The refusal names the field,\ncalls it version skew, and gives this CLI's version. A field you leave unset is not sent, so it\nnever causes that refusal.\n\nA manager has 50 seat slots, and each seat counts once. A slot is held by a managed seat (a row in\nthat manager's `cotal ps`, including a seat still joining), by a reserved launch the manager accepted\nbut has not started a process for, or by a cooling hold. A seat that ends within 10 seconds of\nstarting leaves its slot cooling until those 10 seconds pass, unless an operator stopped it. Such a\nseat holds only that cooling slot, even while its launch is still reporting the failure. A spawn\nrefused at the limit states that split and whether waiting can free a slot:\n\n```text\nat capacity (50 of 50 slots: 49 managed, 0 reserved, 1 cooling); waiting frees a cooling slot in 7s, or despawn one\n```\n\nA cooling slot frees at the stated time. A launch that has not settled frees its slot only if it\nfails, and a managed seat frees its slot only when it stops. The refusal counts a launch as pending\nonly while it holds a slot, so a launch whose seat already ended is not counted. The roster counts\npresence, which also includes peers no manager owns, so its total is a different number.\n\nRun from a managed seat's own shell on a static or open mesh, `cotal spawn --detach` launches as\nthat seat when it targets the seat's own space. Without `--space` it picks that target the way the\noperator path does, so a recorded mesh that is not running is skipped. The CLI reads the seat's\nlaunch identity (`COTAL_NAME`, `COTAL_ID`, `COTAL_LIFECYCLE_UID`, `COTAL_SPACE`, and on a static\nmesh the seat's own credential), so the manager records the seat as the spawner, the same as for\nthe seat's `cotal_spawn` tool. On a static mesh that credential also proves the seat's space, so a\nlaunch without `COTAL_SPACE` still runs as the seat, and a target space holding no credential for\nthe seat is refused. An open mesh acts as the seat only when `COTAL_SPACE` names its space. The\nseat can then stop the child with `cotal_despawn`, and the manager stops the child when the seat\nexits. On a static mesh a seat whose agent file lacks `capabilities: [spawn]` is refused, because\nits credential holds no spawn subject.\n`--on <instance>` keeps its pin: the seat's own credential has no instance route, so on a static\nmesh the CLI mints a one-shot `manager-caller` view for the seat, pinned to that instance and\ncarrying the spawn subject only when the seat's credential holds it. On an open mesh the call keeps\nthe TLS requirement the mesh records. `--creds`, `--server` with an unregistered `--space`, and a\nuser-auth mesh keep the operator path.\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one. OpenCode and Codex query harness/provider surfaces; Jcode reads\nproviders that enable `model_catalog = true` in the operator Jcode `config.toml`. Jcode's listed\neffort tiers render as `variants (declared, not provider-verified)`, and launch can still refuse one.\nA connector without a catalog says so. Pick a result with `cotal spawn --model <id> --variant <v>`,\nwhere `<id>` is the model id as the catalog printed it. OpenCode and Codex ids are the full\n`provider/model`; Jcode ids are bare (`opus-5`, not `cliproxy/opus-5`), because the provider is\nselected by the operator's Jcode config and a prefixed id is refused at launch with the bare form\nnamed.\n\n## endpoints\n\n```bash\ncotal endpoints [--space <s>] [--server <url>] [--creds <path>]\n```\n\nLists the mesh presence roster: agents, the manager, and any other protocol endpoint, with each\nendpoint's role, kind, status, and current activity. Unlike `ps`, this is a read-only presence view;\nit is not limited to child processes owned by the manager.\n\n## Endpoint control\n\n```bash\ncotal describe <endpoint> [--on <instance>]                        [--space <s>]\ncotal invoke <endpoint> <command> [--args '<json>']              [--space <s>]\ncotal invoke <endpoint> <command> --name <agent> [--admin]       [--space <s>]\n```\n\nThe generic v0.4 service surface. `describe` resolves a registered endpoint's command set off the\nwire - the reserved `describe` command answers the registered contract digests, the schemas are\nfetched from the space's content-addressed contract store, recompiled, and verified against those\ndigests - and prints each command with its capability class and targeting shape. `--on <instance>`\npins `describe` to one manager instance's rail (the whole id, as `ps` prints it under its\n`manager <id>` headers), so an operator can read what that instance serves in a multi-manager space;\nunpinned, the class queue answers and the attribution line names whichever instance did. `invoke`\ncalls one command by name: `--args` is a JSON object validated against the fetched input schema\n*before*\npublish; a targeted command takes `--name <agent>` (resolved to the agent's current principal through\n`inspect`) or `--self`. `--admin` uses the admin instrument credential, whose cross-agent reach rides\nthe operator-only `any` authorization mode. Neither command has compile-time knowledge of any\nendpoint's schemas - this is the same trust chain every built-in control command now uses. Needs an\nauth mesh: the manager registers its service on both static and per-user meshes (a signed-in user\nrides their bearer; each visible or invoked command still requires its existing grant, and cross-agent\nreach needs the `admin` scope). An open mesh has no service registry.\n\n## Managed seats\n\n```bash\ncotal ps [--on <instance>] [--wide | --json] [--slots] [--space <s>]\ncotal stop --name <n> [--on <instance>] [--space <s>]\ncotal attach --name <n> [--on <instance>] [--no-reconnect] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | none | Managed agent to stop / attach (required) |\n| `--on <instance>` | class anycast (`ps`: class scatter) | Pin to one manager instance id (multi-manager space); takes the whole id as `ps` prints it, not a prefix. An empty value (`--on \"\"`, an unset shell variable) is refused, never treated as absent. A roster principal id (`local.\u2026`) is refused with a message naming the instance id `ps` prints |\n| `--wide` (`ps`) | off | After each seat's compact row, print extra operational facts the manager records: the provider the connector reported serving the model, `cwd`, `pid`, spawner, lifecycle uid, the owning manager's instance id and host, and for a `--resume` seat the session it forked (`forked from <id>`, with the source title and transcript SHA-256 once a Hermes or Jcode seat has recorded its fork). Model and requested variant stay in the identity row rather than printing twice. A fact the manager did not record (for example a runtime with no real process, or a connector that reported no provider) prints nothing, never a placeholder |\n| `--json` (`ps`) | off | Machine-readable: one JSON object per seat per line, copied unchanged from the manager row. Instance headers and errors go to stderr, so stdout contains only rows. Mutually exclusive with `--wide` |\n| `--slots` (`ps`) | off | List the durable static slot rows this manager owns instead of live seats, through the `slots` command. Mutually exclusive with `--wide`. A row that is not in the live roster still prints, with `live=false`; a retired row never prints |\n| `--no-reconnect` (`attach`) | off | End the attach when its session ends, instead of re-establishing it. For scripts that want one run and one exit code |\n\nA raw `--creds` file is refused by `ps`, `stop`, `attach` and the other control commands, because\nthat route mints no endpoint-caller triple; the project folder, or `--space` against the registry\nentry, is the route that does.\n\nThe human `ps` row is presentation text and is not a stable parsing target. Scripts use `--json`,\nwhich is the machine-readable row contract.\n\n`--slots --wide` is refused: `--slots` lists durable static slot rows, `--wide` prints live seat facts, and the two answer different questions. Across a multi-manager scatter, `--slots` prints each manager's rows under its own instance header, the same way the plain `ps` scatter does.\n\nThese are operator clients over the running manager's control plane. The default row includes the\nconnector, model pin, optional requested variant, and runtime as operational descriptors for the\nmanaged row. They do not make a shared display name a unique protocol identity; use `--json` when\nunambiguous owner+actor attribution is required. An omitted variant means no override was requested;\nCotal does not invent an effective provider default it cannot observe. `ps` also prints two state\nfacts per managed agent, because they answer different questions: the process fact from the manager's\nown runtime handle (`running` with its uptime, or `exited` with how long it ran), and the mesh fact\nfrom the roster (`idle` / `working` / `waiting` / `mesh offline`, or `not in roster` when the seat has\nno presence row at all: a seat that has not joined yet, or one that never did). When the seat's\nconnector relays a harness-reported condition, the mesh fact carries its code and how long it has\nheld, so a seat whose turn died on a provider rate limit reads `waiting (rate_limit for 40m)` rather\nthan a bare `waiting`, and `--json` carries the whole `condition` object. When the connector reports\nthe seat's last work event (presence `activeAt`), the mesh fact ends with its age, such as\n`\xB7 active 3s ago`, and `--json` carries `activeAt`. A seat whose turn stopped advancing keeps\nheartbeating, so its presence row stays fresh and this age is what shows the stall. A seat can be\n`running` and `mesh offline` at once: the process is alive and its presence has lapsed. That row says\nhow long, as in `mesh offline for <age>` with an age such as `3.5h`, counted from the seat's last\npresence heartbeat, which `--json` carries as `offlineSince` (epoch ms). The age is read only from\nthe seat's own presence record, matched on its principal and lifecycle uid, so a same-named peer or\nan older lifecycle never dates it. The manager log names each managed seat that is offline on the\nmesh while its slot is held\n(`seat offline on the mesh: <name> - last heartbeat <time>; process <state>`), including one its\nwatch first sees offline after a reconnect, and each one that comes back\n(`seat back on the mesh: <name>`), so a watchdog that only checks process liveness has a line to\nact on. The manager does not reap or re-key such a seat. The mesh fact is only a verdict while the\nmanager's own presence watch is fresh: when that watch has been silent past the liveness window, or\nhas not replayed the bucket yet, every row prints `mesh unknown` with the reason instead (`--json`\ncarries it as `meshView: stale | unpopulated`), because `offline` and `not in roster` would then\ndescribe the manager's watch rather than the seat. The manager rebinds a watch that goes\nsilent under a live connection on its own, so `mesh unknown` normally clears within a liveness window.\nOn a user-auth mesh `ps` also renders each managed agent's last credential-refresh outcome, fail-closed.\n\n**Mode split (chosen up front, never try-scatter-then-degrade):**\n\n- **Static / open mesh.** Bare `ps` is a **class scatter**: it freezes the live manager class from\n  the records registry, merges every registered instance's agents grouped and attributed per\n  instance, and a non-answering instance is shown as `registered, no answer within the deadline`\n  (never silently omitted). A refused list or a missing answer makes the census incomplete: rows\n  from other instances remain visible, but `ps` prints an incomplete-census warning on stderr and\n  exits non-zero, including with `--json`. Those rows are not a complete seat count. A contract\n  mismatch prints one plain comparison of the requested and served input/output digest pairs and\n  advises aligning manager versions. The no-answer label means only that the instance is registered\n  and did not answer. It does not say the host is down, because a dead host never deregisters itself and a\n  live one can be slow; if it is gone, deregister it.\n  `--on <instance>` pins the read to one exact instance id instead. A wrong pin fails loud\n  rather than falling through: a well-formed id that no live manager carries is reported as\n  `manager instance <id> did not answer` (nothing else is asked), and a credential without that\n  instance's rail is reported as refused by the broker, not as an unresponsive manager. A manager\n  that answers with a refusal is shown with its own cause; \"no manager reachable\" is said only when\n  nothing answered at all. If the scatter's own registry read fails (the freeze or the reconcile),\n  `ps` says the manager registry could not be read rather than pronouncing on the managers, which\n  may all be up.\n\n**The verdict is scoped to the endpoint rail the request rode.** An issued caller rides the\nversioned `ep.v1` rail, a separate subject space from the legacy `ep` rail, and an endpoint serves\nboth (SPEC 13.15). A manager older than the versioned rail serves `ep` alone, so it can be running,\nregistered and answering while an issued caller's request reaches nobody. Silence on `ep.v1` is\nreported as `no manager answered on the <rail> rail` with `ep.v1` as the rail, and names both causes\nit is consistent with: no manager running, or one older than the rail. The CLI cannot tell them\napart, because the service registry records no package version, so check whether a manager is\nrunning and, if it is, its version. The same scoping applies to `cotal run`'s hosted verbs, which\ndrop the `--local` suggestion there, since `--local` drives the run from the calling process and\nnames the caller as its answerer.\n\n**`stop` and `attach` route by seat locality.** A seat can only be stopped or attached by the\nmanager actually running it, and the class queue does not know which one that is. So on a\nstatic/open mesh both verbs first ask every registered instance which one hosts the named seat, then\naddress that instance directly. This happens by default; you do not need `--on`.\n\n`--on <instance>` remains the override, for when you already know where the seat lives or the\nlookup itself is degraded. On a **user-auth mesh**, the exchange selects one authorized manager\nfor a short-lived `manager-caller` view. `--on` requests a specific instance; without it, selection\nmust be unique. Discovery and the command use that instance route. The caller gains no registry\nread or scatter permission. An absent, ambiguous or unauthorized selection refuses before sending\nthe command.\n\nA seat is reported as **not found** only when every reachable instance answered for itself. An\ninstance that stayed silent past the deadline, or that refused the read rather than answering, said\nnothing about which seats it hosts, so the seat may be running on it. That case reports that the\nlocation could not be established, names the instances that did not answer, and states outright\nthat it is not a report that the seat is gone. Read it as unknown and retry with\n`--on <instance>`; a retry loop that treats it as \"already gone\" stops looking for a seat that is\nstill running. A single manager cannot tell \"hosted elsewhere\" from \"does not exist\": it answers\n`not-found` for both, which is why the search asks all of them and why an incomplete search\nconcludes nothing.\n- **User-auth mesh.** `cotal ps` reports what **one** authorized manager knows about your agents\n  (an instance-addressed read against its in-memory roster, owner-filtered). It does **not** report\n  other manager instances or establish whether they are reachable. Completeness across a\n  multi-manager user-auth space is not claimed.\n  A manager that does not answer fails the command outright (exit non-zero), rather than printing\n  an empty list that could be read as \"no agents\". Your ledger row needs the `admin` scope to\n  reach `ps` at all; `spawn` alone is refused by the broker (the ep tier boundary).\n\n`attach` streams and drives an agent's terminal on the `pty` runtime; detach with the escape key\n(Ctrl-] by default; see [`COTAL_DETACH_KEY`](config.md)). The key is recognised as the legacy\ncontrol byte and as the kitty keyboard protocol and xterm modifyOtherKeys encodings of the same\npress, so a terminal with either protocol enabled detaches too. It does so over a one-use, holder-bound\nmesh session ([SPEC](../SPEC.md) \xA713.6): the manager replies with a signed session grant (never a\n`127.0.0.1` URL), the CLI redeems it once over the broker, and the browser console (`cotal console`)\ndrives the same session. `stop` and `attach` need a running manager to talk to. On a static mesh\nthey are cross-agent admin operations. On a user-auth mesh, your own agents (any agent under your\nowner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger row\n([identity & auth](identity-and-auth.md)). Launch detached agents with [`spawn --detach`](#spawn).\n\n**`attach` reconnects when the link dies.** A session lives on a network link, and a laptop that\nsleeps, a VPN that drops or a wifi handover kills it. When that happens `attach` prints\n`[cotal: connection lost, reconnecting]` on stderr and starts asking the manager for a new session:\na fresh grant, a fresh per-session credential, a fresh connection, so every attempt re-runs the same\nauthorization the first attach did. On success it prints `[cotal: reconnected]`, the manager repaints\nthe seat's current screen the way it does for any attach, and you carry on in the same terminal.\nRetries wait 1s, 2s, 5s, 10s, then 30s, for as long as the seat exists. The detach key is read the\nwhole time the loop runs, the waits and the attempts alike, so a reconnect never traps you: press it\nwhile a session is being established and the attach ends there, and a session that lands behind the\npress is handed back to the manager rather than left holding a slot. Everything else you type while\nthere is no session is dropped rather than queued, so keystrokes aimed at a terminal that turned out\nto be frozen, Ctrl-C included, are not delivered to the agent by a reconnect you did not know had\nhappened. That starts before the first session, not at the first reconnect: at a terminal, `attach`\nreads and drops what you type while it is still resolving the mesh, so a key struck at a prompt that\nhas not come up yet does not reach the agent when it does.\nThe terminal is in raw mode for the whole reconnect, including when the link died before the first\nsession finished opening, so the detach key works there too instead of echoing as `^]`.\n\nA **pipe** carries script input. For example, `printf 'ls\\n' | cotal attach --name web` is\nbuffered until the session opens. Buffering continues across reconnects, so\n`tail -f log | cotal attach --name web` does not lose the part of its feed written while the link was\ndown. Only a terminal gets the reader; `--no-reconnect` keeps the old behaviour on both.\n\nIt stops on its own when reconnecting cannot help, and says why: a manager that refuses the attach\nexits non-zero with the manager's own message, and a reconnect that finds the seat no longer there\n(despawned, or its agent exited while the link was down) exits cleanly with `seat <name> is gone`.\nA local connect refusal that retrying cannot fix, such as a static-auth mesh whose seed is now\nmissing, also exits non-zero with the refusal's own sentence. A broker that is still unreachable\nkeeps the loop trying in silence.\nA refusal that could still pass, such as a manager at its session ceiling, is relayed in the\nmanager's own words while the loop keeps trying, once per refusal rather than once per attempt.\nPressing the detach key, or the agent's process exiting while you are attached, ends the attach as\nit always did. `--no-reconnect` turns all of this off and restores the single-session behaviour,\nwhich is what a script wants.\n\nEach reconnect also hands the abandoned session back to the manager, over the first link that can\ncarry the message, so an attach that flaps does not eat the manager's session slots one outage at a\ntime. If that message never gets a link, the attach says so when it ends. The live-session ceiling\ndefaults to 64 concurrent sessions (`--max-sessions`); the browser console opens one session per\npane, so a dashboard over a large mesh should size for agents \xD7 panes. Hitting the ceiling refuses\nbefore a credential is minted and names `--max-sessions`.\n\nWhich mesh `attach` resolves also decides **how it redeems the grant**. On a registered open mesh\nthere is no local seed. The CLI connects bare, the same way other control commands already do, and\nthe session rail is the caller rail that a real open-mode connection already reaches. Telling the\noperator to re-register the root is false: the registered root is already the contract. On a\nstatic-auth mesh the grant is still redeemed by minting a short-lived\nsession-scoped credential from the seed at the root the mesh resolved to, never from a `.cotal`\nfound by walking up from whichever directory you happen to be standing in. The difference is not\nhypothetical: `~/.cotal` exists on every install because the mesh registry lives there, so a command\nrun anywhere under your home directory but outside a project used to mint from your home\ndirectory's trust and present it to a broker that trusts a different chain, which surfaced as a\nbare authorization failure that named nothing. A directory that does hold another chain for the\nsame space is now reported on the way past, and not obeyed:\n\n```text\n! this directory resolves to /Users/you, whose .cotal/auth holds a DIFFERENT trust chain for space \"team\".\n  attach used /Users/you/projects/app, the root this mesh resolved to. The other one is not being used, and is worth a look.\n```\n\nWhen a **static-auth** mesh holds no seed at the resolved root, `attach` refuses and names what it\nresolved, the broker and the root, instead of describing a directory it did not use and instead of\ntaking the open-mode path. An authenticated registry entry with a missing seed is still\nauthenticated. On a USER-AUTH mesh `attach` reads no seed. It sends your login and the session grant to\nthe auth service, which issues a `session-caller` bearer only if your owner and actor hold that\nsession. The connection it opens expires with the session grant.\n\nTerminal bytes stream over the mesh; the manager's own HTTP/WS face serves the console. That endpoint binds\n**loopback by default**, so nothing is exposed by accident; `cotal up --host <addr>` passes its bind\naddress down, which is what lets you reach the browser console (`cotal console`) for an agent whose manager runs on another machine.\n`attach` does not use that face: it redeems a signed mesh session grant over the broker instead (see above), so it reaches a\nremote manager regardless of the bind address. A\nbare `cotal supervise` and an embedded manager stay machine-local. Set it directly with\n`supervise --console-host <host>`.\n\nThat address is **recorded on the mesh** and carried forward, because it is a decision rather than\nsomething later commands can work out for themselves (a broker dial address is not a manager bind\naddress). Every later manager launch for the same mesh reuses it, including a same-root `cotal up` repair,\nan adopted preserved or restored listener, and a `spawn -f` manifest deploy. A manager replacement\ndoes not quietly move a reachable attach face back to loopback. Passing `--host` again overrides it,\nso you can widen or narrow exposure whenever you like; a mesh that never asked stays loopback-only\nand records nothing.\n\nBecause that face mints terminal read and write authority for every managed agent's browser session, it is credentialed in two\ntiers. A mesh caller receives a **ticket** bound to the single agent the manager just authorized,\nsingle-use and short-lived, so one authorized attach can never be re-pointed at someone else's\nagent. The **console token** is the operator's own, reaches every agent, and is printed only to the\nmanager's output. The roster, the live feed, and the PTY stream all answer `401` without one; the\nstatic console shell is served openly, since it describes no agent.\n\n## input\n\n```bash\ncotal input --name <n> --text <text> [--no-enter] [--on <instance>] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | | Managed agent to type into (required) |\n| `--text <text>` | | The text to type, taken verbatim (required) |\n| `--no-enter` | off | Type the text and stop there, without pressing Enter |\n| `--on <instance>` | class anycast | Pin to one manager instance id using the same rules as [`attach`](#managed-seats) |\n\nTypes one line into a running agent's terminal, as if you had typed it there, and returns. This is\nthe half of [`attach`](#managed-seats) that a program wants: `attach` is a live stream that holds a\nsession open and expects a terminal on your side, so a script, a cron job or a web UI cannot use it\nto send a single line. `input` is one authorized call.\n\nWhat it is for is **harness commands**. A line beginning with `/` is not chat and not a message: it\nis something the agent's own harness handles, and the only way in is the keyboard.\n\n```bash\ncotal input --name reviewer --text \"/compact\"          # ask the harness to compact its context\ncotal input --name reviewer --text \"/model opus\"       # switch its model\ncotal input --name reviewer --text \"hold on that PR\"   # ordinary typing works too\n```\n\n**Quoting.** `--text` takes a value, so a payload starting with `/` survives as written. A payload\nstarting with a dash needs the `=` form, because the shell-style `--text --foo` is ambiguous and is\nrefused rather than guessed:\n\n```bash\ncotal input --name reviewer --text=--verbose          # dash-leading text: use --text=<value>\n```\n\nEnter is pressed by default, since a command typed but never submitted has not been delivered.\n`--no-enter` types the text and leaves it sitting at the prompt, which is how you stage a line and\nsend it later.\n\nNothing comes back but a delivery receipt (`\u2713 sent 9 bytes to reviewer`, counting the trailing\ncarriage return). Whatever the agent does next shows up where its output already goes: the mesh, its\ntranscript, or an `attach`.\n\n**This one is operator-only, and more narrowly than `stop` or `attach`.** Those two are granted to\nanything holding `spawn`, so an agent can stop and attach to seats under its own owner. `input` is\nnot: it is granted only to operator credentials, which on a user-auth mesh means your ledger row\nneeds the `admin` scope, the same scope [`ps`](#managed-seats) already needs there. The reason is\nthat a write into a terminal is control of whatever is running in it, and on a user-auth mesh the\nown-owner rule covers every seat under you, not only the ones you launched: a `spawn`-scoped agent\ncould otherwise type into a sibling it never started. Seat locality is still resolved for you.\n\nOnly the `pty` runtime can be typed into. The external terminal runtimes (`tmux`, `cmux`, `orca`,\n`herdr`) attach to a process they do not own, so they have no input stream for it and the command\nrefuses by name rather than dropping the keystroke.\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | none | `new`: the persona's role |\n| `--model <m>` | none | `new`: the persona's model |\n| `--prompt <t>` | none | `new`: the persona's prompt text |\n| `--from <f>` | none | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | none | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under the resolved mesh root's `.cotal/agents/`, the same catalog\n`cotal spawn` launches from. `--space` and `--server` therefore move every list, read, write, delete\nand completion operation to the selected mesh. An unresolved target refuses rather than falling back\nto the current directory. See [Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <name>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | hosting mesh, or matching registered mesh | Broker URL. A registered mesh supplies it when omitted; a different explicit value is refused before anything is dialed. |\n| `--runtime <name>` | `pty` | Agent runtime (`pty` built in; extension runtimes are explicit-only) |\n| `--console-port <n>` | none | Protocol-console port |\n| `--console-host <host>` | loopback | Bind host for the console endpoint. Loopback keeps it machine-local; `cotal up` passes the address it bound the broker to, which is what lets the browser console reach this manager from another machine. `cotal attach` does not use this face: it redeems a mesh session grant over the broker |\n| `--max-sessions <n>` | 64 | Live-session ceiling. Each console pane and each `cotal attach` is one session, so size for agents \xD7 panes, not agent count. A capacity refusal names this flag. `cotal up --max-sessions` records the same number on the mesh so a later `supervise` started by repair or `spawn -f` keeps it |\n| `--roster <file>` | none | Declarative roster to boot at startup |\n| `--launch <spec>` | none | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | none | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; install an\noptional provider first (`cotal ext add @cotal-ai/orca`, `@cotal-ai/tmux`, `@cotal-ai/cmux`, or `@cotal-ai/herdr`) and\nselect it explicitly. A missing provider or app fails loudly; there is no fallback. See [Deploy](deploy.md).\nBoot inventory decides whether this process takes unpinned `spawn`/`launch` on the class rail:\nif every declared connector is unavailable, those commands stay on this instance rail only\n(`status` reports `classSpawn: false`). `describe` still answers on the class rail, so an\nunpinned spawn can bind-fence against a skip member; re-issue, or pin `--on`. A partial\ninventory keeps the class rail and names `--on` on a harness refusal, because sibling\ninventories are not readable from the serve credential. See [control surface](control-surface.md#instance-routing).\n\nOn a normal `SIGINT`/`SIGTERM`, the manager stops every seat and requires the selected runtime to\nprove the seat is gone before it releases the manager lease or service registration. A stop that\ncannot prove exit fails loud and keeps manager authority instead of reporting a clean shutdown while\nan orphan still holds broker rails. After an abrupt manager death, the same logical successor\nterminalizes only its own durable static slots, verify-evicts the predecessor's broker principal,\nrecords that result in the lifecycle's caller-readable audit detail, reaps the predecessor's seat\nprocess through the runtime's custody reference recorded on the slot (the pty runtime verifies the\nprocess start identity in its seat record, so a reused pid is never signalled), and only then\nretires the lifecycle and frees the alias. A runtime that custodies its seats reserves that\nreference before it launches one, and the manager records it on the slot's first durable row, so a\nmanager that dies part-way through a spawn also leaves a seat its successor can address. A spawn\nthat launched its seat and then failed is rolled back by the manager that launched it, and that\nrollback reaps the seat through the same reserved reference before the lifecycle retires. Missing or unverified broker evidence keeps the slot\nterminalizing, and so does a runtime that cannot reap by reference.\n\nA `meshes add --mode user` entry is a **participant** registration, not hosting authority. A\nparticipant may run `supervise` only when the host advertises the remote manager authority service\nand the signed-in actor has the dedicated `supervise` ledger scope. The CLI obtains the closed,\nloopback-only `manager-service` view; `spawn` and `admin` do not substitute for that scope. The\nhost issues the manager's public-nkey JWT material through its lifecycle-bound prepare \u2192 activate\n\u2192 renew protocol, never by handing the participant a signer or static provisioner credential.\nThe host also performs instance-scoped eviction and guarded gate reconciliation. A remote manager\nrefreshes its short-lived registration executor before clean deregistration, so a long-running\nprocess removes its service row on `SIGINT` or `SIGTERM`. After an unclean stop, the same instance\nverify-evicts its superseded family and advances the process epoch. If an abandoned frozen gate\nholds the manager governance slot, a different supervise-scoped manager asks the host to reconcile\nthat holder after a complete gone verdict, then retries its registration once.\n\nA remote supervise never uses local signing trust: with host-issued authority in hand, the\nmanager mints from that authority alone and consults local records only to refuse a conflict,\nnamely the supervised space's own trust records under the cwd root. A root that hosts another\nstatic space beside the sign-in is a normal configuration and is never read as this space's\ntrust.\n\nThe broker URL in the registry entry decides the transport. A remote broker is often published\nover a `wss://` edge rather than a raw `nats://` port, and `supervise` dials whichever scheme the\nrecord holds, starting with the manager-authority registration it runs before the manager exists.\nThe record also decides whether that registration requires TLS, so a participant never downgrades\nthe credential exchange to a plaintext connection the registry did not describe.\n\nWithout that advertised host service or scope, `supervise` refuses before it starts a manager.\nRun `cotal spawn` without `--detach` to launch a foreground agent, or ask the space host to enable\nthe authority service and grant `supervise` for detached agents. If a running remote manager loses\nrenewal, it reports degraded state and refuses unsafe new starts and restarts; live agents are not\nsilently replaced. Do not run `cotal down` or `cotal up` on a participant machine to repair this\ncondition.\n\n## service\n\n```bash\ncotal service install [--mesh <name>] [--linger]\ncotal service status [--mesh <name>] [--json]\ncotal service uninstall [--mesh <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--mesh <name>` | this folder's mesh | The mesh whose manager the service runs; one unit per mesh |\n| `--linger` | off | install: when lingering is off, ask logind to enable it so the user manager starts at boot and the service survives logout. Never enabled silently |\n| `--json` | off | status: machine-readable output |\n\nRuns the manager as a user service so it survives logout and reboot. On Linux this installs a\nsystemd user unit (`~/.config/systemd/user/cotal-manager@<key>.service`, where `<key>` is the\ncase-safe mesh key); on macOS a launchd agent plist under `~/Library/LaunchAgents/`. Any other\nplatform, or an absent systemd/launchd user session, fails with a message naming what is missing.\n\n`install` resolves the mesh from the registry and binds the unit to that entry's root and broker\naddress, so it can be run from any directory. The mesh must be registered (`cotal up` or\n`cotal meshes add`) before installing; an unregistered name refuses before anything is written.\n\nThe unit's `ExecStart` is the bare `supervise` command. The mesh facts travel in a `0600`\n`EnvironmentFile` (`COTAL_SPACE`, `COTAL_SERVER` pinned to the registered broker URL, whatever\nport it listens on) rather than the command line, because command lines are readable by every\nuser on a multi-user host. The same file gives the service a private `COTAL_HOME` and\n`XDG_CONFIG_HOME` under the unit directory, so the service manager never touches the login\nuser's `~/.cotal`. First-run connector seeding runs synchronously inside `service install`,\nagainst that private config root; the unit itself starts with `COTAL_SKIP_CONNECTOR_SEED=1`\nso a manager is never interrupted mid-seed by a restart. An install whose pre-seed cannot\ncomplete (network unreachable, registry error) refuses instead of deferring.\n\nThe same file pins `PATH` to the `PATH` of the shell that ran `install`, and on macOS the plist's\n`EnvironmentVariables` carry it too. Without it the unit inherits the service manager's own short\n`PATH`, which usually lacks `~/.local/bin` and Homebrew, so the manager's boot inventory would\nreport a harness unavailable that your shell resolves. Install from a shell that resolves every\nharness the service should launch, and reinstall after moving one. A relative entry, including\nan empty one, is resolved against the directory you ran `install` from, because the unit starts in\nthe mesh root where the same spelling names another directory. An entry with a `..` segment is\npinned as the directory your shell reaches through it, with symlinks followed, and refuses when it\nreaches none. A `PATH` set to the empty string is one empty entry, so it pins that directory. An\nunset `PATH` refuses.\n\nEvery value the unit derives from a path (`WorkingDirectory`, the `EnvironmentFile` path, the\n`ExecStart` tokens) is escaped for systemd specifiers (`%` becomes `%%`), so a mesh root that\ncontains `%` starts over its real path instead of a path systemd rewrote by expanding it. The\nprovenance comment records the root unescaped.\n\nOn Linux a user unit starts at boot and survives logout only while the user lingers. Without\nlingering, systemd starts no user manager at boot, so an enabled unit stays inert until the next\nlogin and stops at the last logout. `install` checks lingering before it writes anything, and when\nlingering is off it fails with the root command that turns it on (`sudo loginctl enable-linger\n<user>`). With `--linger` it first asks logind to enable lingering for the current user, and fails\nwith the same command when logind refuses (unprivileged users over SSH get `Access denied`).\n`service status` prints that command while lingering is off. A Linger query that does not answer\n`yes` or `no` (logind unreachable, no `loginctl`) is never read as off: `install` refuses with\nthe query's own error and enables nothing, and `service status` shows lingering as unknown with\nthat error (`--json` gives `\"linger\": { \"error\": ... }`).\n\n`service install` also refuses while a manager is already running for the mesh (`cotal down\nmanager` first). The restart policy is `Restart=always` with `RestartSec=20s`, chosen for\nmanager units in production: a manager exits for reasons that are not failures (broker\nrestarts, host suspend), where `on-failure` with a short interval thrashes.\n\nThe unit also sets a start limit (`StartLimitIntervalSec=30min`, `StartLimitBurst=20`). A manager\nthat keeps failing to start stops after 20 attempts, about seven minutes at 20 seconds apart, and\nthe unit is left `failed` instead of restarting forever. One such failure is deliberate. After an\nunclean stop, a manager that cannot verify eviction of its predecessor's credentials exits 1 and\nleaves the issuance gate frozen, because starting without that proof could let two incarnations\nserve at once (SPEC 13.1). It first waits up to 60 seconds for the delivery daemon to answer, so a\ndaemon that is still starting does not fail the start. The log names the cause. When the delivery\ndaemon is down, it says the daemon is not reachable on the `ctl.delivery-admin` rail. When the\ndaemon answers and refuses, for example because the space is missing a `$SYS` cred, it prints the\ndaemon's own reason and repair step. Fix that cause, then run `systemctl --user reset-failed\n<unit>` and `systemctl --user start <unit>`. The macOS agent has no start limit: launchd's\n`ThrottleInterval` only spaces restarts.\n\n`service status` reports the unit state from systemd/launchd, the manager's own health read from\nits pidfile at the unit's recorded root, and the machine facts a hosting side asks for:\narchitecture, OS (the platform, never the hostname), whether `/dev/kvm` is present and\naccessible, CPU count, and total memory. `--json` returns the same fields as one object.\n\n`service uninstall` stops and disables the unit and removes it plus the private state directory.\nIt works from any directory: the unit's own records name the mesh and root it serves, and an\nexplicit `--mesh <name>` selects it. It refuses any unit that was not written by `service\ninstall` (the files carry a provenance comment), whose recorded mesh is missing, or that was\ninstalled for a different mesh, so operator-written units are never destroyed; `service status`\napplies the same rule and never reports a mesh a unit does not record.\n\nThis command installs only the manager. The per-space auth service and the delivery daemon are\nnot installed by it: on a shared broker an operator runs three units per space with `After=`\nedges (auth service, then manager, then delivery) and stops them in reverse. A broker-side `cotal\nup` unit is a separate unit documented in [Run a mesh](run-a-mesh.md).\n\n## reconcile-gate\n\n```bash\ncotal reconcile-gate [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the frozen gate lives in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint whose gate is frozen |\n| `--instance <id>` | this folder's persisted manager instance | Instance id |\n\n**When you need this.** A manager restart killed after deregistration begins but before the new\nincarnation finishes leaves the endpoint's issuance gate *frozen*, held by a\nprocess that no longer exists. The freeze is what stops two incarnations serving at once, which is\ncorrect. The successor manager now completes that dead registration itself on boot, including on\nthe remote user-auth path. A foreign remote manager blocked by this gate also asks the host to repair\nit before one registration retry. Both use the same guard this command uses: they act only when the freeze-holder is affirmatively gone under a complete\nCONNZ sweep (`gone` and `sweepComplete=true`). If that registration's spec write already committed,\nit finishes the same freeze at the committed registration revision. If the spec did not advance, it\nabort-reopens the gate at generation+1 with processEpoch unchanged and continues the normal takeover.\nLive, unknown, unestablishable, and\nwrong-op-kind still refuse; there is no TTL.\n\nUse this command when the automatic path cannot run: the delivery daemon is down, the repair targets a\nnon-manager endpoint, or you want to lift the freeze without starting a manager. It checks that the\nholder really is gone, prints what it found, and then finishes the dead operation the same way as the\ninterrupted restart would have: revoke the old credentials, evict their holders with verification,\nand reopen the gate.\n\nThe command revokes the old credentials 16 at a time. It then verifies the holders' eviction in\nshared sweeps of up to 256 holders on the delivery daemon. Each sweep scans the broker a fixed number\nof times and kicks live connections 16 at a time, so holders that are already gone add almost\nnothing and live ones add one broker round trip per 16 connections. The daemon must serve the\n`evictPrincipals` verb; an older daemon refuses it and the gate stays frozen.\n\nEach sweep durably records the holders it verified before the next sweep starts. If a holder is not\nverified gone, the command leaves the gate frozen with those records kept. An interrupted sweep\nrecords nothing, and the sweeps before it stay recorded. A retry still repeats the freeze-holder\nliveness check, then skips only progress bound to the same registration operation, frozen-gate\nrevision, and holder set.\nThe output reports holders completed before this attempt, completed now, and still remaining. A new\nfreeze or changed holder set starts from zero. Cursor cleanup happens only after reopen; a retained\ncursor is harmless because its old gate revision cannot authorize a later freeze.\n\n**It refuses far more often than it acts, on purpose**, and always says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `holder-alive` | The freeze-holder still has a live connection: a manager *is* running | Stop that process first. Reconciling would evict a live manager's credentials |\n| `holder-unknown` | The connection sweep could not prove the holder absent | Not safe to proceed: an unprovable holder is treated as a live one. Re-run once the broker answers completely |\n| `liveness-unestablishable` | The delivery daemon gave no verdict: it was unreachable, timed out, or refused | Act on the delivery lease line in the refusal (below). Silence is never read as death |\n| `not-frozen` / `no-gate` | The gate is open, or there is no gate at that coordinate | Nothing to repair: check `--endpoint` / `--instance` |\n| `wrong-op-kind` | Frozen under a takeover or retirement, not a registration | Out of scope for this command; it will not reinterpret another operation's intent |\n| `eviction-unverified` | The holder looked gone but eviction could not be verified | The gate is left frozen, unchanged. Investigate the broker before retrying |\n| `raced` | A newer manager moved the gate mid-repair | Re-run `cotal doctor` and look again |\n\nWhen the daemon gives no verdict, the refusal also reads the delivery lease (`lease.0`) and names\nwhat is blocking the rail:\n\n| Lease reading | What to do |\n|---|---|\n| absent | No daemon is running. Start it (`cotal up` runs it) and re-run |\n| unreadable | The daemon cannot be named, so do not assume none is running. Fix the lease read, then re-run |\n| held, not ready | That holder claimed the shard and has not bound its rails. Wait for it, or stop it so its lease lapses |\n| held, ready, no answer | The query may have gone to another daemon still subscribed to the rail, such as a stopped one whose lease lapsed. Re-run before stopping anything. If no run gets an answer, stop any other delivery daemon for the space, then stop or restart the holder |\n| changed hands | The holder took the shard after the query was sent, so it was never asked. Re-run before stopping anything |\n\nThe command reads the lease before it sends the query and again after the query fails. It names a\nholder as the blocker only when the same run of the same daemon held the lease both times, and two\nrows from a daemon too old to record its run never count as the same run. Even then a ready holder\nmay not have been asked: the rail is queue-grouped, so any daemon still subscribed to it can take\nthe query. A row whose times are not valid dates reads as unreadable.\n\nA daemon that answered and refused keeps its own reason, followed by the same lease line. The lease\nline names the holder, whether it is ready, the space account that holds the lease bucket, when that\nholder acquired the shard, and when the row was last written. A ready holder rewrites the row on\nevery renewal and keeps its acquisition time, which only a successful acquisition sets. A row\nwritten by a daemon that predates the acquisition time reports it as unknown. The lease reads never\nchange the outcome: the gate stays frozen and the command exits 2. A manager's boot self-heal uses\nthe same check and reports the same line.\n\nThere is no `--force`, and no path that discards gate state: the only way this reopens a gate is by\nproving the holder is gone and then completing the operation properly.\n\n**What reopening the gate does for the endpoint's governance slot.** A registration takes the\nendpoint-wide governance slot before it publishes its spec, and holds it until its gate reopens. An\ninstance that died between those two points leaves the slot held with no registration behind it.\nThis command does not write that slot and never has; the registration path is its only writer. What\nthe reopen does is advance the holder's gate past the generation the slot is stamped with, which is\nwhat marks the slot abandoned. The next registration for that endpoint then reclaims it as part of\nits ordinary start. So the repair here is still one command followed by starting the manager, and\nthe slot needs no separate step.\n\n## deregister-instance\n\n```bash\ncotal deregister-instance [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the instance is registered in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint the instance serves |\n| `--instance <id>` | this folder's persisted manager instance | Instance id, the whole id as `cotal ps` prints it |\n\n**When you need this.** The service registry records *registration*, not liveness, and nothing in\nthe model expires a row. A manager that stops cleanly removes its own registration. One whose host\ndied without writing anything cannot, so its record goes on claiming a live instance forever: every\nclass scatter in that space freezes the dead slot in, and `cotal ps`, `stop` and `attach` each pay\ntheir whole deadline waiting for a machine that is never coming back. A laptop that was reimaged, a\ncontainer that was deleted, a box that will not be back on the network: those registrations have no\nother exit.\n\nThis command is that exit. It asks the instance first, and it removes a record only when the broker\naffirms the instance's own rail is empty: nothing subscribed there. Then it deletes the\nregistration's two records keys, each pinned to the revision it read, and prints what it removed.\n\n**Silence alone never passes.** An unanswered describe is what a dead host, a wedged process and a\nslow one all look like, and a hung process still holds its subscriptions, so the broker sees\ninterest on its rail. That instance is refused and the observation is printed. A dead process holds\nno connection and therefore no subscription, so a real corpse is still removed.\n\n**Every refusal names the failed check:**\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `instance-answered` | The instance answered a pinned describe. It is alive | Nothing to repair. If it is wedged rather than gone, stop the process first; its own clean stop removes the record |\n| `instance-not-affirmed-gone` | It did not answer, and the broker did not report its rail empty, which is what a held subscription looks like: slow or hung, not affirmed gone | Nothing was removed. Stop the process; its record goes on its own clean stop, or re-run this once it is down |\n| `liveness-unestablishable` | The probe itself failed, so nothing was learned | Fix the probe's path (credential, broker) and re-run. A probe that could not run is never read as death |\n| `not-registered` | No registration at that coordinate | Check `--instance` and `--endpoint`. This takes the whole id, never a prefix |\n| `registration-in-flight` | The instance holds the endpoint governance slot at the live issuance-gate generation, so a registration is still completing | Nothing was removed. Wait for that registration to finish, then re-run |\n| `superseded` | The record moved between the read and the delete | Something is writing to it. Nothing was removed; re-observe before retrying |\n\nThere is no `--force` and no sweep: silence is not death, and a rule that removed rows on silence\nwould eventually remove a live instance that was merely slow. An operator names one instance, the\nbroker's verdict on its rail is what authorizes the removal, and the guard's job is to show them\nthey named a dead one. Removal is not a one way door either. The same instance re-registers over\nthe tombstone on its next start, under the same identity.\n\n## runtimes\n\n```bash\ncotal runtimes\n```\n\nLists every agent runtime the manager can spawn through: the built-in `pty`, the official providers\n(`orca`, `tmux`, `cmux`, `herdr`), and any custom provider installed via `cotal ext add`. Each installed\nprovider is probed so you can see what is actually reachable on this machine before selecting it:\n\n```\npty    built in\norca   installed \xB7 reachable   @cotal-ai/orca\ntmux   available \xB7 cotal ext add @cotal-ai/tmux\ncmux   available \xB7 cotal ext add @cotal-ai/cmux\nherdr  available \xB7 cotal ext add @cotal-ai/herdr\n```\n\n`installed \xB7 reachable` / `unreachable` is the provider's own `available()` probe; `available` means\nit is a known runtime you can add with the shown command. Selecting an unknown or uninstalled runtime\nvia `up`/`spawn --runtime <name>` fails loud and, for a known one, points at the exact `cotal ext add`\npackage. There is no silent fallback to `pty`.\n\n## seats\n\n```bash\ncotal seats [--drain]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--drain` | off | Retire every seat whose agent has exited. A seat whose agent still runs is kept |\n\nThe pty runtime used to start a detached custodian process for every Linux seat. It now spawns\nin-process, but custodians that an earlier manager started keep running, and one whose agent has\nexited stays resident while a manager still holds its connection. This command lists the custody\nrecords under `COTAL_SEAT_ROOT` (default `~/.cotal/seats`), one line per seat:\n\n| State | Meaning |\n|---|---|\n| `live-child` | The agent process still runs. The seat is never signalled, and a manager can still adopt it |\n| `childless` | The agent has exited. `--drain` retires the seat |\n| `drained` | `--drain` proved the custodian and the agent gone and removed the record |\n| `refused` | The record cannot be read, carries no start or boot identity, comes from an earlier boot, or the reap could not prove the processes gone. The record stays on disk |\n\nA drain signals only a custodian whose recorded start identity still matches the live process, so\na reused pid is never touched. A record whose identity cannot tie its pids to this boot's processes\nis refused with or without `--drain`, and is never reported as running or exited. That refusal and\nan unreadable record signal nothing. A refusal from the reap itself can come after the drain already\nsent `SIGKILL` to the custodian. Its detail names the pid or process group the reap could not prove\ngone, so check those processes before you retry. The command exits non-zero when any record is\nrefused. It is Linux-only and throws on other platforms.\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\nA `send dm` prints one line naming three facts: `\u2192 <name>  stored seq <N>; recipient <status>\nat send; delivery not confirmed  <text>`. `stored seq N` is the JetStream sequence the broker\nassigned to the publish; `recipient <status> at send` is the roster status (`idle`, `working`,\nor `offline`) resolved right before the publish, which can change the instant after; the send\nnever prints `delivered`, because the sender's credential cannot read the recipient's durable\nto confirm it. Inspect what the broker actually holds for a recipient with\n[`cotal deliver pending`](#deliver).\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n`cotal send` works from an operator shell or from a seat. Its display name is `<login>@<host>` of\nthe shell that ran it, so the recipient can tell one operator's send from another's; it is taken\nfrom the operating system, never from `COTAL_NAME`. The wire principal comes from the resolved\noperator credential or user bearer, not from `COTAL_NAME`, `COTAL_ID`, `COTAL_OWNER`, or\n`COTAL_ACTOR`. On an open mesh the transient endpoint self-mints its principal.\n\nThe transient endpoint never joins the roster and binds no inbox. A recipient can still answer a\n`send dm` or `send ask` with `cotal_dm`, by the sender's name or by the id on the message it\nholds: the reply is stored under the sender's id in the space's DM history, which an operator's DM\nview such as the dashboard's Direct messages lens shows. The `cotal send` that asked has already\nexited, so the reply never reaches that shell.\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | none | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | none | `set`: replay window size |\n| `--desc <s>` | none | `set`: one-line channel description |\n| `--instructions <s>` | none | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived\nchannel-writer view, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\nOn a remote user-auth mesh that view is served by the public exchange; space-history `purger`\nand the read-only admin view are not.\n\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | none | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. Inside the TUI, operator control (`D` kill, `:spawn`, `:status`, `:purge`) rides the\nsame per-action instrument path as `cotal stop` and `cotal ps`, never the observer; a raw\n`--creds` file cannot drive it. `a` (or `:attach <agent>`) runs\n[`cotal attach`](#managed-seats) in place and returns to the console on detach. See\n[Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal web [--detach] [--host <host>] [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--host <host>` | `127.0.0.1` | Concrete HTTP bind and browser host; wildcard addresses are refused |\n| `--port <n>` | `7799` | HTTP port |\n| `--detach` | off | Run in the background; stop with `cotal down web` or bare `cotal down` |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships inside `cotal-ai` as the `@cotal-ai/web` extension, seeded automatically on first\nrun (like the built-in connectors) so it always matches your CLI version. It self-registers `cotal web`\ninto this surface and serves\n`http://cotal.localhost:7799` by default (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. The public exchange serves `channel-purger` for a remote owner; it still\nrefuses the startup admin view, so a remote `cotal web` is not a complete channel-management\nsurface. Detached mode re-execs the current Cotal installation, writes diagnostics to\nthe mesh root's `.cotal/web.log`, and reports success only after the HTTP server answers. It requires\na recorded mesh root, but can be launched from any directory once `cotal up` has recorded the mesh.\nSee [Watch a mesh](watch-a-mesh.md).\n\n## deliver\n\n```bash\ncotal deliver [--space <s>] [--server <url>] [--tls] [--creds <file>] [--root <dir>] [--shard <n>] [--shards <n>] [--dev-mint]\ncotal deliver pending <name> [--limit <n>] [--durable <name>] [--json]\n```\n\nWith no positional, `cotal deliver` runs the delivery daemon (see\n[the delivery daemon](delivery-daemon.md)). `deliver pending <name>` never starts the daemon: it\nis an operator-only read over one recipient's DM durable, for the moment after a send when the\nquestion is \"what does the broker actually hold for them.\" It resolves `<name>` against a short\npresence watch (an `offline` card still counts, since the recipient may be dead, that is what\nthe verb exists to inspect); when neither a card nor the durable can be found, it prints\n`\u2717 not-found: no agent \"<name>\" and no DM durable for it in space <s>` and exits non-zero, never\n`pending 0`. On a match it prints the durable name and one fact per line: `pending`,\n`ack-pending`, `delivered`, `ack-floor`, `created`, `frontier`, and the stream's `max_age` /\n`max_msgs_per_subject` / `discard` limits (`--json` prints the same facts as one object), followed\nby a bounded, unacked read of up to `--limit` (default 20) recent candidate message ids under the\nheading `recent candidate ids (from the ack floor; not proof of a hole)`, a list of what is\nthere, not proof that nothing was lost.\n\nThe verb needs the `admin` credential profile: it runs through the same static-mesh route as\n`cotal mint --profile admin`, and refuses a user-mode mesh, naming the retired static credential,\nbecause there is no user-mode inspection authority yet. Pass `--creds <file>` for an off-registry\nadmin credential. A same-name respawn never inherits a predecessor's held DMs (the durable is\nlifecycle-keyed); an old lifecycle's durable is reachable only by the name a live read printed\n(the `<durable>` line on the first line of this verb's output). Pass that name with `--durable\n<name>` to read it directly once the lifecycle's card is gone from the roster. This skips the\npresence watch on `<name>` entirely, so `<name>` is required but only echoed in error text.\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\ncotal mint <name> --provision [--role <role>] [--space <s>] [--server <url>]\ncotal mint <name> --expires-in <seconds> | --expires-at <unix-seconds>\ncotal mint <name> --identity <creds> [--expires-in <seconds>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/space.<key>/<name>.creds` | Output path - the default sits under the resolved space's segment (`<key>` is that space's hex encoding, as in [Project files](config.md#project-files)) |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | the agent file's, else subscribe | Read-ACL override, **agent profile only**: `observer` and `admin` carry a fixed read set, and `mint` refuses this flag there rather than narrowing nothing |\n| `--allow-publish <a,b>` | the agent file's, else deny | Post-ACL override, **agent profile only** |\n| `--role <role>` | the agent file's | Agent profile: the anycast task queue the identity pulls (`svc_<role>`) |\n| `--provision` | off | Agent profile: also pre-create the identity's bind-only DM/deliver durables (and its role's task queue) on the live mesh, so the credential can consume |\n| `--expires-in <seconds>` | unbounded | Bound the credential's lifetime: the JWT `exp` is `iat + <seconds>`. A positive integer; refused together with `--expires-at` |\n| `--expires-at <unix-seconds>` | unbounded | Bound the credential to an absolute `exp` (unix seconds). Refused together with `--expires-in` |\n| `--identity <creds>` | a fresh identity | Re-mint for the nkey carried by this creds file, keeping the principal and every durable keyed to it. The file is read by the same loader the endpoint uses; a file with no seed is refused by name |\n| `--space <s>`, `--server <url>` | the resolved mesh | Which root supplies the agent file, static trust and default credential storage; with `--provision`, also which live mesh receives the durables |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\nFor an agent profile, the resolved mesh root supplies the persona ACL, the signing material and the\ndefault credential destination as one authority. If the current folder also holds trust for a\ndifferent space or account, mint refuses before writing and names both roots. It never combines a\npersona from one root with credentials signed or stored under another.\n\nA plain mint is creds only: the identity can publish within its post ACL at once, but on an authed\nmesh its DM inbox and task queue are provisioner-pre-created and bind-only, so a **consuming**\nconnect fails until they exist. `--provision` performs that pre-create in the same command (a\nprovisioner cred is minted from the space's trust material, used, and dropped), so a long-running\nclient you start yourself can receive DMs and role anycasts like a spawned seat. The command prints\nthe identity's principal (its wire id) and lifecycle uid; a consuming client passes that uid as its\n`lifecycleUid`. Agent profile only; an open mesh needs none of this (peers self-create there). The\nsame resolved authority is used for both the credential and `--provision`, so the broker\nfootprint cannot be created under a different root's trust material.\n\nThe CLI-mintable profiles carry no default TTL: without a lifetime flag the credential is\nunbounded, and a standing-renewal consumer refuses it. `--expires-in <seconds>` (or\n`--expires-at`) is the door the renewal seam's own error names. `--identity <creds>` re-mints for\nthe nkey the file already carries, so the new credential presents the SAME principal and every\ndurable keyed to it survives; combine it with a lifetime flag to rotate an expiring credential\nwithout churning the identity.\n\n## Login\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. When the trusted\n`/token` response advertises a same-origin space catalog, login validates and records that account's\nspaces immediately. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session, clears its cache, and removes only that\naccount's discovered registry entries. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\n# an upsert of the WHOLE row: name all three ACL flags, or pass --full for the wide defaults below\ncotal actor grant <actor> --sub <IdP subject> --scope a,b --allow-subscribe a,b --allow-publish a,b [--role <r>] [--label <l>]\ncotal actor grant <actor> --sub <IdP subject> --full [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | none | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | none | The derived owner token (alternative to `--sub`) |\n| `--full` | off | Fill each ACL flag left off with its wide default; without it, `grant` refuses unless all three are named |\n| `--scope <a,b>` | `spawn,role:default` with `--full` | Capability scope (`''` = none; `spawn` = may run agents; `role:<r>` = may delegate role r; `admin` = cross-agent control; `supervise` = eligible for the closed remote manager-service view when the host enables it) |\n| `--allow-subscribe <a,b>` | `>` (all channels) with `--full` | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) with `--full` | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | none | Role (scopes the task-queue consumer) |\n| `--label <l>` | none | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\n`grant --full` is the **full** envelope (all channels; scope `spawn,role:default`, so it may spawn and may delegate the default role). A\n`grant` that leaves off `--scope`, `--allow-subscribe` or `--allow-publish` without `--full` is\nrefused and writes nothing. A re-grant **replaces the whole row**, not the one field you name, so to add a capability spell\nevery field out: the new scope plus the row's current read set, post set, role and label\n(`cotal actor list` shows what a row holds). Under `--full`, a field left off does not stay as it\nwas: it reverts to the wide default in the table above. A re-grant retires the current interactive lifecycle through the running auth\nservice before it rotates the row, so copied bearers cannot cross an authorization update. If that\nretirement cannot be confirmed, the row is left unchanged and the command fails with the recovery\naction. `revoke` uses the same retirement before deleting the row, which lets a later grant create a\nreal successor instead of colliding with a live predecessor. `supervise` is separate from `spawn` and `admin`: it only makes a signed-in\nperson eligible for the host-provided closed remote manager-service view; it does not grant\nmanagement of another owner or a general host profile. `revoke` denies the next exchange and\nthe next connect with no restart, and evicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at. `--fix` takes the mesh's renewal lease when the broker answers and refuses while\na manager or another doctor holds it; with no broker it repairs offline and says so.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | none | Your presence name |\n| `--role <r>` | none | Your role |\n| `--channel <c>` | none | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | none | Join link (`cotal://\u2026`) |\n| `--token <t>` | none | Join token |\n| `--lifecycle-uid <uid>` | none | Required with `--creds`: the lifecycle UID minted alongside the credential (`COTAL_LIFECYCLE_UID` works too). A credential's durable grants name exact lifecycle-keyed resources, so `join` refuses to invent one |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext                 # same as `list`\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\ncotal ext root            # print just the install prefix (scriptable)\ncotal ext seed [--repair|--reset|--force]\n```\n\nOperator-installed extensions: `add` installs an npm package into a cotal-owned prefix and records\nevery registry provider it contributes. Commands appear in help, completion, and dispatch; runtime\nproviders are lazy-loaded by commands such as `supervise`; local process providers participate in\n`status` and selective `down`. `remove` and `list` manage them. The `@cotal-ai/web` dashboard is the\ncanonical command/process example. Installed packages and their location are described in\n[config](config.md).\n\nBare `cotal ext` lists the inventory, headed by the install prefix. That prefix is a cotal-owned npm\nroot kept **separate** from npm's own global tree. These packages never show up in `npm list -g`,\n`cotal ext` (or the Extensions section of `cotal status`) is the canonical inventory. `cotal ext root`\nprints only the path, for scripts. The versions shown are the manifest pin recorded at add time.\n\nRemoving an extension that owns a running local process is refused with the mesh root and its\n`cotal down <component>` command; stop it first so uninstalling the package never strands a process\nwhose lifecycle provider is gone.\n\n### Built-in connectors are seeded extensions\n\nThe first-party agent connectors (`claude`, `opencode`, `codex`, `hermes`, `jcode`, `pi`) are not compiled into\nthe binary. They are seeded on first run through the **same** `ext add` path a third party uses, and\nappear in `cotal ext list` like any other extension. So you can remove one you do not want\n(`cotal ext remove @cotal-ai/connector-hermes`), and a deliberately-removed connector STAYS removed\nacross upgrades. `cotal ext add <your-package>` adds a third-party connector the same way. The web\ndashboard (`@cotal-ai/web`, providing `command:web`) is the seventh built-in seeded on the same path.\n\n`cotal ext seed` is the maintenance entry for that seeding (it runs automatically on the first real\ncommand of each boot, so you rarely call it). Each seeded connector's `\u2713 added` line goes to stderr,\nso the command that triggered the seed keeps stdout to itself:\n\n| Flag | Meaning |\n|---|---|\n| (none) | Reconcile: seed any never-seeded built-in, refresh a seeded one whose version the binary bumped, leave a removed one removed. A no-op once current. |\n| `--repair` | Recover after an interrupted seed or a lost authority (rebuilds the interrupted connector; restores the removed-vs-never-seeded record from its durable backup). |\n| `--reset` | Discard the record and re-seed all seven built-ins (the six connectors plus the web dashboard). **Resurrects any you removed.** Rebuilds cleanly over corrupt seed state. |\n| `--force` | Re-seed the built-ins even when the version stamp is current or a downgrade. |\n\nWhen a newer `cotal` advances the operator-global seed store to its generation, it prints one\nmigration line naming the old and new generations, the exact CLI entry that wrote the store, the\ncommit timestamp, and `seed/stamp.json`. That writer and timestamp are kept in the stamp, so a later\nolder CLI refusal can say which executable wrote the generation it will not overwrite and when.\nLegacy generation-only stamps remain readable; their refusal simply has no writer provenance to add.\n\nAn older `cotal` refuses a seed store written by a newer version. When it can verify a sufficient\n`cotal` executable on PATH or at the installer's `~/.local/bin/cotal` location, the refusal names\nthat absolute path so a reduced service PATH does not select the older binary again. Otherwise it\nkeeps the generic newer-version instruction. `--force` rebuilds the store for the running older\nversion without discarding the ever-seeded authority. `--reset` still exists for corrupt state and\nresurrects deliberately-removed connectors.\n\nA source-checkout CLI (`pnpm cotal`, `tsx bin/cotal.ts`, `node bin/cotal.ts`, or a suite child of\nthose) refuses to write or garbage-collect that store. The refusal names the path, the generation\nit declined, and `$XDG_CONFIG_HOME` as the isolation remedy. `COTAL_HOME` does not relocate this\nstore. An entry that cannot be proven as a released install is refused the same way. Isolated\nrelease tests that must seed from a checkout-shaped `bin/` set `COTAL_ALLOW_CHECKOUT_SEED=1` after\npointing `$XDG_CONFIG_HOME` at a scratch dir; that override is documented here, not on the refusal\nline. An opt-in write still records the checkout path in `seed/stamp.json` as `writtenBy`.\n\nThe default connector for a bare `cotal spawn` (no `--agent`) is the persona's `agent:` pin if it\nhas one, else `claude`; set `COTAL_DEFAULT_AGENT` (e.g. `opencode`) to change the fallback. It is\na default, so a persona that pins its harness still wins over it. An `--agent` naming a removed\nconnector fails loud with the exact\n`cotal ext add` to restore it. Set `COTAL_SKIP_CONNECTOR_SEED=1` to turn off the automatic first-run\nseed/refresh entirely (for a controlled or offline setup that manages connectors by hand); `cotal ext\nseed` still runs on request. `cotal agent-bearer` never takes the seed at all: it is exec'd by\nspawned seats on every bearer refresh, so it neither reconciles nor is refused by the store's\ngeneration (see [Plumbing](#plumbing)).\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | none | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | none | Longer free-form details |\n| `--severity <s>` | none | `low` \\| `medium` \\| `high` |\n| `--area <a>` | none | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | none | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## run\n\nOperate durable workflow runs (cotal-lang programs) from the terminal.\n\n```bash\ncotal run start --file <program> [--timeout <dur>] [--local]\ncotal run resume <runId> [--local --file <program>]\ncotal run ps [--endpoint <ep>] [--json]\ncotal run journal <runId> [--endpoint <ep>] [--json]\ncotal run answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>]\ncotal run amend <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>]\ncotal run migrate <runId> --local --file <program> [--endpoint <ep>]\n```\n\n`start` hands the program to the mesh's manager, which validates it, mints the run id (the record\nnever takes a caller-supplied one), drives it in its own process, and answers with the id once the\nrun is recorded; a program that does not validate is refused with every problem listed. `resume`\nasks the manager to take an existing run back and continue it from its step journal; the source is\nthe recorded program, so no `--file` is taken. Neither takes `--endpoint`: the manager records\nits runs under its own endpoint, and naming another is refused. `ps` lists the run records and\n`journal` renders one run's durable records; both only inspect. An open pause prints its question.\nA pause settled with an accepted answer prints its value as JSON plus the recorded answerer,\nartifact when present, time, and answer id, then one `amended` line per later amendment, in the\norder the store committed them, so the last is the current position.\nExpired pauses and ordinary steps print no answer line.\n`--json` on `ps` or `journal` prints each row the manager answers with (or `--local` reads) as one\nJSON object per line. A `ps` row carries `runId`, `endpoint`, `state`, `holder`, `epoch`,\n`journalHigh`, `forkedFrom`, `startedAt` and `programHash` (the values the program's `run()`\nreports; `programHash` is absent for a run with no recorded program), and `revoked` or\n`revocationUnreadable` when the marker says so. A `journal` row is an `activation` or a `step`. A\nstep row carries its `step` key, the `effect` kind and its `name`, `state`, `outcome`, the recorded\n`status` and `errorCode` once settled, and `startedAt` and `endedAt` in epoch milliseconds. An open\npause adds its `asks`, its `deadlineAt`, and for a checkpoint the `onExpiry` it was armed with; a\nsettled pause adds its `answer` and its `amendments`, as the text view prints them. A field the\njournal does not record is absent: a checkpoint opened before `onExpiry` was recorded carries none.\nThe run header and errors go to stderr, so stdout carries only rows; an unreadable revocation marker\nprints its reason there and still exits 1. The text view is presentation and is not a stable\nparsing target. `--json` on any other verb is refused.\n`answer` resolves an open\ncheckpoint through the manager, presenting as the holder that armed it; the manager records the\nanswerer from your credential, so no `--by` is taken there. A settled step refuses a second\n`answer`. `amend` records a changed position on a settled checkpoint or `ask`: it files a new\nanswer beside the accepted one, naming it, and the journal lists it under the step. The pause stays\nsettled and the run keeps the answer it acted on. A step that is still open or settled without an\nanswer refuses an amend. A spawned seat may amend only an answer recorded under its own name. `migrate` runs the migrate check of an\nedited program against a run's journal, from this terminal under a read credential (`--local`\nonly; the manager serves no run-migrate command): it prints whether the migration is admissible,\nevery orphaned step with its verdict and code, and exits 0 on admissible and non-zero on not. It\nwrites nothing: the commit that would file the migration is not reachable yet, and the report\nsays so. `--timeout` sets the default\ncheckpoint timeout for a drive (default 1h). `--local` drives in this process instead, over one\nconnection per invocation under the run's own credential minted from the project folder's trust\nmaterial, and is the path on a bare broker with no manager or for a run with no recorded program\n(`cotal run resume <runId> --local --file <program>`); `answer --local` and `amend --local` take\n`--by <who>`. On a\nuser-auth mesh the host's own manager refuses the family by name, and `--local` has no credential\nthere. A participant's manager started with `cotal supervise` hosts a logged-in user's runs through\nits issuing host: the auth callout issues the user's manager connection, and every `run` verb rides\nthe versioned rail under that issuance.\n[User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path. The guide is [workflows](workflows.md).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>] [--root <dir>]\ncotal auth-service --space <s> --server <url> [--port <n>] [--exchange-public-port <n>] [--exchange-public-url <https://\u2026>] [--exchange-trusted-proxy]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane: the NATS auth callout, the\ncapability-gated local exchange and JWKS, and, when `--exchange-public-port` is set, the closed public\nexchange/discovery face forwarded by an HTTPS reverse proxy. `--exchange-public-url` is the proxy URL\nadvertised to clients; `--exchange-trusted-proxy` opts into last-hop `X-Forwarded-For` attribution.\n`cotal up --user-auth` starts and supervises the service for you, so you run it directly only to\nrecover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. `--creds` can start a\ndaemon that already looks healthy, but production renewal is not that file alone: the manager and\nthe daemon must address one credential store. On a stock split host with two project roots, a\ndirect `deliver` is not an independent repair; keep the daemon under `cotal up` on the broker\nhost, or inject the same store into both processes ([embedding](embedding.md#supervisor-signing-authority)).\nTyped by hand on the workstation, `deliver` dials the broker recorded for `--space` in the mesh\nregistry (a mismatching `--server` is refused before any dial, and a record for a different\nworkspace root is refused outright); with no record for the space it falls back to the local mesh.\nThe daemon serves the workspace root that `--root <dir>` names, which must hold `.cotal/`, or else\nthe nearest `.cotal/` above its working directory. With neither, it refuses at start and names the\ndirectory it searched from, before it reads a credential or dials a broker.\nSee the [delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. Its local arm uses `--dir` to discover the\ncapability-gated loopback service. A remotely enrolled, already-granted agent instead receives\n`--exchange-url <https://base>` in its launch argv: that arm sends `{owner, actor, actorToken}` to the\npinned public exchange with no local capability, follows no redirects, and refuses every non-HTTPS\nURL because the actor token is the credential in the request body. Because a seat execs it on every\nbearer refresh, it skips the connector-seed boot gate entirely: it reads one 0600 token file,\nexchanges it and prints the bearer without consulting or writing the operator-global seed store, so\na newer store generation cannot refuse a live seat's refresh. `--manager-call` asks for the\ninstance-bound `manager-caller` view; `--manager-instance <id>` selects an explicit live candidate.\nThat mode still prints only the raw token and does not update `--health-file`. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
     },
     {
       "slug": "config",
@@ -19608,7 +19622,7 @@ var DOCS_BUNDLE = {
       "title": "Connect Claude",
       "kind": "Guide (informative)",
       "summary": "The Claude Code connector turns a real claude session into a Cotal mesh peer.",
-      "body": "# Connect Claude\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nThe Claude Code connector turns a real `claude` session into a Cotal mesh peer. A bundled\nplugin inside the session joins NATS, maps lifecycle hooks to presence, and exposes the\nmesh tools. Nothing wraps Claude; it is an ordinary session that happens to be on the\nmesh.\n\nThe shared mesh runtime (agent, `cotal_*` tools, hook relay) lives in\n[`@cotal-ai/connector-core`](../extensions/connector-core); this connector is the thin\nClaude-specific adapter over it. Siblings: [OpenCode](connect-opencode.md) (beta),\n[Hermes](connect-hermes.md) (alpha), [pi](connect-pi.md) (alpha); the\n[Connectors](connectors.md) matrix compares them feature-by-feature.\n\n## Set up\n\n```bash\ncotal setup      # one-time: installs the plugin, seeds one agent; launches nothing\ncotal up         # brings up the mesh + delivery daemon + a detached manager\n```\n\n`cotal setup` installs the cotal plugin (so the repo's Claude sessions get the `cotal_*`\ntools), shares your own MCP servers with spawned sessions on its first run (see\n[Sharing your MCP servers](#sharing-your-mcp-servers)), and seeds one `default` persona; `cotal up` brings up the local stack so\n`cotal spawn --detach` / `cotal_spawn` work right away. Re-running either is idempotent.\nThe install mechanics and the invariants behind them are in\n[setup internals](setup-internals.md).\n\n`cotal setup` also installs Cotal's authored Agent Skills (`SKILL.md`, the agentskills.io format) for\ncoordinating agent teams (today `team-topology`), from one canonical source, on two channels:\n\n- **Claude Code** gets a second, skills-only plugin, `cotal-skills`, from the same `cotal-mesh`\n  marketplace, at **user scope** (machine-wide). The Claude connector declares and implements this\n  setup provider, including the marketplace assets and native plugin commands; the base CLI only passes\n  the vendor-neutral Agent Skills directory. The plugin carries no code and no core dependency,\n  and uninstalls on its own with `claude plugin uninstall cotal-skills --scope user`. Its plugin version\n  is stamped from the running CLI release, so an upgrade + `cotal setup --skills` runs `claude plugin update` and\n  the deployed install actually gets the new skill. `cotal setup` installs it on first run and on repeat\n  runs, so upgraders are not left behind. The same provider reports the plugin and skills plugin rows\n  in `cotal status`, which point a stale or missing skills plugin at `cotal setup --skills`.\n- **Every other harness** (Codex, Cursor, OpenCode, Gemini CLI, Windsurf/Devin) reads the cross-vendor\n  `~/.agents/skills/` directory convention, which has no remote index, so `cotal setup` **reconciles** it\n  (and `cotal setup --skills` does only that):\n  it installs/updates each Cotal skill, backs up a copy you have edited to `SKILL.md.bak` before\n  replacing it, and removes a Cotal skill that is no longer shipped. Only skills Cotal owns are touched;\n  your own or third-party skills there are left alone. `cotal status` reports whether the drop is current,\n  stale, missing, or has a retired skill to reconcile, and names `cotal setup --skills` as the remedy. This is the working cross-vendor path.\n\nCotal also generates an [Agent Skills discovery index](https://cotal.ai/.well-known/agent-skills/index.json)\non cotal.ai, but that RFC is still a draft with no harness consuming it yet, so it is a forward bet,\nnot a channel to rely on today.\n\n## Spawn a session\n\n```bash\ncotal spawn                 # foreground: your default agent, in this terminal\ncotal spawn dave --detach   # supervised: the manager runs it in a PTY\n```\n\nA spawn resolves a persona from `.cotal/agents/<name>.md` ([agent files](agent-files.md));\n`--model`, `--variant`, `--cwd`, `--prompt`, ACL overrides, and `--share-tools` apply to\nboth forms ([run a mesh](run-a-mesh.md) has the full resolution rules). The session joins\nwith identity from its environment and auto-registers presence by the time it is\ninteractive.\n\nInside the session, the agent orients with one read-only tool, `cotal_orientation`: its\nidentity, the channels it reads and may post to, its capabilities, the tools available,\nwho's present, and unread counts. The full tool surface is the\n[MCP tool catalog](mcp-tools.md). In auth mode the team-supervision tools\n(`cotal_spawn` / `cotal_persona` / `cotal_personas`) are injected **only** for personas declaring\n`capabilities: [spawn]` (the same grant that opens the privileged control subject), so an\nagent's toolset matches its declared capabilities. `cotal_run` is gated separately by\n`run`; use `capabilities: [spawn, run]` for both. Fresh setup defaults include both.\nSee [workflow tool setup](workflows.md#from-an-agent-session) for a first run and missing-tool checks.\nClearing retained history is\noperator-only ([run a mesh](run-a-mesh.md)), never an agent tool.\n\n## How it binds\n\nClaude Code exposes four integration surfaces, and three of them collapse into a single\ndual-purpose MCP server:\n\n| Surface | Mechanism |\n|---|---|\n| Outbound, ambient | `http` lifecycle hooks \u2192 POST to the connector (presence, activity) |\n| Outbound, deliberate | MCP tools `cotal_send` / `cotal_dm` / `cotal_anycast` (+ `cotal_feedback`) |\n| Inbound, pull | MCP tool `cotal_inbox` (same server) |\n| Inbound, push | Channel nudge + hook drain (below) |\n\nThe manager launches the *real* `claude` (no wrapper):\n\n```\nclaude --strict-mcp-config --mcp-config '{\"mcpServers\":{\"cotal\":{\u2026}}}' \\\n       --dangerously-load-development-channels server:cotal\n# env: COTAL_SPACE, COTAL_NAME, COTAL_ROLE, COTAL_CHANNEL=1, plus claude's documented auth vars\n```\n\n- **Model auth.** Locally, `claude` still reads macOS Keychain / `~/.claude`. In a container or\n  CI there is no Keychain, so the connector forwards the documented credential set:\n  `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`), `ANTHROPIC_API_KEY` /\n  `ANTHROPIC_AUTH_TOKEN`, and the cloud-provider flags plus their credential vars. Host-session\n  markers (`CLAUDE_CODE_CHILD_SESSION`, `CLAUDECODE`) stay out so a nested seat still saves a\n  transcript. See [Deploy](deploy.md).\n- **Persona privacy.** The persona body is written to a private file and Claude receives only\n  `--append-system-prompt-file <path>`. The body never appears in the spawned process argv. The\n  carrier is a 0600 file inside a 0700 directory on POSIX, with equivalent owner-only ACL hardening\n  on Windows. That is OS-user isolation: any process running as your user can read it while it\n  exists. The manager or the foreground `cotal spawn` removes it, and the shared-server MCP config\n  file, once it has proved the `claude` process gone. If the launcher is killed first, a watcher\n  started beside `claude` removes them when `claude` exits.\n- **MCP servers.** `--strict-mcp-config` ignores every ambient MCP source, so a spawned agent\n  loads the cotal server plus the servers the cotal config shares. First-run `cotal setup`\n  fills that list with your own user-scope servers, so a spawned session has the tools you know\n  (see below).\n- **Installed plugin.** The plugin is installed once (`claude plugin install\n  cotal@cotal-mesh --scope local`) because its hooks bind only to an *installed* plugin.\n  The repo's `.claude-plugin/marketplace.json` lists the committed plugin tree under\n  `claude-plugin/`, which each release regenerates with the built bundles, the skills and the\n  release version, so an install from the repo or from a pinned commit runs without a build\n  ([Release](release.md)). `cotal setup` (npx, no clone) materializes the same marketplace under\n  `~/.cotal/claude-plugin/` from the installed CLI (each plugin dir is rebuilt from scratch and\n  atomically replaced, never merged, so no stale file rides in). The\n  `cotal-skills` plugin installs from that same marketplace at user scope (`claude plugin install\n  cotal-skills@cotal-mesh --scope user`); its manifest and install behavior ship inside the Claude connector, and\n  its version tracks the CLI release so updates land.\n- **Identity-gated.** Connector code requires `COTAL_NAME`, `COTAL_LINK` or `COTAL_AGENT_FILE`.\n  A plain `claude` with none of them never joins, so your own sessions in a repo do not appear\n  as stray peers. Its MCP server still answers `initialize` and lists one static tool,\n  `cotal_how_to_join`, which explains how to launch a session on a mesh. It builds no mesh\n  agent, opens no broker connection and binds no control socket.\n- **Hands-free.** The dev-channels flag prints a one-time confirm prompt. The PTY runtime waits for\n  the dialog title in normalized terminal output and presses Enter once when it appears, so startup\n  speed does not affect a supervised launch. If the declared prompt never appears, the seat exits\n  with a bounded error naming the unmatched prompt instead of hanging silently.\n\nInbound mesh messages arrive in context as\n`<channel source=\"cotal\" from=\"bob\" kind=\"dm\" \u2026>\u2026</channel>`: each meta key a tag\nattribute the agent can read for routing.\n\n## How messages reach the session\n\nDurable deliveries land in the connector's inbox from JetStream consumers\n([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)); live channel traffic can instead arrive\nthrough an at-most-once core subscription. A durable message sent while the agent is busy\nor offline waits on the stream. Two things move a message from inbox to model; one\ndelivers, the other only wakes:\n\n- **Hook drain (delivery).** `SessionStart` / `UserPromptSubmit` hooks read automatic inbox items and\n  inject them as `additionalContext`. This is the single authoritative path: deterministic and works\n  on any Claude Code build. Quiet ambient is excluded and stays buffered for `cotal_inbox`.\n  A message is **acked only once the hook reply carrying it has cleared both legs of its journey**:\n  the connector's control socket to the hook process (which gives up after 2s), and the hook\n  process's own stdout to Claude Code (which it force-exits 1s after starting to write). The relay\n  sends a receipt back down the control socket from that stdout write's callback, and only on a\n  clean write (a runtime whose pipe has gone away fails it), and the connector treats that receipt,\n  not its own socket write, as delivery. So a large injection killed mid-flush, or one written to a\n  broken pipe, leaves the message un-acked and JetStream redelivers it. What this does *not* prove is\n  that Claude Code read or applied the reply: a payload small enough to fit the pipe buffer is\n  reported written the moment the kernel takes it. That residual is why the path errs toward\n  at-least-once rather than treating a confirmed write as a confirmed read. Acking when\n  the reply was merely *formatted* meant a lost reply was a lost message: it was already marked\n  handled, so its own redelivery was silently acked on arrival.\n  A hook whose handler throws still returns an empty reply so the session is never blocked, and\n  that reply carries nothing, so it commits nothing: the batch it had started to surface stays\n  un-acked and goes out on a later frame. The seat also drops any `turn-pending` row that breaks\n  the manager contract, such as one with no integer deadline, and says so once in its log. A reply\n  with no `turns` array changes nothing: the seat keeps the turns it already holds.\n  This errs toward **at-least-once**: if a reply lands but its confirmation does not, the batch is\n  surfaced again and flagged as a possible repeat. A duplicate injection is noise; a buried DM stops\n  the peer answering at all.\n- **Channel nudge (wake).** An arriving message fires a `notifications/claude/channel`\n  event that wakes an *idle* session into a turn, so the drain runs *now* instead of at\n  the next prompt. The nudge never acks anything. A nudge that the host rejects is retried with a\n  bounded backoff while anything is still pending. For an idle session it is the only wake source,\n  so dropping it means silence until someone types. When the channel becomes active, the connector\n  first re-fires a focus mention remembered during startup, otherwise one buffered wake. A rejected\n  push keeps its bounded retry, and JetStream redelivery remains the durable backstop for unacked\n  inbox items. If the channel cannot run at all, delivery still waits for the next hook. Live-only\n  traffic has no durable retry.\n\n**Two priority tiers.** A *directed* message (DM, anycast, or a channel message that\n`@mentions` us) always nudges. *Ambient* channel chatter does not nudge mid-turn; it\naccumulates, and the `Stop` \u2192 idle transition fires one batch nudge so the backlog drains\ntogether.\n\n**Constraints (accepted).** Channels are a Claude Code research preview (\u2265 v2.1.80;\npermission relay \u2265 v2.1.81): Anthropic auth only, admin-enabled on Team/Enterprise, and a\ncustom channel needs the `--dangerously-load-development-channels` launch flag. The hook\ndrain does not depend on any of that; the channel only adds \"wake me when idle.\"\n\nThe same channel also relays **tool-permission requests** onto the mesh, so a peer (a\nhuman at the CLI, a policy node) can approve or deny an agent's pending tool call through\nCotal rather than a per-terminal prompt.\n\n### Attention\n\nAn agent picks how aggressively peer traffic reaches it with\n`cotal_status({ attention })` (three modes, orthogonal to presence):\n\n| arrival | open (default) | dnd | focus |\n|---|---|---|---|\n| directed (dm / anycast) | wake + inject | wake + inject | wake + inject |\n| channel `@mention` | wake + inject | wake + inject | ack-drop; wake to *pull*; not injected |\n| ambient channel chatter | wake when idle; hold while working | never wakes; injects next turn | ack-drop; recall via `cotal_inbox` |\n\nPer-channel overrides refine this: **quiet** (delivered, never wakes; `@mention` still\nwakes) and **muted** (dropped on receive, mentions included; DMs/anycast unaffected), set\nwith `cotal_channel_mode` or as agent-file defaults (`quiet:` / `muted:`,\n[agent files](agent-files.md)). A per-channel override is the final word for that channel.\nQuiet ambient is pull-only: it never hitchhikes on a human prompt, DM, mention, or other\nconnector-driven turn. `cotal_inbox` explicitly surfaces and clears it. A quiet-channel\n`@mention` remains automatic and injects normally.\n\nA pull is bounded too, and clears only what it hands over. One `cotal_inbox` call carries at most a\nreceivable window (direct messages and role requests first, then channel traffic, replayed history\nlast); whatever does not fit stays buffered, is named in the reply, and comes back on the next call.\nA message too large for one whole response is delivered in parts: once no smaller mail is waiting,\neach call carries its next part, and it is cleared only after its last part goes out, because clearing\nwhat was not handed over is the loss this bound exists to stop.\nThat matters most on the path where it is easiest to lose mail: reconnecting brings a channel-history\nreplay with it, so the largest payload and the least expendable message arrive in the same read.\n\nThe local inbox is bounded. On pathological overflow it evicts pull-only items first, then other\nchannel traffic, and a direct message or role request only when the whole buffer is directed mail.\nAn evicted channel item is acknowledged. An evicted direct message or role request never is, and\nthe broker redelivers it after the ack wait until a redelivery finds room. A direct message stays\npending on the session's DM durable, where `cotal deliver pending <name>` counts it. A role request\nstays on its role's shared queue, which that command does not read. A full inbox therefore delays\ndirected mail until the session drains it.\nIf the bounded live/durable classification guard also fills, the connector fails closed:\notherwise-normal ambient becomes pull-only until restart. Muted hard-drop and normal focus recall\nstill take precedence. Focus also keeps a bounded exclusion list so mode toggles cannot recall\nquiet/muted traffic; if that safety bound fills, recall skips the affected channel and reports it\nas incomplete rather than risk resurfacing excluded content. Recall cannot tell one message with an\nempty id from an identical one with another disposition, so in focus such a message is held in the\nlocal inbox as pull-only instead of being dropped, and a mention of it still wakes the agent. When\nthe session settles an id-less copy, it reads the chat stream's last sequence. Identical copies\narrive in stream order, and those reads can answer out of order, so the first read that can see the\ncopies binds them in arrival order, latest first, each to the latest unbound stream copy at or below\nthe lowest sequence read for it or any later identical copy.\nWhile the connection stays up, every stream copy at or below that sequence reached the session\nfirst, so a later identical copy sent during a reconnect gap is above it and stays unbound. A copy\nthat arrives while a read runs may not be in that read, so it binds nothing there and recall reads\nthe channel again, up to three times; if it still could be a stream copy in the last read, recall\nleaves that stream copy in the stream and reports the channel as incomplete. A settled copy a\ncomplete read cannot bind is behind the focus start or out of retention, and is forgotten. Recall\nhands back into the inbox only the stream copies nothing is bound to, such as one sent during a\nreconnect gap or one the inbox evicted on overflow, and `cotal_inbox` hands each over once. Overflow\nfrees only the evicted copy, held or quiet, and a copy no read has bound yet keeps its place in\narrival order, so an identical muted copy stays out of recall. When\nthe inbox is full, recall leaves them in the stream for a later call and reports the channel as\nincomplete. A history read that fails, or a channel with replay off, settles nothing and is reported\nas incomplete, and recall calls run one at a time. If the sequence read for a settled copy fails,\nor answers only after the connection dropped, recall skips that channel for the rest of the focus\nperiod and reports it as incomplete. Recall cannot tell a late copy of a message it handed back from\na new identical message, so every copy takes its own disposition: a new identical quiet mention is\nstill delivered automatically, and a late copy can surface a second time.\nA recalled message that already went out in part is read to its last part, even if an exclusion\nlands after its first part. One session reads its inbox one call at a time: a `cotal_inbox` call\nthat overlaps another waits for it to finish, so neither decides from a view the other has already\nmoved past.\nIf the separate hard-drop disposition guard fills, channel traffic is dropped for the rest of the\nsession rather than risk a late copy bypassing an earlier muted/focus decision; DMs and anycast are\nunaffected.\n\nAttention is **advisory UX, not a boundary**: any peer can wake a dnd/focus agent by\nnaming it, and `muted` means \"I opted out of receiving\", not \"the channel is blocked\";\nthe broker still authorizes and delivers. Focus's real effect is shrinking the\nuntrusted-ambient injection surface (only subject-authenticated dm/anycast auto-inject).\nIt resets to **open** on `SessionStart`, so a restarted agent never stays silently deaf.\nYour attention is mirrored into presence so peers can see it.\n\nWhatever does reach a turn is framed so a peer cannot write the frame. A line that begins at column\nzero is written by the connector; one message is one line plus indented continuations, with the\nsender inside a single bracket pair. A message body, a sender name and role, and a service or\nchannel label are all peer-controlled, so each passes through the same neutralization the\n`cotal_inbox` reply uses: no line break a splitter may honour and no bracket survives into a\nrendered attribution. This matters more for an injected block than for a reply, because the agent\ndid not ask for it and so never had the chance to distrust it.\n\n## Presence mapping\n\nThe connector wires a small subset of Claude Code hooks to presence states; presence is\ncoarse, and \"what it is doing\" rides on activity updates. Presence is **advisory**: a presence\npublish that fails (the endpoint mid-reconnect, say) is swallowed and never prevents the same hook\nfrom delivering messages or flushing held ones.\nA `SessionStart` during an open turn, including compaction, preserves the current `working` or\n`waiting` status until `Stop`, `StopFailure`, or `SessionEnd` closes the turn.\n\n| Hook | \u2192 state |\n|---|---|\n| `SessionStart` | `idle` only when no turn is open (join; surfaces the inbox; captures the live model into `meta.model` when no pin) |\n| `UserPromptSubmit` | `working` (turn starts; surfaces the inbox) |\n| `PreToolUse` | no change; records *what* is about to run, so a permission wait can name it |\n| `Notification` (`permission_prompt` / `agent_needs_input`) | `waiting` with condition `approval` / `input` (activity leads with the pending tool, e.g. `Bash: git push \u2026`) |\n| `Stop` / `StopFailure` | `idle` (turn done / died on an API error; flushes anything held while busy). `StopFailure` also relays Claude Code's native error value as `condition.source` and maps it to the closed condition vocabulary. On the [event plane](#event-plane) it closes the run with `RUN_ERROR`. |\n| `SessionEnd` | `offline` (graceful leave) |\n\n`StopFailure` maps `rate_limit` and `overloaded` directly; auth and credential failures to\n`auth`; account and billing failures to `billing`; `invalid_request` to `request`;\n`model_not_found` to `model`; `server_error` to `server`; `max_output_tokens` to `context`; and\n`unknown` to `failed`. The native value remains in `condition.source`.\n\nHooks are relayed over the connector's **authenticated** local control endpoint (per-user\nsocket + per-launch token, constant-time checked), so a local process that finds the path\nstill can't drive presence or stop the agent. The full Claude Code hook-event list lives\nwith the adapter:\n[`extensions/connector-claude-code`](../extensions/connector-claude-code/README.md).\n\n## Event plane\n\nA spawned session publishes a **structured** account of what it\ndid: run boundaries per turn, assistant text, reasoning, and each tool call with its start\nand its end. Not prose about the work, the work itself, in a vocabulary a program can\nread. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an unrestricted\nspace. A user-auth registration with `policy: { events: \"required\" }` carries `eventsRequired` in the\nprivate launch material, so the connector arms even without `COTAL_EVENTS`; `--no-events` is refused.\nA hand-driven user-mode session may carry the same decision as `COTAL_EVENTS_REQUIRED=1`. Its own\npublish grant must cover `events.<owner>.<actor>` or the connector refuses before joining. An unmanaged\nsession with no launch material and no required-policy fallback keeps the generic default behavior.\n\nA new session includes its first run even when Claude writes a positional startup prompt before the\nconnector receives `SessionStart`. That from-zero read is keyed only to Claude's explicit\n`source: \"startup\"`; resumed, forked, cleared, and compacted sessions adopt at the transcript boundary\ncaptured at that adopt, before the mesh link connects, so nothing Claude appends while the connector\nis still starting up lands behind the cursor and is silently dropped. Crash recovery follows the\ncursor already stored in the event write-ahead log, regardless of the new process's startup label.\n\nClaude starts each hook in its own process, so a prompt or stop relay can reach Cotal before the\n`SessionStart` relay. The connector holds those event flushes and the terminal until `SessionStart`\nsupplies the source, then enqueues adopt, flush, and close in that order.\n\n`SessionStart` can also run before the connector process has bound its local control socket. The hook\nthe `SessionStart` relay retries only transient pre-connect listener errors, with capped backoff\ninside its existing two-second budget. Later hooks and permanent local faults still fail open\nimmediately. Once a socket has connected, a broken exchange is not retried: the connector may\nalready have handled the frame, so replaying it could apply one lifecycle event twice.\nThat retained `SessionStart` can itself arrive before Claude creates the transcript path. A genuinely\nnew startup waits up to five seconds for that file with capped backoff, and the same deadline bounds\none stalled file read; expiry fails loud instead of silently losing the first run. A forked session\ngets the same wait, because Claude copies the parent transcript into the fork's own file after the\nhook, and then adopts at the end of that copy. Resumed, cleared and compacted starts and recovered\ncursors still require their existing source at once.\n\nTool arguments (`TOOL_CALL_ARGS`) and tool results (`TOOL_CALL_RESULT`) are not republished\nonto this channel. The durable emitter drops those events before they are written to the\nwrite-ahead log, because this channel's read ACL is not the ACL the tool ran under. Content is\nmandatory on both kinds, so the event is suppressed rather than emptied or replaced with a\nplaceholder. Tool start and end still go out. A restart that finds a pending pre-fix frame\nstill carrying those kinds HALTS rather than republishing it.\n\nThe channel is **`events.<owner>.<actor>`**, named after the session's principal. What the actor\nhalf is depends on the mesh, and the difference matters when you go looking for it: on a static mesh\nit is a key the manager allocated, never the display name, so two live agents sharing a display name\ndo not share a stream; on a user-auth mesh it is the agent's own name, because that is what the\nledger row is keyed on. Spelled out again with both halves below. The launch grants publish rights\non that channel alone. A spawn\nthat asks for a *different* agent's event channel is refused at the door rather than granted, since\nthat channel is that session's event stream. The same rule runs on restart: a manager\nresume document that names another agent's event channel is refused rather than adopted, because the\nmanaged row is re-armed from that document and the credential is re-minted from the row.\n\nThe rule reads a **concrete** channel, two principal tokens and nothing else. A pattern such as\n`events.<owner>.>` is not an event channel to it and passes untouched, governed by ordinary ACL\nauthority: on a user mesh the delegation envelope, on a static mesh the spawning credential itself.\nThat is deliberate, because the pattern is the form an operator writes on purpose for an observer,\nand it is worth knowing rather than assuming the fence is total.\n\nTo let something else read a plane, grant it out of band. The refusal prints the command for the\nmesh it is running on, spelled out in full, and only that one.\n\nOn a **user-auth** mesh:\n\n```bash\ncotal actor grant <reader> --owner <owner> --scope '' --allow-subscribe 'events.<owner>.<actor>' --allow-publish ''\n```\n\nEvery field, deliberately. `actor grant` is an upsert of the whole row, so it refuses a grant that\nleaves off any of the three ACL flags. Only `--full` turns an omitted flag into the wide default\n(`>` read, `>` post, `spawn,role:default` scope), which is the opposite of what a scoped watcher is for.\n\nOn a **static** mesh there is no actor ledger for `actor grant` to write to, and the refusal says\nso; mint the reader instead:\n\n```bash\ncotal mint watcher --profile agent --allow-subscribe 'events.<owner>.<actor>' --provision\n```\n\nThe **agent** profile, not the observer one. `mint` reads `--allow-subscribe` only for that\nprofile, and refuses it anywhere else: `--profile observer --allow-subscribe <channel>` exits\nnon-zero and writes no creds file, because the observer profile carries a fixed read set over the\nwhole chat plane, which is the opposite of what a scoped watcher is for. The agent profile also prints the lifecycle uid the\nreader needs, since an authed consuming endpoint refuses to start without one.\n\nOn an **open** mesh there is nothing to grant: the mesh has no credentials and no ACLs, so any peer\nthat lists the channel reads it, and the refusal says so instead of naming a command. The\nown-channel rule still applies there, because a spawn is not the place to hand out a read on\nanother agent's tool inputs and outputs.\n\nTwo things a reader has to do that are not obvious, both on `CotalEndpoint`. It must pass the event\nchannel in `channels`: an endpoint reads the channels it lists, so one constructed without\nthe event channel joins nothing and the frames never arrive. And it reads history with `readHistory(channel)`, the delivery daemon's mediated read, not\n`channelHistory(channel)`: a scoped credential is denied the ad-hoc consumer the direct read\ncreates, by design. `cotal console` and the web console already do both.\n\nThe `<owner>.<actor>` pair is the session's principal. On a user-auth mesh the actor half is the\nagent's own name, so the channel is `events.<your-owner>.<agent-name>`. On a\nstatic mesh the owner half is the literal `local` and the actor is a key the manager allocated, so\nthe channel is `events.local.<key>`; the spawn reply carries that key as `id`. Note\nthat `cotal console` and the web console keep event channels out of their channel lists on purpose,\nsince a plane is a machine feed rather than a conversation; they draw the frames when you open the\nchannel by name.\n\nThe rule governs the manager's doors, which are the ones a caller other than you can reach. A\nforeground `cotal spawn` on your own machine mints from your own signing material, so it can still\ngrant any channel you name: that is the out-of-band grant, not a way around the rule.\n\n**Failed turns publish run errors.** Claude Code decides for itself\nwhether a turn finished or died and fires one of two hooks accordingly, so the connector relays that\ndecision rather than making one of its own: a turn that ended on an API error ends its run with\n`RUN_ERROR` carrying the fixed message `run failed` and no code. Neither the detail Claude Code\nreported nor its error kind is published there: both are upstream values that can echo your prompt or\ntool output, and the events channel has a different read ACL. The error kind still reaches presence\nas the agent's condition (`rate_limit`, `auth`, `billing` and the rest). A turn that ended normally still\nends with a run-finished event carrying no outcome, which says the turn ended and does not claim it\nsucceeded.\n\nEvents are written to a per-session write-ahead log before they are published, so a hook that fires\nafter a restart resumes at the cursor it left rather than replaying or skipping, and a run that was\nopen when the session stopped is closed rather than left dangling.\n\nOne channel carries **every session of one agent**, because it is named after the principal and not\nafter the session. Alongside the per-session logs the connector keeps one small record per principal,\nholding the last sequence the broker assigned on that channel, so a new session continues the stream\nits predecessor left instead of starting again from nothing. Both live under the events state root\n(`COTAL_WORKSPACE_ROOT`), and neither is something you edit by hand.\n\nA **missing** record is not a fault: the connector rebuilds it from the session logs beside it,\nwhich is how an agent that was already running before this record existed keeps its stream. That\nrebuild stops if any one of those session logs is damaged. Unreadable, not valid JSON, and written\nfor a different principal all count, and so does a session directory or a log that is a link rather\nthan the real file the connector wrote, or a log that has more than one name. A tip taken from the\nrest would be too low, and it would stop publication later with nothing left to point at the cause.\nThe connector names the file instead, and the only way past it is the directory removal described\nbelow, under the same condition. A record that **disagrees with the broker** is a fault, and the\nconnector stops publishing and says why rather than guessing. A record that **moved while a session\nwas writing to it** is refused the same way: it means something else wrote the principal's record,\nand the connector reports which value it held and which the file holds rather than writing over the\nlater one. There is no command to clear it. The state is the principal's directory under the events\nroot, and clearing it by hand means removing that directory whole: the sequence, the cursor and the\nper-session logs only mean anything together, so removing part of it leaves a state the next start\nrefuses. Removing it is only half a remedy, and the half that comes first is the channel. The\ndirectory is where the agent's memory of the tip lives, not the tip itself, so on a channel that\nstill holds frames the next session opens expecting an empty one and stops on the same\ndisagreement, with the logs a tip could have been rebuilt from now gone. Purge the channel first,\nthen remove the directory.\n\nReading it: `cotal console` and the web console draw event frames directly. A frame carries no text\npart by design, so a surface that renders a message as flat text shows a marker instead of prose.\n\n**On a per-user-auth mesh, the default event plane needs the spawner's grant to cover the channel.** The event\nchannel is added to the child's publish set, and delegation only narrows: an agent may hand down\na subset of what it holds and no more. So a peer-initiated spawn is refused unless the\nspawning identity's own grant already covers the child's event channel. The refusal prints the\nexact `cotal actor grant` command that widens it. An operator launch, whose chain reaches an\nadmin-scoped or roster row, is unaffected. Passing `events: false` is the explicit opt-out.\n\nArming the event plane through a typed spawn request (`manager.spawn` with `events`, including\nthe CLI's `cotal spawn --detach --events`) additionally requires the caller's admin tier on a\nuser mesh. A non-admin caller that asks for the plane is refused before anything is provisioned,\nand one that stays silent gets a spawn without it, with the reply saying so.\n\n## Resume a session\n\n`--resume <session-id>` pulls an existing Claude session, its context and transcript,\ninto the mesh. It **forks**: Claude mints a *new* session id from that transcript\n(`--resume <id> --fork-session`), so the meshed agent gets its own session and the\noriginal is untouched.\n\n- `cotal spawn --resume <id>` (foreground) is the primary surface: the transcript is on\n  *your* machine, and errors are Claude's own stderr, inline.\n- `--detach --resume <id>` works, with two differences: the id resolves against the\n  **manager host's** `~/.claude` (you practically need `--cwd`), and the manager waits for\n  a real outcome; `\u2713 started` means the agent *joined the mesh*, `\u2717 exited on launch`\n  carries Claude's last output, and an uncertain launch (~30 s) is reported without\n  tearing the agent down.\n- Resume is an **operator surface only**, deliberately not exposed on MCP `cotal_spawn`\n  (a mesh peer naming host-local transcripts would widen `spawn` into transcript\n  disclosure). Only the Claude connector supports it today; OpenCode and Hermes fail loud.\n- Needs a `claude` new enough for `--resume \u2026 --fork-session` (verified on 2.1.197).\n\n## Sharing your MCP servers\n\nA spawned session keeps your own MCP servers by default. On its first run, `cotal setup` copies\nthe user-scope servers from your Claude Code config (`~/.claude.json`, or the one under\n`$CLAUDE_CONFIG_DIR`) into the cotal config file (`~/.config/cotal/config.json`) under\n`connectors.claude.mcpServers`, and names them in its output. With none to copy it writes an\nempty list. Each entry is the familiar `.mcp.json` shape ([full format](config.md)). A cotal\nconfig that already declares that list keeps it, and a later `cotal setup` never changes it.\n\nThe cotal config holds secrets only as `${VAR}` references. Setup cannot tell literal text from\na secret, so it leaves out a server with an `env` or `headers` value that is anything but `${VAR}`\nreferences (a `Bearer ${TOKEN}` header among them) and names it in its output. To share one,\nadd it to the cotal config with each secret written as a `${VAR}` reference, and export that\nvariable where you spawn. Setup also leaves out and names an entry no session can start, such as\none with a missing or empty `command` or `url`, or one whose `command` is not a string.\n\nAt launch the connector forwards *only* the named vars the chosen servers declare and\npasses the merged config as an owner-only temp file; `--strict-mcp-config` stays on, so\nonly cotal + the shared servers load.\n\nFor a lighter seat, share fewer. Remove an entry from the cotal config to drop it from every\nspawn, or scope one spawn with `--share-tools tavily,figma` (or `--share-tools none` for cotal\nalone). An empty list (`\"mcpServers\": {}`) in `~/.config/cotal/config.json` keeps every spawn\nisolated, and setup leaves it as it is.\n\nTwo caveats: sharing a server grants its credential to the agent (the var lives in the\nClaude process's environment, so share only when you're fine with that teammate holding\nthe key), and memory adds up, because a heavy server boots once per spawn, multiplied\nacross a team, and can starve a small machine.\n\n## Feedback\n\n`cotal_feedback` works out of the box: without a key it posts to the public intake at\n`https://cotal.ai/v1/feedback` (needs a contact email: `COTAL_FEEDBACK_EMAIL`, then\n`git config user.email`, else the agent asks). Set `COTAL_FEEDBACK_KEY=fbk_<key>` in a\nbeta tester's environment to route to the keyed intake (`Authorization: Bearer`, identity\nderived from the key); `COTAL_FEEDBACK_URL` overrides either endpoint. The CLI can send\ntoo: `cotal feedback \"<summary>\" [--type bug]`. Each submission carries\n`origin: human | agent`, whether the tester asked, or the agent auto-reported a major\nissue.\n"
+      "body": "# Connect Claude\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nThe Claude Code connector turns a real `claude` session into a Cotal mesh peer. A bundled\nplugin inside the session joins NATS, maps lifecycle hooks to presence, and exposes the\nmesh tools. Nothing wraps Claude; it is an ordinary session that happens to be on the\nmesh.\n\nThe shared mesh runtime (agent, `cotal_*` tools, hook relay) lives in\n[`@cotal-ai/connector-core`](../extensions/connector-core); this connector is the thin\nClaude-specific adapter over it. Siblings: [OpenCode](connect-opencode.md) (beta),\n[Hermes](connect-hermes.md) (alpha), [pi](connect-pi.md) (alpha); the\n[Connectors](connectors.md) matrix compares them feature-by-feature.\n\n## Set up\n\n```bash\ncotal setup      # one-time: installs the plugin, seeds one agent; launches nothing\ncotal up         # brings up the mesh + delivery daemon + a detached manager\n```\n\n`cotal setup` installs the cotal plugin (so the repo's Claude sessions get the `cotal_*`\ntools), shares your own MCP servers with spawned sessions on its first run (see\n[Sharing your MCP servers](#sharing-your-mcp-servers)), and seeds one `default` persona; `cotal up` brings up the local stack so\n`cotal spawn --detach` / `cotal_spawn` work right away. Re-running either is idempotent.\nThe install mechanics and the invariants behind them are in\n[setup internals](setup-internals.md).\n\n`cotal setup` also installs Cotal's authored Agent Skills (`SKILL.md`, the agentskills.io format) for\ncoordinating agent teams (today `team-topology`), from one canonical source, on two channels:\n\n- **Claude Code** gets a second, skills-only plugin, `cotal-skills`, from the same `cotal-mesh`\n  marketplace, at **user scope** (machine-wide). The Claude connector declares and implements this\n  setup provider, including the marketplace assets and native plugin commands; the base CLI only passes\n  the vendor-neutral Agent Skills directory. The plugin carries no code and no core dependency,\n  and uninstalls on its own with `claude plugin uninstall cotal-skills --scope user`. Its plugin version\n  is stamped from the running CLI release, so an upgrade + `cotal setup --skills` runs `claude plugin update` and\n  the deployed install actually gets the new skill. `cotal setup` installs it on first run and on repeat\n  runs, so upgraders are not left behind. The same provider reports the plugin and skills plugin rows\n  in `cotal status`, which point a stale or missing skills plugin at `cotal setup --skills`.\n- **Every other harness** (Codex, Cursor, OpenCode, Gemini CLI, Windsurf/Devin) reads the cross-vendor\n  `~/.agents/skills/` directory convention, which has no remote index, so `cotal setup` **reconciles** it\n  (and `cotal setup --skills` does only that):\n  it installs/updates each Cotal skill, backs up a copy you have edited to `SKILL.md.bak` before\n  replacing it, and removes a Cotal skill that is no longer shipped. Only skills Cotal owns are touched;\n  your own or third-party skills there are left alone. `cotal status` reports whether the drop is current,\n  stale, missing, or has a retired skill to reconcile, and names `cotal setup --skills` as the remedy. This is the working cross-vendor path.\n\nCotal also generates an [Agent Skills discovery index](https://cotal.ai/.well-known/agent-skills/index.json)\non cotal.ai, but that RFC is still a draft with no harness consuming it yet, so it is a forward bet,\nnot a channel to rely on today.\n\n## Spawn a session\n\n```bash\ncotal spawn                 # foreground: your default agent, in this terminal\ncotal spawn dave --detach   # supervised: the manager runs it in a PTY\n```\n\nA spawn resolves a persona from `.cotal/agents/<name>.md` ([agent files](agent-files.md));\n`--model`, `--variant`, `--cwd`, `--prompt`, ACL overrides, and `--share-tools` apply to\nboth forms ([run a mesh](run-a-mesh.md) has the full resolution rules). The session joins\nwith identity from its environment and auto-registers presence by the time it is\ninteractive.\n\nInside the session, the agent orients with one read-only tool, `cotal_orientation`: its\nidentity, the channels it reads and may post to, its capabilities, the tools available,\nwho's present, and unread counts. The full tool surface is the\n[MCP tool catalog](mcp-tools.md). In auth mode the team-supervision tools\n(`cotal_spawn` / `cotal_persona` / `cotal_personas`) are injected **only** for personas declaring\n`capabilities: [spawn]` (the same grant that opens the privileged control subject), so an\nagent's toolset matches its declared capabilities. `cotal_run` is gated separately by\n`run`; use `capabilities: [spawn, run]` for both. Fresh setup defaults include both.\nSee [workflow tool setup](workflows.md#from-an-agent-session) for a first run and missing-tool checks.\nClearing retained history is\noperator-only ([run a mesh](run-a-mesh.md)), never an agent tool.\n\n## How it binds\n\nClaude Code exposes four integration surfaces, and three of them collapse into a single\ndual-purpose MCP server:\n\n| Surface | Mechanism |\n|---|---|\n| Outbound, ambient | `http` lifecycle hooks \u2192 POST to the connector (presence, activity) |\n| Outbound, deliberate | MCP tools `cotal_send` / `cotal_dm` / `cotal_anycast` (+ `cotal_feedback`) |\n| Inbound, pull | MCP tool `cotal_inbox` (same server) |\n| Inbound, push | Channel nudge + hook drain (below) |\n\nThe manager launches the *real* `claude` (no wrapper):\n\n```\nclaude --strict-mcp-config --mcp-config '{\"mcpServers\":{\"cotal\":{\u2026}}}' \\\n       --dangerously-load-development-channels server:cotal\n# env: COTAL_SPACE, COTAL_NAME, COTAL_ROLE, COTAL_CHANNEL=1, plus claude's documented auth vars\n```\n\n- **Model auth.** Locally, `claude` still reads macOS Keychain / `~/.claude`. In a container or\n  CI there is no Keychain, so the connector forwards the documented credential set:\n  `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`), `ANTHROPIC_API_KEY` /\n  `ANTHROPIC_AUTH_TOKEN`, and the cloud-provider flags plus their credential vars. Host-session\n  markers (`CLAUDE_CODE_CHILD_SESSION`, `CLAUDECODE`) stay out so a nested seat still saves a\n  transcript. See [Deploy](deploy.md).\n- **Persona privacy.** The persona body is written to a private file and Claude receives only\n  `--append-system-prompt-file <path>`. The body never appears in the spawned process argv. The\n  carrier is a 0600 file inside a 0700 directory on POSIX, with equivalent owner-only ACL hardening\n  on Windows. That is OS-user isolation: any process running as your user can read it while it\n  exists. The manager or the foreground `cotal spawn` removes it, and the shared-server MCP config\n  file, once it has proved the `claude` process gone. If the launcher is killed first, a watcher\n  started beside `claude` removes them when `claude` exits.\n- **MCP servers.** `--strict-mcp-config` ignores every ambient MCP source, so a spawned agent\n  loads the cotal server plus the servers the cotal config shares. First-run `cotal setup`\n  fills that list with your own user-scope servers, so a spawned session has the tools you know\n  (see below).\n- **Installed plugin.** The plugin is installed once (`claude plugin install\n  cotal@cotal-mesh --scope local`) because its hooks bind only to an *installed* plugin.\n  The repo's `.claude-plugin/marketplace.json` lists the committed plugin tree under\n  `claude-plugin/`, which each release regenerates with the built bundles, the skills and the\n  release version, so an install from the repo or from a pinned commit runs without a build\n  ([Release](release.md)). `cotal setup` (npx, no clone) materializes the same marketplace under\n  `~/.cotal/claude-plugin/` from the installed CLI (each plugin dir is rebuilt from scratch and\n  atomically replaced, never merged, so no stale file rides in). The\n  `cotal-skills` plugin installs from that same marketplace at user scope (`claude plugin install\n  cotal-skills@cotal-mesh --scope user`); its manifest and install behavior ship inside the Claude connector, and\n  its version tracks the CLI release so updates land.\n- **Identity-gated.** Connector code requires `COTAL_NAME`, `COTAL_LINK` or `COTAL_AGENT_FILE`.\n  A plain `claude` with none of them never joins, so your own sessions in a repo do not appear\n  as stray peers. Its MCP server still answers `initialize` and lists one static tool,\n  `cotal_how_to_join`, which explains how to launch a session on a mesh. It builds no mesh\n  agent, opens no broker connection and binds no control socket.\n- **Hands-free.** The dev-channels flag prints a one-time confirm prompt. The PTY runtime waits for\n  the dialog title in normalized terminal output and presses Enter once when it appears, so startup\n  speed does not affect a supervised launch. If the declared prompt never appears, the seat exits\n  with a bounded error naming the unmatched prompt instead of hanging silently.\n\nInbound mesh messages arrive in context as\n`<channel source=\"cotal\" from=\"bob\" kind=\"dm\" \u2026>\u2026</channel>`: each meta key a tag\nattribute the agent can read for routing.\n\n## How messages reach the session\n\nDurable deliveries land in the connector's inbox from JetStream consumers\n([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)); live channel traffic can instead arrive\nthrough an at-most-once core subscription. A durable message sent while the agent is busy\nor offline waits on the stream. Two things move a message from inbox to model; one\ndelivers, the other only wakes:\n\n- **Hook drain (delivery).** `SessionStart` / `UserPromptSubmit` hooks read automatic inbox items and\n  inject them as `additionalContext`. This is the single authoritative path: deterministic and works\n  on any Claude Code build. Quiet ambient is excluded and stays buffered for `cotal_inbox`.\n  A message is **acked only once the hook reply carrying it has cleared both legs of its journey**:\n  the connector's control socket to the hook process (which gives up after 2s), and the hook\n  process's own stdout to Claude Code (which it force-exits 1s after starting to write). The relay\n  sends a receipt back down the control socket from that stdout write's callback, and only on a\n  clean write (a runtime whose pipe has gone away fails it), and the connector treats that receipt,\n  not its own socket write, as delivery. So a large injection killed mid-flush, or one written to a\n  broken pipe, leaves the message un-acked and JetStream redelivers it. What this does *not* prove is\n  that Claude Code read or applied the reply: a payload small enough to fit the pipe buffer is\n  reported written the moment the kernel takes it. That residual is why the path errs toward\n  at-least-once rather than treating a confirmed write as a confirmed read. Acking when\n  the reply was merely *formatted* meant a lost reply was a lost message: it was already marked\n  handled, so its own redelivery was silently acked on arrival.\n  A hook whose handler throws still returns an empty reply so the session is never blocked, and\n  that reply carries nothing, so it commits nothing: the batch it had started to surface stays\n  un-acked and goes out on a later frame. The seat also drops any `turn-pending` row that breaks\n  the manager contract, such as one with no integer deadline, and says so once in its log. A reply\n  with no `turns` array changes nothing: the seat keeps the turns it already holds.\n  This errs toward **at-least-once**: if a reply lands but its confirmation does not, the batch is\n  surfaced again and flagged as a possible repeat. A duplicate injection is noise; a buried DM stops\n  the peer answering at all.\n- **Channel nudge (wake).** An arriving message fires a `notifications/claude/channel`\n  event that wakes an *idle* session into a turn, so the drain runs *now* instead of at\n  the next prompt. The nudge never acks anything. A nudge that the host rejects is retried with a\n  bounded backoff while anything is still pending. For an idle session it is the only wake source,\n  so dropping it means silence until someone types. When the channel becomes active, the connector\n  first re-fires a focus mention remembered during startup, otherwise one buffered wake. A rejected\n  push keeps its bounded retry, and JetStream redelivery remains the durable backstop for unacked\n  inbox items. If the channel cannot run at all, delivery still waits for the next hook. Live-only\n  traffic has no durable retry.\n\n**Two priority tiers.** A *directed* message (DM, anycast, or a channel message that\n`@mentions` us) always nudges. *Ambient* channel chatter does not nudge mid-turn; it\naccumulates, and the `Stop` \u2192 idle transition fires one batch nudge so the backlog drains\ntogether.\n\n**Constraints (accepted).** Channels are a Claude Code research preview (\u2265 v2.1.80;\npermission relay \u2265 v2.1.81): Anthropic auth only, admin-enabled on Team/Enterprise, and a\ncustom channel needs the `--dangerously-load-development-channels` launch flag. The hook\ndrain does not depend on any of that; the channel only adds \"wake me when idle.\"\n\nThe same channel also relays **tool-permission requests** onto the mesh, so a peer (a\nhuman at the CLI, a policy node) can approve or deny an agent's pending tool call through\nCotal rather than a per-terminal prompt.\n\n### Attention\n\nAn agent picks how aggressively peer traffic reaches it with\n`cotal_status({ attention })` (three modes, orthogonal to presence):\n\n| arrival | open (default) | dnd | focus |\n|---|---|---|---|\n| directed (dm / anycast) | wake + inject | wake + inject | wake + inject |\n| channel `@mention` | wake + inject | wake + inject | ack-drop; wake to *pull*; not injected |\n| ambient channel chatter | wake when idle; hold while working | never wakes; injects next turn | ack-drop; recall via `cotal_inbox` |\n\nPer-channel overrides refine this: **quiet** (delivered, never wakes; `@mention` still\nwakes) and **muted** (dropped on receive, mentions included; DMs/anycast unaffected), set\nwith `cotal_channel_mode` or as agent-file defaults (`quiet:` / `muted:`,\n[agent files](agent-files.md)). A per-channel override is the final word for that channel.\nQuiet ambient is pull-only: it never hitchhikes on a human prompt, DM, mention, or other\nconnector-driven turn. `cotal_inbox` explicitly surfaces and clears it. A quiet-channel\n`@mention` remains automatic and injects normally.\n\nA pull is bounded too, and clears only what it hands over. One `cotal_inbox` call carries at most a\nreceivable window (direct messages and role requests first, then channel traffic, replayed history\nlast); whatever does not fit stays buffered, is named in the reply, and comes back on the next call.\nA message too large for one whole response is delivered in parts: once no smaller mail is waiting,\neach call carries its next part, and it is cleared only after its last part goes out, because clearing\nwhat was not handed over is the loss this bound exists to stop.\nThat matters most on the path where it is easiest to lose mail: reconnecting brings a channel-history\nreplay with it, so the largest payload and the least expendable message arrive in the same read.\n\nThe local inbox is bounded. On pathological overflow it evicts pull-only items first, then other\nchannel traffic, and a direct message or role request only when the whole buffer is directed mail.\nAn evicted channel item is acknowledged. An evicted direct message or role request never is, and\nthe broker redelivers it after the ack wait until a redelivery finds room. A direct message stays\npending on the session's DM durable, where `cotal deliver pending <name>` counts it. A role request\nstays on its role's shared queue, which that command does not read. A full inbox therefore delays\ndirected mail until the session drains it.\nIf the bounded live/durable classification guard also fills, the connector fails closed:\notherwise-normal ambient becomes pull-only until restart. Muted hard-drop and normal focus recall\nstill take precedence. Focus also keeps a bounded exclusion list so mode toggles cannot recall\nquiet/muted traffic; if that safety bound fills, recall skips the affected channel and reports it\nas incomplete rather than risk resurfacing excluded content. Recall cannot tell one message with an\nempty id from an identical one with another disposition, so in focus such a message is held in the\nlocal inbox as pull-only instead of being dropped, and a mention of it still wakes the agent. When\nthe session settles an id-less copy, it reads the chat stream's last sequence. Identical copies\narrive in stream order, and those reads can answer out of order, so the first read that can see the\ncopies binds them in arrival order, latest first, each to the latest unbound stream copy at or below\nthe lowest sequence read for it or any later identical copy.\nWhile the connection stays up, every stream copy at or below that sequence reached the session\nfirst, so a later identical copy sent during a reconnect gap is above it and stays unbound. A copy\nthat arrives while a read runs may not be in that read, so it binds nothing there and recall reads\nthe channel again, up to three times; if it still could be a stream copy in the last read, recall\nleaves that stream copy in the stream and reports the channel as incomplete. A settled copy a\ncomplete read cannot bind is behind the focus start or out of retention, and is forgotten. Recall\nhands back into the inbox only the stream copies nothing is bound to, such as one sent during a\nreconnect gap or one the inbox evicted on overflow, and `cotal_inbox` hands each over once. Overflow\nfrees only the evicted copy, held or quiet, and a copy no read has bound yet keeps its place in\narrival order, so an identical muted copy stays out of recall. When\nthe inbox is full, recall leaves them in the stream for a later call and reports the channel as\nincomplete. A history read that fails, or a channel with replay off, settles nothing and is reported\nas incomplete, and recall calls run one at a time. If the sequence read for a settled copy fails,\nor answers only after the connection dropped, recall skips that channel for the rest of the focus\nperiod and reports it as incomplete. Recall cannot tell a late copy of a message it handed back from\na new identical message, so every copy takes its own disposition: a new identical quiet mention is\nstill delivered automatically, and a late copy can surface a second time.\nA recalled message that already went out in part is read to its last part, even if an exclusion\nlands after its first part. One session reads its inbox one call at a time: a `cotal_inbox` call\nthat overlaps another waits for it to finish, so neither decides from a view the other has already\nmoved past.\nIf the separate hard-drop disposition guard fills, channel traffic is dropped for the rest of the\nsession rather than risk a late copy bypassing an earlier muted/focus decision; DMs and anycast are\nunaffected.\n\nAttention is **advisory UX, not a boundary**: any peer can wake a dnd/focus agent by\nnaming it, and `muted` means \"I opted out of receiving\", not \"the channel is blocked\";\nthe broker still authorizes and delivers. Focus's real effect is shrinking the\nuntrusted-ambient injection surface (only subject-authenticated dm/anycast auto-inject).\nIt resets to **open** on `SessionStart`, so a restarted agent never stays silently deaf.\nYour attention is mirrored into presence so peers can see it.\n\nWhatever does reach a turn is framed so a peer cannot write the frame. A line that begins at column\nzero is written by the connector; one message is one line plus indented continuations, with the\nsender inside a single bracket pair. A message body, a sender name and role, and a service or\nchannel label are all peer-controlled, so each passes through the same neutralization the\n`cotal_inbox` reply uses: no line break a splitter may honour and no bracket survives into a\nrendered attribution. This matters more for an injected block than for a reply, because the agent\ndid not ask for it and so never had the chance to distrust it.\n\n## Presence mapping\n\nThe connector wires a small subset of Claude Code hooks to presence states; presence is\ncoarse, and \"what it is doing\" rides on activity updates. Presence is **advisory**: a presence\npublish that fails (the endpoint mid-reconnect, say) is swallowed and never prevents the same hook\nfrom delivering messages or flushing held ones.\nA `SessionStart` during an open turn, including compaction, preserves the current `working` or\n`waiting` status until `Stop`, `StopFailure`, or `SessionEnd` closes the turn.\n\n| Hook | \u2192 state |\n|---|---|\n| `SessionStart` | `idle` only when no turn is open (join; surfaces the inbox; captures the live model into `meta.model` when no pin) |\n| `UserPromptSubmit` | `working` (turn starts; surfaces the inbox) |\n| `PreToolUse` | no change; records *what* is about to run, so a permission wait can name it |\n| `Notification` (`permission_prompt` / `agent_needs_input`) | `waiting` with condition `approval` / `input` (activity leads with the pending tool, e.g. `Bash: git push \u2026`) |\n| `Stop` / `StopFailure` | `idle` (turn done / died on an API error; flushes anything held while busy). `StopFailure` also relays Claude Code's native error value as `condition.source` and maps it to the closed condition vocabulary. On the [event plane](#event-plane) it closes the run with `RUN_ERROR`. |\n| `SessionEnd` | `offline` (graceful leave) |\n\nThe connector also leaves gracefully when its stdin closes. An MCP client closes it to end the\nsession, and a killed `claude` closes it with no `SessionEnd`, so a dead session drops off the\nroster instead of staying on it as a live peer.\n\n`StopFailure` maps `rate_limit` and `overloaded` directly; auth and credential failures to\n`auth`; account and billing failures to `billing`; `invalid_request` to `request`;\n`model_not_found` to `model`; `server_error` to `server`; `max_output_tokens` to `context`; and\n`unknown` to `failed`. The native value remains in `condition.source`.\n\nHooks are relayed over the connector's **authenticated** local control endpoint (per-user\nsocket + per-launch token, constant-time checked), so a local process that finds the path\nstill can't drive presence or stop the agent. The full Claude Code hook-event list lives\nwith the adapter:\n[`extensions/connector-claude-code`](../extensions/connector-claude-code/README.md).\n\n## Event plane\n\nA spawned session publishes a **structured** account of what it\ndid: run boundaries per turn, assistant text, reasoning, and each tool call with its start\nand its end. Not prose about the work, the work itself, in a vocabulary a program can\nread. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an unrestricted\nspace. A user-auth registration with `policy: { events: \"required\" }` carries `eventsRequired` in the\nprivate launch material, so the connector arms even without `COTAL_EVENTS`; `--no-events` is refused.\nA hand-driven user-mode session may carry the same decision as `COTAL_EVENTS_REQUIRED=1`. Its own\npublish grant must cover `events.<owner>.<actor>` or the connector refuses before joining. An unmanaged\nsession with no launch material and no required-policy fallback keeps the generic default behavior.\n\nA new session includes its first run even when Claude writes a positional startup prompt before the\nconnector receives `SessionStart`. That from-zero read is keyed only to Claude's explicit\n`source: \"startup\"`; resumed, forked, cleared, and compacted sessions adopt at the transcript boundary\ncaptured at that adopt, before the mesh link connects, so nothing Claude appends while the connector\nis still starting up lands behind the cursor and is silently dropped. Crash recovery follows the\ncursor already stored in the event write-ahead log, regardless of the new process's startup label.\n\nClaude starts each hook in its own process, so a prompt or stop relay can reach Cotal before the\n`SessionStart` relay. The connector holds those event flushes and the terminal until `SessionStart`\nsupplies the source, then enqueues adopt, flush, and close in that order.\n\n`SessionStart` can also run before the connector process has bound its local control socket. The hook\nthe `SessionStart` relay retries only transient pre-connect listener errors, with capped backoff\ninside its existing two-second budget. Later hooks and permanent local faults still fail open\nimmediately. Once a socket has connected, a broken exchange is not retried: the connector may\nalready have handled the frame, so replaying it could apply one lifecycle event twice.\nThat retained `SessionStart` can itself arrive before Claude creates the transcript path. A genuinely\nnew startup waits up to five seconds for that file with capped backoff, and the same deadline bounds\none stalled file read; expiry fails loud instead of silently losing the first run. A forked session\ngets the same wait, because Claude copies the parent transcript into the fork's own file after the\nhook, and then adopts at the end of that copy. Resumed, cleared and compacted starts and recovered\ncursors still require their existing source at once.\n\nTool arguments (`TOOL_CALL_ARGS`) and tool results (`TOOL_CALL_RESULT`) are not republished\nonto this channel. The durable emitter drops those events before they are written to the\nwrite-ahead log, because this channel's read ACL is not the ACL the tool ran under. Content is\nmandatory on both kinds, so the event is suppressed rather than emptied or replaced with a\nplaceholder. Tool start and end still go out. A restart that finds a pending pre-fix frame\nstill carrying those kinds HALTS rather than republishing it.\n\nThe channel is **`events.<owner>.<actor>`**, named after the session's principal. What the actor\nhalf is depends on the mesh, and the difference matters when you go looking for it: on a static mesh\nit is a key the manager allocated, never the display name, so two live agents sharing a display name\ndo not share a stream; on a user-auth mesh it is the agent's own name, because that is what the\nledger row is keyed on. Spelled out again with both halves below. The launch grants publish rights\non that channel alone. A spawn\nthat asks for a *different* agent's event channel is refused at the door rather than granted, since\nthat channel is that session's event stream. The same rule runs on restart: a manager\nresume document that names another agent's event channel is refused rather than adopted, because the\nmanaged row is re-armed from that document and the credential is re-minted from the row.\n\nThe rule reads a **concrete** channel, two principal tokens and nothing else. A pattern such as\n`events.<owner>.>` is not an event channel to it and passes untouched, governed by ordinary ACL\nauthority: on a user mesh the delegation envelope, on a static mesh the spawning credential itself.\nThat is deliberate, because the pattern is the form an operator writes on purpose for an observer,\nand it is worth knowing rather than assuming the fence is total.\n\nTo let something else read a plane, grant it out of band. The refusal prints the command for the\nmesh it is running on, spelled out in full, and only that one.\n\nOn a **user-auth** mesh:\n\n```bash\ncotal actor grant <reader> --owner <owner> --scope '' --allow-subscribe 'events.<owner>.<actor>' --allow-publish ''\n```\n\nEvery field, deliberately. `actor grant` is an upsert of the whole row, so it refuses a grant that\nleaves off any of the three ACL flags. Only `--full` turns an omitted flag into the wide default\n(`>` read, `>` post, `spawn,role:default` scope), which is the opposite of what a scoped watcher is for.\n\nOn a **static** mesh there is no actor ledger for `actor grant` to write to, and the refusal says\nso; mint the reader instead:\n\n```bash\ncotal mint watcher --profile agent --allow-subscribe 'events.<owner>.<actor>' --provision\n```\n\nThe **agent** profile, not the observer one. `mint` reads `--allow-subscribe` only for that\nprofile, and refuses it anywhere else: `--profile observer --allow-subscribe <channel>` exits\nnon-zero and writes no creds file, because the observer profile carries a fixed read set over the\nwhole chat plane, which is the opposite of what a scoped watcher is for. The agent profile also prints the lifecycle uid the\nreader needs, since an authed consuming endpoint refuses to start without one.\n\nOn an **open** mesh there is nothing to grant: the mesh has no credentials and no ACLs, so any peer\nthat lists the channel reads it, and the refusal says so instead of naming a command. The\nown-channel rule still applies there, because a spawn is not the place to hand out a read on\nanother agent's tool inputs and outputs.\n\nTwo things a reader has to do that are not obvious, both on `CotalEndpoint`. It must pass the event\nchannel in `channels`: an endpoint reads the channels it lists, so one constructed without\nthe event channel joins nothing and the frames never arrive. And it reads history with `readHistory(channel)`, the delivery daemon's mediated read, not\n`channelHistory(channel)`: a scoped credential is denied the ad-hoc consumer the direct read\ncreates, by design. `cotal console` and the web console already do both.\n\nThe `<owner>.<actor>` pair is the session's principal. On a user-auth mesh the actor half is the\nagent's own name, so the channel is `events.<your-owner>.<agent-name>`. On a\nstatic mesh the owner half is the literal `local` and the actor is a key the manager allocated, so\nthe channel is `events.local.<key>`; the spawn reply carries that key as `id`. Note\nthat `cotal console` and the web console keep event channels out of their channel lists on purpose,\nsince a plane is a machine feed rather than a conversation; they draw the frames when you open the\nchannel by name.\n\nThe rule governs the manager's doors, which are the ones a caller other than you can reach. A\nforeground `cotal spawn` on your own machine mints from your own signing material, so it can still\ngrant any channel you name: that is the out-of-band grant, not a way around the rule.\n\n**Failed turns publish run errors.** Claude Code decides for itself\nwhether a turn finished or died and fires one of two hooks accordingly, so the connector relays that\ndecision rather than making one of its own: a turn that ended on an API error ends its run with\n`RUN_ERROR` carrying the fixed message `run failed` and no code. Neither the detail Claude Code\nreported nor its error kind is published there: both are upstream values that can echo your prompt or\ntool output, and the events channel has a different read ACL. The error kind still reaches presence\nas the agent's condition (`rate_limit`, `auth`, `billing` and the rest). A turn that ended normally still\nends with a run-finished event carrying no outcome, which says the turn ended and does not claim it\nsucceeded.\n\nEvents are written to a per-session write-ahead log before they are published, so a hook that fires\nafter a restart resumes at the cursor it left rather than replaying or skipping, and a run that was\nopen when the session stopped is closed rather than left dangling.\n\nOne channel carries **every session of one agent**, because it is named after the principal and not\nafter the session. Alongside the per-session logs the connector keeps one small record per principal,\nholding the last sequence the broker assigned on that channel, so a new session continues the stream\nits predecessor left instead of starting again from nothing. Both live under the events state root\n(`COTAL_WORKSPACE_ROOT`), and neither is something you edit by hand.\n\nA **missing** record is not a fault: the connector rebuilds it from the session logs beside it,\nwhich is how an agent that was already running before this record existed keeps its stream. That\nrebuild stops if any one of those session logs is damaged. Unreadable, not valid JSON, and written\nfor a different principal all count, and so does a session directory or a log that is a link rather\nthan the real file the connector wrote, or a log that has more than one name. A tip taken from the\nrest would be too low, and it would stop publication later with nothing left to point at the cause.\nThe connector names the file instead, and the only way past it is the directory removal described\nbelow, under the same condition. A record that **disagrees with the broker** is a fault, and the\nconnector stops publishing and says why rather than guessing. A record that **moved while a session\nwas writing to it** is refused the same way: it means something else wrote the principal's record,\nand the connector reports which value it held and which the file holds rather than writing over the\nlater one. There is no command to clear it. The state is the principal's directory under the events\nroot, and clearing it by hand means removing that directory whole: the sequence, the cursor and the\nper-session logs only mean anything together, so removing part of it leaves a state the next start\nrefuses. Removing it is only half a remedy, and the half that comes first is the channel. The\ndirectory is where the agent's memory of the tip lives, not the tip itself, so on a channel that\nstill holds frames the next session opens expecting an empty one and stops on the same\ndisagreement, with the logs a tip could have been rebuilt from now gone. Purge the channel first,\nthen remove the directory.\n\nReading it: `cotal console` and the web console draw event frames directly. A frame carries no text\npart by design, so a surface that renders a message as flat text shows a marker instead of prose.\n\n**On a per-user-auth mesh, the default event plane needs the spawner's grant to cover the channel.** The event\nchannel is added to the child's publish set, and delegation only narrows: an agent may hand down\na subset of what it holds and no more. So a peer-initiated spawn is refused unless the\nspawning identity's own grant already covers the child's event channel. The refusal prints the\nexact `cotal actor grant` command that widens it. An operator launch, whose chain reaches an\nadmin-scoped or roster row, is unaffected. Passing `events: false` is the explicit opt-out.\n\nArming the event plane through a typed spawn request (`manager.spawn` with `events`, including\nthe CLI's `cotal spawn --detach --events`) additionally requires the caller's admin tier on a\nuser mesh. A non-admin caller that asks for the plane is refused before anything is provisioned,\nand one that stays silent gets a spawn without it, with the reply saying so.\n\n## Resume a session\n\n`--resume <session-id>` pulls an existing Claude session, its context and transcript,\ninto the mesh. It **forks**: Claude mints a *new* session id from that transcript\n(`--resume <id> --fork-session`), so the meshed agent gets its own session and the\noriginal is untouched.\n\n- `cotal spawn --resume <id>` (foreground) is the primary surface: the transcript is on\n  *your* machine, and errors are Claude's own stderr, inline.\n- `--detach --resume <id>` works, with two differences: the id resolves against the\n  **manager host's** `~/.claude` (you practically need `--cwd`), and the manager waits for\n  a real outcome; `\u2713 started` means the agent *joined the mesh*, `\u2717 exited on launch`\n  carries Claude's last output, and an uncertain launch (~30 s) is reported without\n  tearing the agent down.\n- Resume is an **operator surface only**, deliberately not exposed on MCP `cotal_spawn`\n  (a mesh peer naming host-local transcripts would widen `spawn` into transcript\n  disclosure). Only the Claude connector supports it today; OpenCode and Hermes fail loud.\n- Needs a `claude` new enough for `--resume \u2026 --fork-session` (verified on 2.1.197).\n\n## Sharing your MCP servers\n\nA spawned session keeps your own MCP servers by default. On its first run, `cotal setup` copies\nthe user-scope servers from your Claude Code config (`~/.claude.json`, or the one under\n`$CLAUDE_CONFIG_DIR`) into the cotal config file (`~/.config/cotal/config.json`) under\n`connectors.claude.mcpServers`, and names them in its output. With none to copy it writes an\nempty list. Each entry is the familiar `.mcp.json` shape ([full format](config.md)). A cotal\nconfig that already declares that list keeps it, and a later `cotal setup` never changes it.\n\nThe cotal config holds secrets only as `${VAR}` references. Setup cannot tell literal text from\na secret, so it leaves out a server with an `env` or `headers` value that is anything but `${VAR}`\nreferences (a `Bearer ${TOKEN}` header among them) and names it in its output. To share one,\nadd it to the cotal config with each secret written as a `${VAR}` reference, and export that\nvariable where you spawn. Setup also leaves out and names an entry no session can start, such as\none with a missing or empty `command` or `url`, or one whose `command` is not a string.\n\nAt launch the connector forwards *only* the named vars the chosen servers declare and\npasses the merged config as an owner-only temp file; `--strict-mcp-config` stays on, so\nonly cotal + the shared servers load.\n\nFor a lighter seat, share fewer. Remove an entry from the cotal config to drop it from every\nspawn, or scope one spawn with `--share-tools tavily,figma` (or `--share-tools none` for cotal\nalone). An empty list (`\"mcpServers\": {}`) in `~/.config/cotal/config.json` keeps every spawn\nisolated, and setup leaves it as it is.\n\nTwo caveats: sharing a server grants its credential to the agent (the var lives in the\nClaude process's environment, so share only when you're fine with that teammate holding\nthe key), and memory adds up, because a heavy server boots once per spawn, multiplied\nacross a team, and can starve a small machine.\n\n## Feedback\n\n`cotal_feedback` works out of the box: without a key it posts to the public intake at\n`https://cotal.ai/v1/feedback` (needs a contact email: `COTAL_FEEDBACK_EMAIL`, then\n`git config user.email`, else the agent asks). Set `COTAL_FEEDBACK_KEY=fbk_<key>` in a\nbeta tester's environment to route to the keyed intake (`Authorization: Bearer`, identity\nderived from the key); `COTAL_FEEDBACK_URL` overrides either endpoint. The CLI can send\ntoo: `cotal feedback \"<summary>\" [--type bug]`. Each submission carries\n`origin: human | agent`, whether the tester asked, or the agent auto-reported a major\nissue.\n"
     },
     {
       "slug": "connect-codex",
@@ -19629,7 +19643,7 @@ var DOCS_BUNDLE = {
       "title": "Connect Jcode (beta)",
       "kind": "Guide (informative)",
       "summary": "Jcode joins a Cotal mesh as a lateral peer.",
-      "body": "# Connect Jcode (beta)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Jcode](https://github.com/1jehuang/jcode) joins a Cotal mesh as a lateral peer. The connector\ncreates one private Jcode Harness API instance per seat, one Jcode session inside it, and exposes\nthe normal `cotal_*` tool surface through Jcode's documented stdio MCP configuration.\n\n**Beta** means the supported path is deliberately narrow: a fresh private session, a fork of one\nof your own sessions (`--resume`), prompt injection, presence, managed start/stop, requested\nreasoning effort, and an attached TUI work. Features that do not preserve that private session's\nmesh surface fail loud: exact-session continuation, `--share-tools`, and connector `--opt` values\nare not supported.\n\n## Install\n\nThe connector is seeded with the Cotal CLI. Jcode's released Harness API bridge is a Unix-socket\nsurface, so Windows is not supported. Managed seats run on Linux, macOS, and the BSDs.\nInstall Jcode 0.78.1 or later from its GitHub release and make the binary available as `jcode` on `PATH`:\n\n```bash\njcode version --json\ncotal spawn --agent jcode\n```\n\nIf an older Cotal installation is missing the connector, run `cotal ext seed --repair` (or\n`cotal ext add @cotal-ai/connector-jcode`). This connector intentionally uses the released\nbinary's `api-bridge` command; it does not require a Rust checkout.\n\n## Spawn it\n\n```bash\ncotal spawn --agent jcode\ncotal spawn reviewer --agent jcode -d\ncotal spawn --agent jcode --model gpt-5.6-sol --prompt \"Review the current change.\"\nCOTAL_DEFAULT_AGENT=jcode cotal spawn\n```\n\nA detached seat is managed normally: `cotal ps`, `cotal attach`, and `cotal stop` control the\nsame process the connector starts. In a terminal, Jcode opens on the managed session. With piped\noutput it stays headless; set `COTAL_JCODE_TUI=1` or `COTAL_JCODE_TUI=0` in the environment of the\nprocess building the launch to override that choice. For a detached spawn, that is the manager's\nenvironment.\n\n## How it binds\n\nJcode's stable integration surface is the **Harness API**: protocol-v1 NDJSON over a Unix socket.\nThe connector launches a **private instance** with `@1jehuang/jcode-sdk`'s `launchInstance()` and\nattaches only to that instance's own socket:\n\n- `launchInstance()` starts a private `JCODE_HOME`, runtime directory, daemon, and `api-bridge`;\n  the connector holds the process handle first-hand and closes that instance with the Cotal seat.\n  This gives each managed Cotal peer one owned session and prevents it from seeing or changing\n  the operator's live Jcode sessions.\n- Attaching to an **operator-run** `jcode api-bridge` shares the operator's live session\n  inventory. That is appropriate for a dashboard or editor integration, but not a managed Cotal\n  seat: stop, prompt injection, and session selection could act on the operator's work. The\n  connector never attaches to an operator bridge.\n- A managed seat **never updates its own binary**. Jcode's background updater restarts the\n  process tree when it lands a release; that restart drops the seat's TUI, which is the only\n  connection the Jcode server counts as a client, and nothing re-attaches, so the server's idle\n  reaper takes the seat down five minutes later in the middle of a turn. The seat's version is\n  whatever is on `PATH` when you spawn it, and it stays that version for the seat's life. Update\n  deliberately, between seats, not under a running agent.\n\nOn a graceful stop **and** on a startup failure, the connector proves the private daemon tree is\nactually gone rather than trusting the SDK's registry-keyed stop (which is a silent no-op when the\n`servers.json` socket path does not match verbatim): it reads the PIDs the private home itself\nrecords, sends a bounded SIGTERM, escalates survivors to an exact-PID SIGKILL, and reports a\nfailed stop instead of a clean one if any recorded process survives. It never signals by name, so\nteardown can only ever reach the seat's own tree.\n\nA seat that dies without that teardown, from a manager restart or a kill past the grace window,\nleaves its Jcode server running. The server has a process group of its own and carries no\n`COTAL_NAME`, so a name-keyed reap does not reach it, and it holds the seat's runtime directory\nuntil its own five-minute idle timer expires. Each launch records its identity nonce and its host\nprocess in the private home, and the seat's next launch stops the tree that record names. The\nrecorded host is the gate: while it is still alive the seat is still serving, so nothing is\nsignalled and the second launch meets Jcode's own runtime-directory lock instead.\n\nThe private Jcode home lives under `<manager-workspace>/.cotal/jcode/`. It is unique per\nspace/name and is owner-only. Jcode's own credential inheritance is used for the private instance,\nso provider logins work without copying its transcript/config tree into the seat. The spawned\nJcode process does not inherit `COTAL_*` values or the Cotal launch-material pointer.\n\nBecause the home is keyed by space and name, a seat respawned under the same space, name, and\nmanager workspace lands in the same home, and the connector automatically continues the\nnon-archived Jcode session there that was recorded for the seat's working directory and holds the\nlargest transcript, since that is the session carrying the memory a restart would otherwise throw\naway. A seat spawned under a fresh name keys a different home and starts with an\nempty transcript, so keep the same name when you want a replacement seat to continue where the\nprevious one stopped. This automatic continuation is a relaunch of the seat's own private session;\nit is separate from `--resume`, which forks an outside session into the seat (below). The short\nsocket alias the connector derives from that home is reclaimed at every launch, so a name a stopped\nseat used stays launchable.\n\n`cotal spawn --resume <id>` forks session `<id>` from your own Jcode home (`JCODE_HOME`, or the\ndefault Jcode home) into the seat's private home before the seat's instance starts. The Harness API\nhas no fork call, so the connector does what Jcode's own split does: it writes a new session whose\nparent is the source and which carries the source's messages, compaction state, system prompt, and\nmodel. The seat gets a new session id and its briefing as the first turn after that history. The\nsource files are only read, so the source transcript is never appended to. A session id with no\nreadable transcript, or one whose snapshot or journal holds fields Jcode cannot load, is refused\nbefore the seat launches; every carried message, content block, and compaction state is checked\nagainst Jcode's own schema, and the refusal names the field. Jcode stores its counts as u64 and\nreads one only as a plain decimal integer, so a count above what a JavaScript number holds is copied\nbyte for byte, and one above the u64 range or spelled with a fraction or an exponent (`1e3`, `1.0`)\nis refused. The source may be live: the connector\nreads it until two reads agree and every journal line is newer than the snapshot, so a Jcode\ncheckpoint caught mid-way is neither lost nor applied twice, and a session that keeps changing is\nrefused with a request to retry. A seat relaunched under the same name continues its\nfork rather than forking again, without reading the source, which may since have been deleted. The\nseat's briefing is recorded separately from the fork, so a first launch that fails after forking\nstill briefs the seat on its next launch. The seat records the source session id, its title, and a\nSHA-256 of the snapshot and journal it read, prints them when it forks, and the manager reads that\nrecord into the seat's resume document, so `cotal ps --wide` shows them. The manager keeps a title\nof at most 1024 characters, so a source with a longer title is refused before the seat launches.\n\nConnector diagnostics are written both to the spawning terminal and to an owner-only\n`<private-home>/logs/connector-<timestamp>-<pid>.log`, so a failed launch remains inspectable after\nthe manager's launch error scrolls away. Public startup failures stay scrubbed to allow-listed\ncodes rather than arbitrary Harness API messages.\n\nCredential mirroring is mandatory for managed Jcode seats: each launch atomically refreshes the\nallowlisted Jcode, provider-config, and external-login destinations, and removes a destination when\nits source login was removed. Cleanup addresses only that explicit inventory; transcripts, MCP\nconfiguration, logs, and other private-home state are untouched. Copy, mkdir, and removal walk the\nparents with `O_NOFOLLOW`, then publish, create, or unlink the leaf through the pinned parent rather\nthan through a path the kernel re-walks. Replacing a walked directory with a symlink cannot write,\ncreate, or delete a namesake outside the private home.\n\nTwo mechanisms provide that pin. On Linux the leaf is named `/dev/fd/<fd>/<name>`, the openat and\nunlinkat equivalent Node does not expose, after `/dev/fd/<fd>/.` is proven to traverse. macOS mounts\n`/dev/fd` but has no subpath namespace under a descriptor, so there the connector pins the parent as\nthe process working directory instead: a single-component name resolves from that directory's inode\nand no ancestor is walked again. Entering by path is verified rather than trusted, because `chdir`\ntakes a path: the entered directory's inode must equal the inode of the descriptor opened a moment\nearlier, and a mismatch is refused by name. The working directory is restored on every exit,\nincluding the refusing ones. If neither pin is available, the connector throws a named error and\nmirrors nothing. Once a pin holds, `ENOENT` on a child means the mirror path is absent.\n\nThere is no credential-free opt-out today because the private instance must reproduce the operator's\ncurrent provider-login state rather than silently start with stale or partial authorization.\n\nIf a provider failure closes the private Harness API connection during a mesh-driven turn, the\nconnector leaves that turn's inbox batch unacknowledged and opens one bounded recovery window for a\nprivate replacement connection to the same session. The window lasts 60 seconds from the close, and\nstopping the broken private tree counts against it. A transient launch or attach failure retries\ninside that window, so a loaded host gets the same result as a fast one without creating an\nunbounded connector relaunch loop. The seat reports `waiting` while it reconnects, then redrives\nthat unacknowledged batch only after the session attaches. Each failed replacement must be proven\nstopped before another launch. A permanent Harness refusal, including an invalid request, missing\nsession, protocol mismatch, missing binary, or socket permission denial, ends the seat immediately;\nanother launch cannot change it. An unprovable teardown, the recovery window expiring, or a second\ndisconnect after a successful replacement also ends the seat. When a turn failed on a Harness error\nand no turn has succeeded since, whether the host or the TUI owned it, the connector line that ends\nthe seat this way also names that error as `last turn error: <message>`, so the manager's\n`seat reaped:` line carries it without a read of the seat's private log. The reap line keeps only the\nfirst 240 characters, so that field comes before the error of a failed recovery, which then reads\n`recovery error: <message>`. An unrecognized Harness SDK error\ncode remains transient by default and retries inside the same bounded window; new permanent codes\nmust be added to the explicit classifier and its exact-count regression.\n\nJcode currently supports **stdio** MCP servers. The connector writes only its own `cotal` entry to\nthe private `JCODE_HOME/mcp.json`; it starts a stdio MCP bridge for that entry and relays its calls\nto the host's one `MeshAgent`. The Jcode/MCP child receives a per-launch relay capability, but not\nthe Cotal broker credential or its launch-material pointer. Jcode also overlays project\n`.jcode/mcp.json`, `.mcp.json`, and `.claude/mcp.json`; a managed launch **refuses** a workspace\ncontaining any of those files, because one could replace the `cotal` bridge or add tools that were\nnot explicitly shared. Operator MCP configuration is isolated in the private home and project MCP\nconfiguration is not supported yet.\n\nBefore the seat joins the mesh, the host runs a mandatory Jcode turn that calls\n`cotal_orientation`. Jcode loads MCP tools asynchronously; its first turn can use the pre-MCP tool\nsnapshot immediately before Jcode rebuilds that snapshot. The host repeats the identical proof once\nin that case. A second absence fails the launch, so a bridge that never comes up remains a loud\nfailure rather than an agent that is present but mute. The persona is already in that transcript as\na no-reply message; the spawn `--prompt` is not submitted until after join. While the proof is in\nflight the connector log names `pre-join readiness` and the bound. That in-flight line only means\nstartup reached the gate; it is not a hang, a missing prompt, or a provider refusal by itself.\nAfter the turn, a second line names the outcome and is what separates those cases:\n`orientation proved; joining with no spawn --prompt` or `joining, then submitting the spawn\n--prompt` when the proof passed; `provider refusal` when the provider rejected the turn; `timeout`\nwhen the bound fired. A genuine hang that never returns and never hits the bound has no outcome\nline. A one-line log with no route line is not that signal. The proof itself is bounded to the\nsame three minutes the connector declares to the manager (`readinessTimeoutMs` is the exported\n`JCODE_READINESS_TIMEOUT_MS`). Tests may shorten the host bound through\n`COTAL_JCODE_READINESS_TIMEOUT_MS`; that override is not an operator setting and does not change\nthe window the connector declares to the manager. The bound is a call-observation deadline: the\nhost proves readiness on the orientation `tool_done` event as it arrives, without waiting for\n`turn_done`. If that call never arrives inside the window the host exits `readiness_timeout` and\nnever joins, rather than working invisibly. That teardown does not wait for the in-flight turn:\nit kills the private Jcode tree and discards whatever that turn had generated. Nothing from it\nis recoverable; inspect the seat connector log for the timeout outcome, then spawn again. The\ntimeout line names whether the orientation call was observed. A seat that already made the call\njoins even if that proof turn is still open; the host does not destroy a functional session\nsolely because `turn_done` has not arrived. The manager's wait can still report `uncertain` when\njoin itself is slow after a passing proof; that is not a cleanup verdict, and it is not the same\nas a host `readiness_timeout`. Use `cotal attach <name>` or `cotal ps` to inspect an `uncertain`\nlaunch. The\nhost then waits for the mesh connection and presence bind to complete before it delivers a notice\nthat the bootstrap orientation predates the join and that a new orientation is live context. During\na broker outage, it stays waiting and sends no connected notice.\n\nA seat launched with a spawn `--prompt` gets that notice as a no-reply append; the prompt is still\nthe seat's first driven turn. A seat launched with no spawn `--prompt` has nothing else to schedule\na turn after join, so the notice is delivered as the seat's first driven turn instead of a no-reply\nappend: the same dispatch boundary and one-shot rule the startup prompt uses, so the seat's final\nstartup state is never an unread append.\n\nA refused post-join notice sent as a no-reply append is logged without ending the joined session.\nWhen the notice is instead the startup turn (no spawn prompt), a refusal on that turn is handled\nthe same way any other startup-prompt failure is: logged and retried, never fatal to the seat. The\nstartup prompt (or, with no spawn prompt, the notice standing in for it) stays pending while the\nnative session is busy or its bridge reconnects. Once the host invokes the request, it consumes\nthat prompt and does not retry it after an ambiguous error or close. This prevents a second\nsubmission; it cannot prove whether the first request executed.\n\nThe startup prompt excludes the automatic inbox. Messages buffered before it run in the following\nturn, including ordinary channel traffic held in `dnd`. Quiet-channel traffic remains available only\nthrough an explicit inbox pull. The connector log names a startup prompt waiting on in-flight\nsteering and a turn deferred because native state changed during that wait.\n\n## Event plane\n\nA spawned seat publishes run boundaries, assistant text, reasoning,\nand tool starts and ends on `events.<owner>.<actor>`. Tool arguments and results are not published.\nThe channel and grant rules are the same as the other connectors; see\n[Connect Claude Code](connect-claude.md#event-plane) for how to grant and read one.\n\nJcode's live Harness API reports token-sized text and reasoning deltas, but that stream cannot be\nread again after a host crash. The connector therefore reads Jcode's native append-only session\njournal under the seat's private home. The journal supplies a durable byte cursor and is keyed by\nthe Jcode session id, which is also the AG-UI thread id. A restarted seat continues from the cursor\nstored in its event write-ahead log and does not republish records already acknowledged.\n\nIf Jcode checkpoints its journal, the connector validates the saved session snapshot and ends the\ninterrupted event observations with `RUN_ERROR`. Open tool observations end before this error; this\ndoes not claim that their executions completed. The seat stays up while the next journal is absent,\nincluding during a long tool call. The reader keeps its previous cursor until it can read the new\njournal from its beginning. It does not reconstruct missing output from the snapshot. A tool result\nwhose start was not observed also ends the run with `RUN_ERROR`, not an invented tool start or an\nunpaired end. Like every published run error, both carry only the fixed message `run failed`: the\nconnector's codes `jcode_journal_fold` and `jcode_tool_start_missing` do not leave the seat. On restart, open tools are restored from the event WAL.\n\nA missing journal without a valid snapshot for the same session remains an emitter failure.\nMalformed cursors, invalid complete records and filesystem access refusals are not checkpoints.\n\nWhen the seat's mesh connection drops and the endpoint is rebuilding it, event publishing waits\nuntil the connection is live again and then publishes the queued records in order. The seat stays up\nthrough the outage. If the seat is stopped before the connection returns, the wait ends and the\nconnector log records `AG-UI emitter stopped`. The unpublished records stay in the journal\nbehind the stored cursor, and the next start publishes them. Any other emitter failure still stops\nthe seat with exit code 1.\n\nThe journal records settled message blocks rather than live deltas. Text and reasoning therefore\narrive per persisted block, and tool activity arrives when Jcode persists the tool-use and result\nblocks. User prompt text is not republished onto the event channel. The launcher sets\n`COTAL_EVENTS` by default; pass `--no-events` to opt out.\nOn an open mesh, a default event-enabled Jcode seat uses its managed seat name as the stable actor\ntoken; with `--no-events`, open-mode identity keeps its ordinary self-minted behavior.\n\n\nFor a foreground launch, the TUI opens as soon as the session is ready, before the readiness turn,\nso it streams boot activity instead of leaving the terminal blank. Presence still begins only after\nthe readiness proof passes. An inbound peer message then wakes a Harness API turn. A directed message\nthat arrives while the Harness session is busy (a Cotal-owned `run()`, a TUI-owned turn, or an\nadvisory idle pulse between tool rounds of a still-open Cotal-owned run) enters Jcode's session-owned\nsoft-interrupt queue. Ambient channel traffic stays buffered for the next turn. The host marks\npresence working while the session is busy, publishes `activity` naming automatic queue depth and age\nwhile anything remains uncommitted, and acknowledges every initial or soft-interrupted inbox id only\nafter that containing turn succeeds. A failed Cotal-owned turn or private Harness replacement leaves\nthose ids unacknowledged for mesh redelivery. When the Harness reports the failure itself, such as a\nprovider `rate_limit`, the host relays its error code as the presence `condition`, so the roster and\n`cotal ps` read `waiting (rate_limit for 2m)`. A turn the TUI owns is covered too: its failure arrives as an\nunsolicited Harness error frame, and the host relays that the same way. A code outside the closed\nvocabulary reads `failed` with the native code in `condition.source`. The next turn clears it when it\nstarts, whether the host or the TUI owns that turn. The host also records every work event of its\nsession, such as a token or a tool call, as presence `activeAt`, whether the host or the TUI owns the\nturn. A turn that stopped advancing therefore shows the age of its last event, `\xB7 active 40m ago`,\nbeside a heartbeat that is still fresh. `cotal_inbox` pulls only buffered quiet\nambient from that host-owned queue; its shared optional `peek` argument is supported, so `peek: true`\nshows those messages without clearing them.\n\n## Model limits\n\n`--model` is passed to Jcode's session-level Harness API model selector. Jcode validates the model\nagainst the active provider, and an accepted selection becomes the session pin and the seat's model\nlabel. The connector reports the provider route actually serving that model to presence, and\n`cotal ps --wide` and `--json` show it as `provider`. The connector does not require `RuntimeInfo.model`\nto echo that pin immediately because the runtime field can temporarily report the previous model\nafter selection.\n\nModel startup refusals are named without exposing provider output: `model_prefix_rejected` means a\n`provider/model` value was supplied where the Harness API requires a bare id, `model_refused` means\nJcode rejected that bare id, and `model_mismatch` means a requested variant could not be tied to one\nactive provider route for the selected model. `private_state` names a different step: the seat's\nprivate home, its credential mirror, or its short socket alias could not be prepared.\n\nStored sessions have their own refusals. `sessions_enumeration_failed` means listing the home's\nprior sessions killed the harness. `sessions_unwritable` means the home's `sessions/` directory\nexists but will not take a write: the harness would accept the seat and die only while persisting\nits first session, so the connector refuses before that launch and names the directory and the\nerrno. Fix the directory's permissions on the seat's private state and start again; the connector\nnever repairs or widens them itself. A missing `sessions/` directory is a first launch and is left\nalone.\n\n`cotal models --agent jcode` reads the declared catalog from the operator Jcode home's\n`config.toml`: each provider with `model_catalog = true`, its `[[providers.<name>.models]]` ids,\nand any declared `reasoning_efforts`. This is the same config Jcode copies into a private managed\ninstance. The command fails loud when the file is unreadable, malformed, or enables a catalog\nwithout model entries.\n\nThe listed effort tiers are display declarations, not Jcode runtime capabilities. Jcode's named\nmodel config does not assign effort support per model. A named provider profile enables it through\nprovider configuration or Jcode's model-family detection. `cotal models` prints\nthat caveat inline as `variants (declared, not provider-verified)` beside each configured tier list,\nso it cannot be missed by reading only the model rows. Providers can reject a tier the file names,\nso launch remains the authority: Jcode applies the requested value and a provider rejection ends the\nlaunch. `--refresh` does not turn this local declaration into a live probe.\n\nThe Harness API can set a requested effort but cannot read an effective effort back. Its runtime\nidentity reports provider, model, and routes only; no reply or event carries the applied tier. Cotal\ntherefore records the accepted request and does not relabel it as an observed effect.\n\n`--variant` is the session's **reasoning effort**, applied after the model and before the seat's\nfirst turn, so a seat never serves a turn at an effort nobody chose. A persona's `variant:` is the\ndefault and `--variant` overrides it, the same way `model:` and `--model` work:\n\n```bash\ncotal spawn --agent jcode --model gpt-5.6-sol --variant high\n```\n\nWhich tiers exist depends on the provider, profile, and model. The connector does not carry a copy\nof those rules. After model selection it uses the accepted session pin with Jcode's runtime provider\nand route catalog to verify one active provider route, then passes the tier to that route. For a\nvariant-only launch, where there is no requested pin, the runtime model identifies the selection.\nA duplicate model id on another route cannot receive the setting by accident. A rejected tier ends\nthe launch with a safely parsed accepted ladder when Jcode supplies one. A verified route with no\nreasoning-effort surface also ends before the first turn, but reports unsupported capability instead\nof suggesting another tier. Arbitrary provider rejection text stays private. Omit `--variant` to\nkeep Jcode's configured default.\n\nIf the mandatory readiness turn receives a provider `invalid_request` refusal for a model id or\nreasoning-effort value, the launch diagnostic names only the provider error code and rejected\nvalue. Other provider response text remains scrubbed, so an external observer/UI can correct\nconnector-visible input without exposing private harness output.\n\nThe following fail loud before a new session is provisioned where the manager can preflight them,\nor at connector launch as a backstop:\n\n- **Exact-session continuation:** a Cotal seat owns a new private Jcode instance. Attaching it to\n  a session an operator or another seat still owns would violate that ownership boundary. Use\n  `--resume`, which gives the seat its own fork.\n- **Tool sharing:** Jcode resolves its MCP configuration from several global and project sources.\n  The connector owns a private configuration containing only `cotal`, rather than claim a chosen\n  subset can be safely merged.\n- **Launch options:** the connector does not map arbitrary flags/config into the Harness API.\n- **Containers:** the current deploy image does not bundle Jcode, so there is no containerized Jcode connector today.\n\n## Security limits\n\nThe private home protects against accidental sharing and stale session selection; it is not an\nOS-user isolation boundary. A hostile process running as the same user can still read that user's\nfiles or inspect another same-user process. Use OS/container isolation where peers must be mutually\nhostile.\n\nThe model can receive remote peer messages and Jcode is an autonomous coding harness. Treat its\nprovider credentials, filesystem access, and network capability as the privileges of the OS user\nrunning the seat. Cotal's spawn capability governs who may create a seat; it is not a sandbox for\nwhat a model can be persuaded to do after creation.\n"
+      "body": "# Connect Jcode (beta)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[Jcode](https://github.com/1jehuang/jcode) joins a Cotal mesh as a lateral peer. The connector\ncreates one private Jcode Harness API instance per seat, one Jcode session inside it, and exposes\nthe normal `cotal_*` tool surface through Jcode's documented stdio MCP configuration.\n\n**Beta** means the supported path is deliberately narrow: a fresh private session, a fork of one\nof your own sessions (`--resume`), prompt injection, presence, managed start/stop, requested\nreasoning effort, and an attached TUI work. Features that do not preserve that private session's\nmesh surface fail loud: exact-session continuation, `--share-tools`, and connector `--opt` values\nare not supported.\n\n## Install\n\nThe connector is seeded with the Cotal CLI. Jcode's released Harness API bridge is a Unix-socket\nsurface, so Windows is not supported. Managed seats run on Linux, macOS, and the BSDs.\nInstall Jcode 0.78.1 or later from its GitHub release and make the binary available as `jcode` on `PATH`:\n\n```bash\njcode version --json\ncotal spawn --agent jcode\n```\n\nIf an older Cotal installation is missing the connector, run `cotal ext seed --repair` (or\n`cotal ext add @cotal-ai/connector-jcode`). This connector intentionally uses the released\nbinary's `api-bridge` command; it does not require a Rust checkout.\n\n## Spawn it\n\n```bash\ncotal spawn --agent jcode\ncotal spawn reviewer --agent jcode -d\ncotal spawn --agent jcode --model gpt-5.6-sol --prompt \"Review the current change.\"\nCOTAL_DEFAULT_AGENT=jcode cotal spawn\n```\n\nA detached seat is managed normally: `cotal ps`, `cotal attach`, and `cotal stop` control the\nsame process the connector starts. In a terminal, Jcode opens on the managed session. With piped\noutput it stays headless; set `COTAL_JCODE_TUI=1` or `COTAL_JCODE_TUI=0` in the environment of the\nprocess building the launch to override that choice. For a detached spawn, that is the manager's\nenvironment.\n\n## How it binds\n\nJcode's stable integration surface is the **Harness API**: protocol-v1 NDJSON over a Unix socket.\nThe connector launches a **private instance** with `@1jehuang/jcode-sdk`'s `launchInstance()` and\nattaches only to that instance's own socket:\n\n- `launchInstance()` starts a private `JCODE_HOME`, runtime directory, daemon, and `api-bridge`;\n  the connector holds the process handle first-hand and closes that instance with the Cotal seat.\n  This gives each managed Cotal peer one owned session and prevents it from seeing or changing\n  the operator's live Jcode sessions.\n- Attaching to an **operator-run** `jcode api-bridge` shares the operator's live session\n  inventory. That is appropriate for a dashboard or editor integration, but not a managed Cotal\n  seat: stop, prompt injection, and session selection could act on the operator's work. The\n  connector never attaches to an operator bridge.\n- A managed seat **never updates its own binary**. Jcode's background updater restarts the\n  process tree when it lands a release; that restart drops the seat's TUI, which is the only\n  connection the Jcode server counts as a client, and nothing re-attaches, so the server's idle\n  reaper takes the seat down five minutes later in the middle of a turn. The seat's version is\n  whatever is on `PATH` when you spawn it, and it stays that version for the seat's life. Update\n  deliberately, between seats, not under a running agent.\n\nOn a graceful stop **and** on a startup failure, the connector proves the private daemon tree is\nactually gone rather than trusting the SDK's registry-keyed stop (which is a silent no-op when the\n`servers.json` socket path does not match verbatim): it reads the PIDs the private home itself\nrecords, sends a bounded SIGTERM, escalates survivors to an exact-PID SIGKILL, and reports a\nfailed stop instead of a clean one if any recorded process survives. It never signals by name, so\nteardown can only ever reach the seat's own tree.\n\nA seat that dies without that teardown, from a manager restart or a kill past the grace window,\nleaves its Jcode server running. The server has a process group of its own and carries no\n`COTAL_NAME`, so a name-keyed reap does not reach it, and it holds the seat's runtime directory\nuntil its own five-minute idle timer expires. Each launch records its identity nonce and its host\nprocess in the private home, and the seat's next launch stops the tree that record names. The\nrecorded host is the gate: while it is still alive the seat is still serving, so nothing is\nsignalled and the second launch meets Jcode's own runtime-directory lock instead.\n\nThe private Jcode home lives under `<manager-workspace>/.cotal/jcode/`. It is unique per\nspace/name and is owner-only. Jcode's own credential inheritance is used for the private instance,\nso provider logins work without copying its transcript/config tree into the seat. The spawned\nJcode process does not inherit `COTAL_*` values or the Cotal launch-material pointer.\n\nBecause the home is keyed by space and name, a seat respawned under the same space, name, and\nmanager workspace lands in the same home, and the connector automatically continues the\nnon-archived Jcode session there that was recorded for the seat's working directory and holds the\nlargest transcript, since that is the session carrying the memory a restart would otherwise throw\naway. A seat spawned under a fresh name keys a different home and starts with an\nempty transcript, so keep the same name when you want a replacement seat to continue where the\nprevious one stopped. This automatic continuation is a relaunch of the seat's own private session;\nit is separate from `--resume`, which forks an outside session into the seat (below). The short\nsocket alias the connector derives from that home is reclaimed at every launch, so a name a stopped\nseat used stays launchable.\n\n`cotal spawn --resume <id>` forks session `<id>` from your own Jcode home (`JCODE_HOME`, or the\ndefault Jcode home) into the seat's private home before the seat's instance starts. The Harness API\nhas no fork call, so the connector does what Jcode's own split does: it writes a new session whose\nparent is the source and which carries the source's messages, compaction state, system prompt, and\nmodel. The seat gets a new session id and its briefing as the first turn after that history. The\nsource files are only read, so the source transcript is never appended to. A session id with no\nreadable transcript, or one whose snapshot or journal holds fields Jcode cannot load, is refused\nbefore the seat launches; every carried message, content block, and compaction state is checked\nagainst Jcode's own schema, and the refusal names the field. Jcode stores its counts as u64 and\nreads one only as a plain decimal integer, so a count above what a JavaScript number holds is copied\nbyte for byte, and one above the u64 range or spelled with a fraction or an exponent (`1e3`, `1.0`)\nis refused. The source may be live: the connector\nreads it until two reads agree and every journal line is newer than the snapshot, so a Jcode\ncheckpoint caught mid-way is neither lost nor applied twice, and a session that keeps changing is\nrefused with a request to retry. A seat relaunched under the same name continues its\nfork rather than forking again, without reading the source, which may since have been deleted. The\nseat's briefing is recorded separately from the fork, so a first launch that fails after forking\nstill briefs the seat on its next launch. The seat records the source session id, its title, and a\nSHA-256 of the snapshot and journal it read, prints them when it forks, and the manager reads that\nrecord into the seat's resume document, so `cotal ps --wide` shows them. The manager keeps a title\nof at most 1024 characters, so a source with a longer title is refused before the seat launches.\n\nConnector diagnostics are written both to the spawning terminal and to an owner-only\n`<private-home>/logs/connector-<timestamp>-<pid>.log`, so a failed launch remains inspectable after\nthe manager's launch error scrolls away. Public startup failures stay scrubbed to allow-listed\ncodes rather than arbitrary Harness API messages.\n\nCredential mirroring is mandatory for managed Jcode seats: each launch atomically refreshes the\nallowlisted Jcode, provider-config, and external-login destinations, and removes a destination when\nits source login was removed. Cleanup addresses only that explicit inventory; transcripts, MCP\nconfiguration, logs, and other private-home state are untouched. Copy, mkdir, and removal walk the\nparents with `O_NOFOLLOW`, then publish, create, or unlink the leaf through the pinned parent rather\nthan through a path the kernel re-walks. Replacing a walked directory with a symlink cannot write,\ncreate, or delete a namesake outside the private home.\n\nTwo mechanisms provide that pin. On Linux the leaf is named `/dev/fd/<fd>/<name>`, the openat and\nunlinkat equivalent Node does not expose, after `/dev/fd/<fd>/.` is proven to traverse. macOS mounts\n`/dev/fd` but has no subpath namespace under a descriptor, so there the connector pins the parent as\nthe process working directory instead: a single-component name resolves from that directory's inode\nand no ancestor is walked again. Entering by path is verified rather than trusted, because `chdir`\ntakes a path: the entered directory's inode must equal the inode of the descriptor opened a moment\nearlier, and a mismatch is refused by name. The working directory is restored on every exit,\nincluding the refusing ones. If neither pin is available, the connector throws a named error and\nmirrors nothing. Once a pin holds, `ENOENT` on a child means the mirror path is absent.\n\nThere is no credential-free opt-out today because the private instance must reproduce the operator's\ncurrent provider-login state rather than silently start with stale or partial authorization.\n\nIf a provider failure closes the private Harness API connection during a mesh-driven turn, the\nconnector leaves that turn's inbox batch unacknowledged and opens one bounded recovery window for a\nprivate replacement connection to the same session. The window lasts 60 seconds from the close, and\nstopping the broken private tree counts against it. A transient launch or attach failure retries\ninside that window, so a loaded host gets the same result as a fast one without creating an\nunbounded connector relaunch loop. The seat reports `waiting` while it reconnects, then redrives\nthat unacknowledged batch only after the session attaches. Each failed replacement must be proven\nstopped before another launch. A permanent Harness refusal, including an invalid request, missing\nsession, protocol mismatch, missing binary, or socket permission denial, ends the seat immediately;\nanother launch cannot change it. An unprovable teardown, the recovery window expiring, or a second\ndisconnect after a successful replacement also ends the seat. When a turn failed on a Harness error\nand no turn has succeeded since, whether the host or the TUI owned it, the connector line that ends\nthe seat this way also names that error as `last turn error: <message>`, so the manager's\n`seat reaped:` line carries it without a read of the seat's private log. The reap line keeps only the\nfirst 240 characters, so that field comes before the error of a failed recovery, which then reads\n`recovery error: <message>`. An unrecognized Harness SDK error\ncode remains transient by default and retries inside the same bounded window; new permanent codes\nmust be added to the explicit classifier and its exact-count regression.\n\nJcode currently supports **stdio** MCP servers. The connector writes only its own `cotal` entry to\nthe private `JCODE_HOME/mcp.json`; it starts a stdio MCP bridge for that entry and relays its calls\nto the host's one `MeshAgent`. The Jcode/MCP child receives a per-launch relay capability, but not\nthe Cotal broker credential or its launch-material pointer. Jcode also overlays project\n`.jcode/mcp.json`, `.mcp.json`, and `.claude/mcp.json`; a managed launch **refuses** a workspace\ncontaining any of those files, because one could replace the `cotal` bridge or add tools that were\nnot explicitly shared. Operator MCP configuration is isolated in the private home and project MCP\nconfiguration is not supported yet.\n\nBefore the seat joins the mesh, the host runs a mandatory Jcode turn that calls\n`cotal_orientation`. Jcode loads MCP tools asynchronously; its first turn can use the pre-MCP tool\nsnapshot immediately before Jcode rebuilds that snapshot. The host repeats the identical proof once\nin that case. A second absence fails the launch, so a bridge that never comes up remains a loud\nfailure rather than an agent that is present but mute. The persona is already in that transcript as\na no-reply message; the spawn `--prompt` is not submitted until after join. While the proof is in\nflight the connector log names `pre-join readiness` and the bound. That in-flight line only means\nstartup reached the gate; it is not a hang, a missing prompt, or a provider refusal by itself.\nAfter the turn, a second line names the outcome and is what separates those cases:\n`orientation proved; joining with no spawn --prompt` or `joining, then submitting the spawn\n--prompt` when the proof passed; `provider refusal` when the provider rejected the turn; `timeout`\nwhen the bound fired. A genuine hang that never returns and never hits the bound has no outcome\nline. A one-line log with no route line is not that signal. The proof itself is bounded to the\nsame three minutes the connector declares to the manager (`readinessTimeoutMs` is the exported\n`JCODE_READINESS_TIMEOUT_MS`). Tests may shorten the host bound through\n`COTAL_JCODE_READINESS_TIMEOUT_MS`; that override is not an operator setting and does not change\nthe window the connector declares to the manager. The bound is a call-observation deadline: the\nhost proves readiness on the orientation `tool_done` event as it arrives, without waiting for\n`turn_done`. If that call never arrives inside the window the host exits `readiness_timeout` and\nnever joins, rather than working invisibly. That teardown does not wait for the in-flight turn:\nit kills the private Jcode tree and discards whatever that turn had generated. Nothing from it\nis recoverable; inspect the seat connector log for the timeout outcome, then spawn again. The\ntimeout line names whether the orientation call was observed. A seat that already made the call\njoins even if that proof turn is still open; the host does not destroy a functional session\nsolely because `turn_done` has not arrived. The manager's wait can still report `uncertain` when\njoin itself is slow after a passing proof; that is not a cleanup verdict, and it is not the same\nas a host `readiness_timeout`. Use `cotal attach <name>` or `cotal ps` to inspect an `uncertain`\nlaunch. The\nhost then waits for the mesh connection and presence bind to complete before it delivers a notice\nthat the bootstrap orientation predates the join and that a new orientation is live context. During\na broker outage, it stays waiting and sends no connected notice.\n\nA seat launched with a spawn `--prompt` gets that notice as a no-reply append; the prompt is still\nthe seat's first driven turn. A seat launched with no spawn `--prompt` has nothing else to schedule\na turn after join, so the notice is delivered as the seat's first driven turn instead of a no-reply\nappend: the same dispatch boundary and one-shot rule the startup prompt uses, so the seat's final\nstartup state is never an unread append.\n\nA refused post-join notice sent as a no-reply append is logged without ending the joined session.\nWhen the notice is instead the startup turn (no spawn prompt), a refusal on that turn is handled\nthe same way any other startup-prompt failure is: logged and retried, never fatal to the seat. The\nstartup prompt (or, with no spawn prompt, the notice standing in for it) stays pending while the\nnative session is busy or its bridge reconnects. Once the host invokes the request, it consumes\nthat prompt and does not retry it after an ambiguous error or close. This prevents a second\nsubmission; it cannot prove whether the first request executed.\n\nThe startup prompt excludes the automatic inbox. Messages buffered before it run in the following\nturn, including ordinary channel traffic held in `dnd`. Quiet-channel traffic remains available only\nthrough an explicit inbox pull. The connector log names a startup prompt waiting on in-flight\nsteering and a turn deferred because native state changed during that wait.\n\n## Event plane\n\nA spawned seat publishes run boundaries, assistant text, reasoning,\nand tool starts and ends on `events.<owner>.<actor>`. Tool arguments and results are not published.\nThe channel and grant rules are the same as the other connectors; see\n[Connect Claude Code](connect-claude.md#event-plane) for how to grant and read one.\n\nJcode's live Harness API reports token-sized text and reasoning deltas, but that stream cannot be\nread again after a host crash. The connector therefore reads Jcode's native append-only session\njournal under the seat's private home. The journal supplies a durable byte cursor and is keyed by\nthe Jcode session id, which is also the AG-UI thread id. A restarted seat continues from the cursor\nstored in its event write-ahead log and does not republish records already acknowledged.\n\nIf Jcode checkpoints its journal, the connector validates the saved session snapshot and ends the\ninterrupted event observations with `RUN_ERROR`. Open tool observations end before this error; this\ndoes not claim that their executions completed. The seat stays up while the next journal is absent,\nincluding during a long tool call. The reader keeps its previous cursor until it can read the new\njournal from its beginning. It does not reconstruct missing output from the snapshot. A tool result\nwhose start was not observed also ends the run with `RUN_ERROR`, not an invented tool start or an\nunpaired end. Like every published run error, both carry only the fixed message `run failed`: the\nconnector's codes `jcode_journal_fold` and `jcode_tool_start_missing` do not leave the seat. On restart, open tools are restored from the event WAL.\n\nA missing journal without a valid snapshot for the same session remains an emitter failure.\nMalformed cursors, invalid complete records and filesystem access refusals are not checkpoints.\n\nWhen the seat's mesh connection drops and the endpoint is rebuilding it, event publishing waits\nuntil the connection is live again and then publishes the queued records in order. The seat stays up\nthrough the outage. If the seat is stopped before the connection returns, the wait ends and the\nconnector log records `AG-UI emitter stopped`. The unpublished records stay in the journal\nbehind the stored cursor, and the next start publishes them. Any other emitter failure still stops\nthe seat with exit code 1.\n\nThe journal records settled message blocks rather than live deltas. Text and reasoning therefore\narrive per persisted block, and tool activity arrives when Jcode persists the tool-use and result\nblocks. User prompt text is not republished onto the event channel. The launcher sets\n`COTAL_EVENTS` by default; pass `--no-events` to opt out.\n\n\nFor a foreground launch, the TUI opens as soon as the session is ready, before the readiness turn,\nso it streams boot activity instead of leaving the terminal blank. Presence still begins only after\nthe readiness proof passes. An inbound peer message then wakes a Harness API turn. A directed message\nthat arrives while the Harness session is busy (a Cotal-owned `run()`, a TUI-owned turn, or an\nadvisory idle pulse between tool rounds of a still-open Cotal-owned run) enters Jcode's session-owned\nsoft-interrupt queue. Ambient channel traffic stays buffered for the next turn. The host marks\npresence working while the session is busy, publishes `activity` naming automatic queue depth and age\nwhile anything remains uncommitted, and acknowledges every initial or soft-interrupted inbox id only\nafter that containing turn succeeds. A failed Cotal-owned turn or private Harness replacement leaves\nthose ids unacknowledged for mesh redelivery. When the Harness reports the failure itself, such as a\nprovider `rate_limit`, the host relays its error code as the presence `condition`, so the roster and\n`cotal ps` read `waiting (rate_limit for 2m)`. A turn the TUI owns is covered too: its failure arrives as an\nunsolicited Harness error frame, and the host relays that the same way. A code outside the closed\nvocabulary reads `failed` with the native code in `condition.source`. The next turn clears it when it\nstarts, whether the host or the TUI owns that turn. The host also records every work event of its\nsession, such as a token or a tool call, as presence `activeAt`, whether the host or the TUI owns the\nturn. A turn that stopped advancing therefore shows the age of its last event, `\xB7 active 40m ago`,\nbeside a heartbeat that is still fresh. `cotal_inbox` pulls only buffered quiet\nambient from that host-owned queue; its shared optional `peek` argument is supported, so `peek: true`\nshows those messages without clearing them.\n\n## Model limits\n\n`--model` is passed to Jcode's session-level Harness API model selector. Jcode validates the model\nagainst the active provider, and an accepted selection becomes the session pin and the seat's model\nlabel. The connector reports the provider route actually serving that model to presence, and\n`cotal ps --wide` and `--json` show it as `provider`. The connector does not require `RuntimeInfo.model`\nto echo that pin immediately because the runtime field can temporarily report the previous model\nafter selection.\n\nModel startup refusals are named without exposing provider output: `model_prefix_rejected` means a\n`provider/model` value was supplied where the Harness API requires a bare id, `model_refused` means\nJcode rejected that bare id, and `model_mismatch` means a requested variant could not be tied to one\nactive provider route for the selected model. `private_state` names a different step: the seat's\nprivate home, its credential mirror, or its short socket alias could not be prepared.\n\nStored sessions have their own refusals. `sessions_enumeration_failed` means listing the home's\nprior sessions killed the harness. `sessions_unwritable` means the home's `sessions/` directory\nexists but will not take a write: the harness would accept the seat and die only while persisting\nits first session, so the connector refuses before that launch and names the directory and the\nerrno. Fix the directory's permissions on the seat's private state and start again; the connector\nnever repairs or widens them itself. A missing `sessions/` directory is a first launch and is left\nalone.\n\n`cotal models --agent jcode` reads the declared catalog from the operator Jcode home's\n`config.toml`: each provider with `model_catalog = true`, its `[[providers.<name>.models]]` ids,\nand any declared `reasoning_efforts`. This is the same config Jcode copies into a private managed\ninstance. The command fails loud when the file is unreadable, malformed, or enables a catalog\nwithout model entries.\n\nThe listed effort tiers are display declarations, not Jcode runtime capabilities. Jcode's named\nmodel config does not assign effort support per model. A named provider profile enables it through\nprovider configuration or Jcode's model-family detection. `cotal models` prints\nthat caveat inline as `variants (declared, not provider-verified)` beside each configured tier list,\nso it cannot be missed by reading only the model rows. Providers can reject a tier the file names,\nso launch remains the authority: Jcode applies the requested value and a provider rejection ends the\nlaunch. `--refresh` does not turn this local declaration into a live probe.\n\nThe Harness API can set a requested effort but cannot read an effective effort back. Its runtime\nidentity reports provider, model, and routes only; no reply or event carries the applied tier. Cotal\ntherefore records the accepted request and does not relabel it as an observed effect.\n\n`--variant` is the session's **reasoning effort**, applied after the model and before the seat's\nfirst turn, so a seat never serves a turn at an effort nobody chose. A persona's `variant:` is the\ndefault and `--variant` overrides it, the same way `model:` and `--model` work:\n\n```bash\ncotal spawn --agent jcode --model gpt-5.6-sol --variant high\n```\n\nWhich tiers exist depends on the provider, profile, and model. The connector does not carry a copy\nof those rules. After model selection it uses the accepted session pin with Jcode's runtime provider\nand route catalog to verify one active provider route, then passes the tier to that route. For a\nvariant-only launch, where there is no requested pin, the runtime model identifies the selection.\nA duplicate model id on another route cannot receive the setting by accident. A rejected tier ends\nthe launch with a safely parsed accepted ladder when Jcode supplies one. A verified route with no\nreasoning-effort surface also ends before the first turn, but reports unsupported capability instead\nof suggesting another tier. Arbitrary provider rejection text stays private. Omit `--variant` to\nkeep Jcode's configured default.\n\nIf the mandatory readiness turn receives a provider `invalid_request` refusal for a model id or\nreasoning-effort value, the launch diagnostic names only the provider error code and rejected\nvalue. Other provider response text remains scrubbed, so an external observer/UI can correct\nconnector-visible input without exposing private harness output.\n\nThe following fail loud before a new session is provisioned where the manager can preflight them,\nor at connector launch as a backstop:\n\n- **Exact-session continuation:** a Cotal seat owns a new private Jcode instance. Attaching it to\n  a session an operator or another seat still owns would violate that ownership boundary. Use\n  `--resume`, which gives the seat its own fork.\n- **Tool sharing:** Jcode resolves its MCP configuration from several global and project sources.\n  The connector owns a private configuration containing only `cotal`, rather than claim a chosen\n  subset can be safely merged.\n- **Launch options:** the connector does not map arbitrary flags/config into the Harness API.\n- **Containers:** the current deploy image does not bundle Jcode, so there is no containerized Jcode connector today.\n\n## Security limits\n\nThe private home protects against accidental sharing and stale session selection; it is not an\nOS-user isolation boundary. A hostile process running as the same user can still read that user's\nfiles or inspect another same-user process. Use OS/container isolation where peers must be mutually\nhostile.\n\nThe model can receive remote peer messages and Jcode is an autonomous coding harness. Treat its\nprovider credentials, filesystem access, and network capability as the privileges of the OS user\nrunning the seat. Cotal's spawn capability governs who may create a seat; it is not a sandbox for\nwhat a model can be persuaded to do after creation.\n"
     },
     {
       "slug": "connect-opencode",
@@ -19657,7 +19671,7 @@ var DOCS_BUNDLE = {
       "title": "The control surface",
       "kind": "Concept (informative)",
       "summary": "Cotal once had a privileged control rail: a fixed set of named service tiers (self / manager / admin / delivery) on their own ctl.",
-      "body": '# The control surface\n\n> **Concept** (informative) \xB7 **For:** operators and client authors who want to know how the manager and other daemons are driven \xB7 **Normative:** [SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)\n\nCotal once had a privileged control rail: a fixed set of named service tiers\n(`self` / `manager` / `admin` / `delivery`) on their own `ctl.*` subjects, with the manager\nas a special case the broker recognised by name. That rail is gone. Everything that serves\nstructured commands now, the manager, the delivery daemon, a wrapped MCP server, a\nthird-party service, is an ordinary **endpoint**: a daemon that registers a service\nidentity, publishes its contracts, and answers `describe`. `manager` is an endpoint name\nlike any other; no subject, envelope, or grant in this surface knows it specially. The\nmanager is a service on the mesh, not an authority over it: it holds only the capability\nrows its callers grant it, and serves over a scoped credential.\n\n## The `ep` rails\n\nOne kind, `ep`, carries every request under a mode token that says where the request\nroutes, never which verb it is (the verb rides the envelope): `one` (queue-group\nanycast, one and only one class member), `all` (scatter, every instance), and `inst` (one instance by its\nstable address). Replies come back on a `reply` rail keyed to the serving instance and its\nepoch. Around these sit the sibling planes the composites use: per-goal events, timers,\nsessions, and the journal that holds durable facts. Every request carries the caller as\nthree forge-locked tokens, `owner`, `actor`, and lifecycle `uid`, plus an unguessable\nnonce, so the broker polices who is calling in the subject grammar itself. See\n[SPEC \xA713.2](../SPEC.md#132-grammar) for the grammar and [\xA713.5](../SPEC.md#135-verbs) for\nthe verbs (`call`, `cast`, `watch`, `claim`, `scatter`).\n\n## Lifecycle identity\n\nA principal `owner.actor` is a reusable routing alias: a despawn frees the actor name and a\nlater spawn may legitimately reuse it, so the alias alone is never authority. Two further\ncoordinates make an identity durable: a **lifecycle uid**, an unguessable, never-reused id\nfor one managed lifecycle under a principal, and a **process epoch**, the fenced ownership\nepoch of the process currently animating it, advanced on every restart or takeover. At most\none live epoch owns an identity, and a superseded epoch must stop serving. Durables and\ncredentials key on the lifecycle uid, not the reusable name, which is what lets a\nsupervised restart recover the same lifecycle instead of minting a new one. See\n[SPEC \xA713.1](../SPEC.md#131-lifecycle-identity) and [identity & auth](identity-and-auth.md).\n\n## Service discovery\n\nNo client has compile-time knowledge of any endpoint\'s commands. `cotal describe\n<endpoint>` resolves a registered endpoint\'s command set off the wire: the reserved\n`describe` command answers the registered contract digests, the schemas are fetched from the\nspace\'s content-addressed contract store, recompiled, and verified against those digests.\nEach command prints with its capability class and targeting shape. `cotal invoke <endpoint>\n<command> --args \'<json>\'` then calls one command by name, validating the arguments as they\nwill be sent (JSON drops a key whose value is undefined) against the fetched input schema before\npublish. A refusal at that check means nothing was sent, and it is marked `not-executed`. A\nsigned-in user invokes the same surface through their bearer, and the broker enforces each\ncommand\'s existing capability grant. A manager alias supplied through `--name` resolves through\nits name-keyed `inspect` command, so an authorized targeted call does not need the manager-wide\n`ps` enumeration grant. Every built-in manager command uses this\nsame trust chain, so there is nothing the built-ins can reach that a described contract cannot. The registered\n`auth` endpoint is describable the same way `manager` is: `cotal describe auth` lists\n`retire-lifecycle` and its exact-mode target shape.\nSee [SPEC \xA713.7](../SPEC.md#137-contracts-and-discovery) and [cli.md](cli.md).\n\nThe manager\'s `resolve-cwd` command is in the `manager.spawn` capability class. It accepts an\nabsolute path on that manager\'s host and returns its canonical directory plus the host name. It\nrefuses a relative, missing or non-directory path with `failed-precondition`; it creates nothing.\n`spawn` applies the same check at admission, before any credentials or durables are minted.\n\n### Inspecting a managed name\n\nManager `inspect` keeps its successful response as the live managed-agent row. A live hit does\nnot read durable lifecycle state, so a temporary records-store failure cannot break inspection of\nan agent the manager currently holds.\n\nOn a live miss, a static manager point-reads its durable slot row. A name with no slot, or a slot\nwhose phase is `retired`, remains `not-found`. A nonterminal slot returns\n`failed-precondition` with `error.details[].kind =\nai.cotal.manager.static-slot-observation`. The detail carries the slot\'s `slotPhase`,\n`owner`, `actor`, `slotLifecycleUid`, `cleanupComplete` when recorded, and `slotRevision`. It\nthen carries the separate lifecycle head\'s `headState`, `headOp` when present,\n`headLifecycleUid`, and `headRevision`. Head fields are absent when provisioning has not written\nthe lifecycle head yet.\nThe error message carries the same diagnostic summary so string-only operator paths do not hide\nthe structured detail.\n\nA slot row records the manager instance that owns it. In a space with more than one manager, the\nclass queue can hand `inspect` to an instance that does not host the name. When the row names a\ndifferent instance and is not `retired`, the miss returns `failed-precondition` with the same\ndetail plus `ownerInstanceId`, which names the only manager that can act on it. The message names\nboth instances, so a caller that reads only the string can tell it from `not-found`. A sibling\'s\n`retired` row remains `not-found`.\n\nThe slot is read before the head. These records do not form one atomic snapshot, so the detail\nalso carries `readOrder: ["slot", "head"]` and `consistency: "ordered-not-atomic"`. A head can\nadvance between the reads. The issuance gate is not projected because the retirement operation\nneeded for this diagnosis is already recorded on the head, and reading a third record would add\nanother non-atomic edge without changing the per-name result.\n\nIf either durable read fails or exceeds its bound, the miss returns `unavailable` with\n`ai.cotal.manager.static-slot-read-failed` rather than claiming the name is absent. That detail\nnames the inspected `name`, the failed `record` (`slot`, `head`, or `slot-or-head` when the layer\ncannot distinguish them), and `operation: "read"`. User-auth managers do not own `mgrslot` rows,\nso their inspect misses remain live-map reads.\n\nFor Linux custodied seats, retirement requires the runtime\'s process-exit evidence before\nfreeing the alias or deleting its credentials and delivery state. Socket loss alone is not\nproof of exit. The runtime retains the record captured at launch or adoption so a clean\ncustodian exit can unlink its file without losing the recorded boot and process identities.\nIf the file is missing, reaping uses that retained record and the existing kernel identity\nchecks. An unknown reference without either record refuses cleanup. Reused process ids\nare never signalled on the strength of the old record.\n\n### Listing the durable slots\n\nManager `slots` (`manager.read`, untargeted) lists the durable static slot rows this manager\nowns. Only static managers hold these rows: a user-mode or open manager answers\n`failed-precondition`, and a manager whose durable store is not standing answers `unavailable`.\nEach row carries the same `readOrder` and `consistency` fields `inspect` uses, because the list\nis read the same way: torn across rows as well as within each row\'s slot/head pair. A `retired`\nrow is never listed. `live` reflects the manager\'s live roster at render time, not the durable\nrow.\n\n## Spawn is a goal\n\nLong-running commands are **actions** ([SPEC \xA713.6](../SPEC.md#136-composites)): the caller\nsubmits with a client-generated `goalId` and a request fingerprint, the endpoint records a\ndurable accept or reject decision, progress rides per-goal events, and the work ends in one\nterminal outcome (`succeeded`, `failed`, `cancelled`, `expired`, or `uncertain`). Spawn is\nthe reference case. Rather than block the caller for up to 30 seconds while an agent comes\nup, the manager accepts the goal and returns the allocated identity at once:\n\n```json\n{\n  "name": "reviewer-2",\n  "owner": "u_...", "actor": "reviewer", "uid": "...",\n  "goalId": "...", "fingerprint": "...",\n  "readinessDeadlineMs": 30000,\n  "executor": { "lifecycleUid": "...", "epoch": 3 }\n}\n```\n\nThe name is the one actually allocated: a persona-derived collision is auto-numbered\n(`reviewer`, then `reviewer-2`), while a hard-pinned `--name` that collides with a live\nagent is refused at accept, before anything is minted. Auto-numbering never hands out a numbered\nname it has already issued in that manager process, even after the agent holding it is gone, so\na collision takes the next number. Only numbering consults that history: a hard-pinned `--name`,\nor a persona whose own name is a numbered string, takes that name whenever it is free, and\nnumbering does not skip a string such a spawn held before. The triple plus `goalId` let the\ncaller follow progress (connector handoff, process launched, presence join) and reconcile\nlater against the exact instance that accepted. Presence within the manager\'s default\n30-second readiness window, or a connector\'s declared bounded window, settles the goal\n`succeeded`; an early process exit is `failed`; the window passing with neither is `uncertain`,\na bounded, durable outcome that a later `ps` or status read settles against the live roster.\n`uncertain` is a real terminal outcome, not an absence and not a silent hang. It carries the\ndiagnosis of whoever owned the deadline: for a launch that\nnames the agent and says to inspect it rather than re-issue, since re-issuing after a launch\nthat in fact succeeded mints a duplicate. A committer that supplies no diagnosis falls back to\n"the success signal did not arrive within the readiness deadline". The agent\'s own eventual\nstate is then observable on its presence record.\n\nThe acceptance carries that exact `readinessDeadlineMs`. A synchronous follower treats its own\nrequest deadline as a floor and waits through the accepted readiness budget plus delivery margin,\nso a connector-specific slow boot cannot be reported as a caller timeout while the manager is\nstill legitimately waiting for its terminal.\n\nA spawn that is **refused** because a lifecycle barrier already holds the actor (a frozen\nissuance gate, a retiring alias, a retired uid) is not a wait-timeout. The manager already\nknows the blocked op (`registration` / `retirement` / `activation` / `takeover`), the head\nstate (`active` / `retiring` / `retired`), the `opId` holding it, and the remedy when one\nexists (`retry`, `cotal reconcile-gate`). Those facts ride `error.details[]` as\n`kind = ai.cotal.ep.lifecycle-blocked` and are also appended to the error string, so a\ncaller that only prints `error.message` still sees them. A connector that collapses the\nrefusal to "startup failed (unknown)" or a SPEC 13.6 wait-timeout is hiding a knowable\nstate, not reporting a missing one.\n\n## Instance routing\n\nA space can run more than one manager. Each manager persists a stable logical instance id\nacross restarts and advances its process epoch when it comes back, so callers address a\nspecific manager without caring which process currently serves it. A start serves only at the\nepoch its own registration committed, never at the epoch of a later start of the same instance.\nOn a static or open mesh,\nan untargeted spawn rides class anycast (any manager may accept, and the acceptance records which one did).\n`cotal spawn <persona> --detach --on <instance>` and `cotal_spawn(instance: "<instance>")`\npin one instance by its exact id. A foreground CLI spawn has no manager to pin and refuses the\nflag. An MCP pin that does not resolve is refused without falling back to class anycast. There are no ordinal\naliases and no short forms: wherever a display names an instance you can address, it prints\nthe whole id, because both surfaces take nothing else.\n\nOn a user-auth mesh, manager commands obtain a short-lived `manager-caller` view from the\nexchange. It authorizes one concrete manager instance using the caller\'s current actor grant and\nthe host\'s registered service records. Discovery and invocation both use that instance\'s `inst`\nroute. This view grants no registry scan, class queue, or additional command capability. An absent,\nambiguous or unauthorized selection refuses before the command is sent.\n\nManaged launches carry `COTAL_MANAGER_INSTANCE` so their tools address the manager that launched\nthem. Existing unbound sessions can use the exchange\'s unique authorized selection without\nreplacing their actor or conversation. The connector uses a separate control connection; the\nstanding message connection and its credential source are unchanged. Accepted spawn goals are\nfollowed on that renewing connection, using its existing caller-scoped progress grant, so a long\nreadiness budget does not depend on the short-lived control credential. The follower confirms its\nprogress subscription with the broker before submitting on the separate connection. A caller still\nchecks the resolved instance and epoch, and never retries an ambiguous mutation outcome.\n\nThe manager\'s `goal-result` command accepts `{goalId}` and returns `{goalId, result?}`. It reads\nonly the authenticated caller\'s owner, actor and lifecycle through the manager\'s separate trusted\ngoal-writer connection. The caller receives an attributed reply, never a raw JetStream reader\ngrant. Each read is admitted by the connection\'s broker-enforced command grant. A live user-auth\nconnection remains bounded by its bearer expiry after revocation; a renewed connection is checked\nagainst fresh authority. There is no separate per-read ledger check. An absent `result` means no\nterminal is recorded; it does not prove the goal is running or permit another submission. The\nexisting trusted goal-writer\'s leader-served EPF read is space-wide at the broker; the handler\nconfines it to this endpoint and caller triple.\n\nA followed mutation requires a manager whose attributed describe includes `goal-result`. Update\nthe manager, issuer and client together before using that recovery path. Reloading an issuer alone\ncannot change an already-running participant manager. Recovery re-resolves the accepting instance\'s\nepoch, preserves the caller lifecycle and validates the result against the accepted goal and any\nacceptance fingerprint. Stopping the caller ends its observation, not the already accepted goal.\n\nCancellation before submission reports `not-executed`. Once submission starts, cancellation or a\nlost reply reports an unknown outcome unless an attributed refusal proves otherwise. A received\nrefusal remains a refusal even when stop races it. Local failures do not invent responder identities.\nThe follower owns its subscription, timers and read cancellation signal. Reconciliation begins\nbefore the wait deadline, and late read completions cannot settle an expired observation. Its read\ncallback receives the accepting caller triple, remaining budget and abort signal; borrowed bearer\ncommands and control connections use that signal. An in-flight dial that finishes after cancellation\ncloses without publishing. A local reply-subscription failure prevents publication and is observed\nby the same request promise, including when the transport is closing or draining. Request\ncancellation does not revoke or resubmit the accepted operation.\n\n"Only one manager per space" is not the current invariant. A split topology that keeps the\nbroker host manager-free is still a topology choice: `cotal up` on that host starts a\nmanager you then stop with `cotal down manager` after `\u2713 manager up` in\n`.cotal/manager.<spaceKey>.log` (detach stdout listing `manager` is pidfile liveness, not a\nteardown boundary), and `cotal supervise\n--server` runs the manager elsewhere ([Run a mesh](run-a-mesh.md)). Extra live managers\nare addressable, not an error.\n\nThe reserved `describe` bootstrap is the one request the resolver may repeat while waiting: it is\nread-only, it is re-published under the same request binding, and every attempt stays inside the\noriginal deadline. This covers the startup window where Core NATS discards the first request before\nthe manager has subscribed. If the connection closes while the resolver waits, the describe fails\ncleanly instead of throwing from the retry timer. The resolved command is never repeated by this\nreadiness behavior.\n\nThe resolve and the invoke are separate trips through the same anycast queue, so in a\nmulti-manager space an unpinned call can land on an instance the caller did not resolve. Every\ncall carries the incarnation it resolved against, and a manager that is not that incarnation\n**refuses before running the command**, so the failure an operator sees says the command did\nnot run, and re-issuing it cannot duplicate the effect. That is the difference that matters for\na mutation: the older behaviour detected the mismatch on the reply, after the manager had\nalready acted, and could only tell you to go and check. `--on` still matters for reaching a\nspecific manager (`ps`, `stop`, `attach`, `spawn --detach`), but it is no longer what stands\nbetween a split and a duplicated spawn. Against a manager older than this fence the refusal is\nstill after the fact, and its message says so. The re-issue is automatic only when the refusal\nstates `not-executed` in its `outcome` field; a refusal that omits the field, or states\n`unknown`, is surfaced to the caller instead of repaired, because neither proves the command did\nnot run. The CLI\'s manager commands, `cotal invoke` and the manager row of `cotal status` re-describe\nand re-issue an unpinned call after each such refusal, up to 16 times, so a split reaches the\noperator only when every attempt split. A pinned call is never re-issued.\n\nA manager whose boot inventory marked every declared connector unavailable does not subscribe\n`spawn` or `launch` on the class `one` rail. Those commands stay on scatter and on this\ninstance\'s `inst` rail, so a sibling that can launch them can take an unpinned spawn, and a\ncaller that pins this instance with `--on` still gets a named harness refusal. `describe`\nstill lists the commands: the instance rail serves them, and `describe` itself stays on the\nclass rail (SPEC 13.7). An unpinned `spawn` can therefore bind-fence: `describe` may land on\nthe skip member while `spawn` lands on a sibling, the command was not run, and the caller\nre-issues or pins `--on`. `status` reports `classSpawn: false` when that skip is in effect.\nA manager that can launch some connectors keeps the class rail. If the queue hands it a\nharness its inventory marked unavailable, the refusal names `--on` because the standing serve\ncredential cannot read sibling inventories. Pin the capable instance (the whole id, as `ps`\nprints it).\n\n`ps` and\n`status` become a **scatter** across every registered instance: the caller freezes the\nexpected set from the service registry, invokes each under a shared deadline, and merges the\nresults with per-instance attribution. A non-answering instance is labelled as registered\nwith no answer within the deadline, never silently omitted. See [SPEC \xA713.5](../SPEC.md#135-verbs) (scatter) and [cli.md](cli.md).\n\nThe expected set comes from the **registry**, which records registration rather than liveness.\nAn instance that crashes never deregisters, so it stays in the set and the gather has nothing\nleft to wait for but an answer that cannot come. It pays the whole deadline, on every scatter,\nindefinitely. A scatter can therefore be given a per-instance liveness probe: when the broker\nitself reports that an instance holds no subscription on its own instance rail, the gather stops\nwaiting for it. Only that affirmative report counts. A lapsed presence entry, a probe that timed\nout, and a probe that failed are all *absence of evidence*, and treating any of them as death\nwould turn a slow correct answer into a fast wrong one, so they leave the full deadline standing.\nNothing about the outcome changes either way: an instance that did not answer is still\nunreachable, still surfaced, and the scatter is still not complete.\n\nThe probe is supplied by the **caller**, not invented by the scatter. Asking about an instance is\na publish on that instance\'s rail, and a credential that holds no row for it is refused by the\nbroker asynchronously, while the publish itself returns normally. The probe verb watches for that\nrefusal and raises it as `permission-denied` naming the rail, so it is never mistaken for a quiet\ninstance, and it never burns the probe budget waiting out a refusal. Only the layer that\nminted the credential knows which ids it may ask about, so that layer asks about those and no\nothers. `cotal ps` freezes the class on its first connection, re-mints an instrument pinned only\nto the frozen ids, and scatters on a second; a refusal the broker raises anyway is printed and\nthe instance\'s row says the probe was refused, which is a fact about the credential, not about\nthe instance.\n\nThis does not help against an instance that is **connected but not answering**. A hung manager\nholds its subscriptions, so it is indistinguishable from a slow one, and it still costs the full\ndeadline. That is the correct result, not a gap in the probe.\n\n### Deregistration\n\nA probe makes a dead registration cheap to skip; it does not remove it. Removal is the\nregistration\'s own exit, and there are two explicit routes to it\n([SPEC \xA713.5](../SPEC.md#135-verbs): a deleted `svc` spec *is* the deregistration).\n\nA manager that stops cleanly removes its own registration if it still owns the recorded revision,\nso an ordinary shutdown leaves no stale row. It refuses that delete while this instance holds the\nendpoint governance slot at the live issuance-gate generation (a registration still completing\nits reopen). A leftover slot whose generation is behind that live generation is not in-flight and\ndoes not block the stop. A manager that cannot renew or read its lease keeps serving, stays\nregistered, and retries. If another process holds the same instance key, that process has taken\nthe instance over, so this one logs the conflict and exits without deregistering, leaving the\nsuccessor\'s registration alone.\n\nA restart that died *mid-registration* is a different residue: the issuance gate stays frozen under\nthat op. The successor completes the dead registration on boot when the freeze-holder is\naffirmatively gone under a complete CONNZ sweep (the same composition as\n[`cotal reconcile-gate`](cli.md#reconcile-gate)). A committed spec write is finished under that\nsame freeze; only a definite no-commit abort-reopens and then runs the normal takeover.\nIt does not invent a TTL and it does not start a new freeze over a still-held one.\n\nThat residue has a second half, and it is the endpoint governance slot rather than the gate. Every\nregistration takes the endpoint-wide slot before it publishes its spec and holds it until its own\ngate reopens, which is what serializes registration for the endpoint. An instance that stopped\nbetween those two points leaves the slot held with no registration behind it, so the endpoint\nrefuses new registrations while nothing is actually in flight. The slot is stamped with the\ngeneration of the gate its holder had frozen when it took it, and a slot is promoted only at that\nsame generation. So once the holder\'s gate has reopened past the stamp, the slot can never be\npromoted by anyone, and the next registration for that endpoint replaces it. That reclaim is part of\nan ordinary start and needs no operator step.\n\nA slot whose holder\'s gate is still at the stamped generation is a registration that is genuinely in\nflight, and it keeps refusing. The two states read differently only in the holder\'s gate coordinate,\nso reopening that gate is what separates them: the holder\'s own restart heals it on boot, and\n[`cotal reconcile-gate`](cli.md#reconcile-gate) is the operator\'s route when the boot path cannot\nrun. The registration path is the slot\'s only writer, and neither repair command writes it.\nA registration that cannot read the holder\'s gate at all refuses, because an unreadable gate does\nnot distinguish the two states either. Each of these refusals carries\n`kind = ai.cotal.ep.foreign-slot-held` in `error.details[]` with the holder\'s instance id and the\n`condition` that refused: `in-flight` for a holder gate still at the stamp, or `no-seam`,\n`unreadable`, `garbled` or `behind` when the registration could not read that gate or read it below\nthe stamp. A remote manager asks its host to reconcile the holder only on `in-flight`, the one\ncondition a gate repair can clear.\n\nFor the instance that cannot cooperate, an operator names it:\n`cotal deregister-instance --instance <id>` ([cli.md](cli.md#deregister-instance)). It removes the\nrecord only on the same evidence `cotal ps` acts on: the broker reporting nothing subscribed on\nthat instance\'s own rail. It refuses if the instance answers a describe, refuses if the probe could\nnot run at all, and refuses if the instance is merely quiet, because a hung process still holds its\nsubscriptions and is therefore not affirmed gone. It also refuses while that instance holds the\nendpoint governance slot at the live issuance-gate generation (a registration still completing);\na leftover slot behind that generation is not in-flight and does not block. Nothing sweeps the\nregistry on an age threshold or on silence.\nAn instance that is deregistered while it is merely wedged re-registers over the tombstone on its\nnext start, which is what makes the operator\'s decision a recoverable one.\n\n## Attach sessions\n\n`cotal attach` no longer returns a `ws://127.0.0.1` URL. It creates a one-use, holder-bound\nsession offer: the manager mints a token bound to the caller, the target lifecycle, its own\ninstance id and epoch, and an expiry, and replies with a session id and expiry only, no URL\nand no secret in the reply. The CLI redeems the offer over the mesh (a second redeem is\nrefused). On a registered open mesh that redeem is a bare connection, the same path other\ncontrol commands already use; on a static-auth mesh it is still a session-caller credential\nminted from the resolved root\'s seed. On a user-auth mesh the CLI holds no seed: it exchanges its\nlogin and the grant for a `session-caller` view bearer, and the callout mints the same caller rails\nwith the grant\'s expiry. Terminal bytes then stream on core-NATS session subjects\nscoped to the two parties. Backpressure is a bounded in-flight window with an explicit drop notice, never\nsilent loss; a late attach still repaints the full screen from a replayed terminal\nsnapshot. Close, expiry, target despawn, and a manager restart are distinct, surfaced end\nstates: a restarted manager\'s successor refuses the old epoch\'s sessions and the client\nshows "manager restarted; re-attach".\n\n## Seat input\n\n`attach` is a stream, so it is the wrong shape for a program that wants to send one line: it\nholds a session open and expects a terminal at the caller\'s end. The `input` command is the\nother half. One authorized call writes text into a running seat\'s terminal as if it had been\ntyped there, and answers with the seat and the number of bytes delivered.\n\nIt exists for **harness commands**. A line beginning with `/` (`/compact`, `/clear`, `/model`)\nis neither chat nor an event: the agent\'s own harness handles it, and the keyboard is the only\nway in. An external control surface that can already read a seat\'s turns and talk to it still\ncannot drive it without this.\n\nThe op is targeted, rides the `manager.lifecycle` capability, and declares authz modes `owner`\nand `any`, the row shape `attach` and `despawn` already carry, checked by the same authorization.\nEnter is appended unless the caller suppresses it, and nothing is echoed back, since the resulting\nturns already have somewhere to go.\n\n**Who may call it is narrower than either of those**, and the reasoning is worth stating because\nthe natural assumption is wrong. `despawn` and `attach` are granted to anything holding `spawn`;\n`input` is granted only to operator credentials. The tempting argument for treating them alike is\nthat an attach session\'s `write` already reaches the same terminal, so `input` adds nothing. It\ndoes not reach it: an attach yields a signed session offer, and redeeming one needs a per-session\ncredential minted from the space signing seed, which no agent holds. So `input` would be new\nauthority, and the own-owner rule that bounds `despawn` covers every seat under an owner rather\nthan only the ones a caller launched. Killing a peer is denial; typing into a peer is control of\nit. The write therefore sits with the credential that is already the administrative authority for\nthe domain.\n\nOnly a runtime that owns the child\'s input stream can serve it. The `pty` runtime does; the\nexternal terminal runtimes attach to a process they do not own, and there the command refuses\nand names the runtime rather than dropping the keystroke. A seat that is not running refuses for\nits own reason, and the two are distinguishable, so a caller can tell "this will never work"\nfrom "not right now". See [cli.md](cli.md#input).\n\n## Grants\n\nThere is no broad control credential. A caller holds one capability row per command it is\nallowed to send, and minting maps each named capability to the request subjects it needs and no\nothers. The manager serves over a scoped serve credential that can answer and\nreply but cannot, for instance, write another endpoint\'s records or forge a goal terminal;\nthe goal-fact writer and the session writer are separate, narrowly scoped credentials the\nbroker fences by subject. Authorization is checked at the serving boundary, and for actions\nit linearises at acceptance: a spawn refused there mints no reservation and leaves no\nprocess. See [SPEC \xA713.9](../SPEC.md#139-authority-boundary) and\n[identity & auth](identity-and-auth.md).\n\n## See also\n\n- [Architecture](architecture.md), where the manager and the wire fit in the whole system.\n- [CLI](cli.md), for `describe`, `invoke`, `spawn`, `ps`, `status`, `attach`, and `input`.\n- [SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04), the normative contract.\n'
+      "body": '# The control surface\n\n> **Concept** (informative) \xB7 **For:** operators and client authors who want to know how the manager and other daemons are driven \xB7 **Normative:** [SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)\n\nCotal once had a privileged control rail: a fixed set of named service tiers\n(`self` / `manager` / `admin` / `delivery`) on their own `ctl.*` subjects, with the manager\nas a special case the broker recognised by name. That rail is gone. Everything that serves\nstructured commands now, the manager, the delivery daemon, a wrapped MCP server, a\nthird-party service, is an ordinary **endpoint**: a daemon that registers a service\nidentity, publishes its contracts, and answers `describe`. `manager` is an endpoint name\nlike any other; no subject, envelope, or grant in this surface knows it specially. The\nmanager is a service on the mesh, not an authority over it: it holds only the capability\nrows its callers grant it, and serves over a scoped credential.\n\n## The `ep` rails\n\nOne kind, `ep`, carries every request under a mode token that says where the request\nroutes, never which verb it is (the verb rides the envelope): `one` (queue-group\nanycast, one and only one class member), `all` (scatter, every instance), and `inst` (one instance by its\nstable address). Replies come back on a `reply` rail keyed to the serving instance and its\nepoch. Around these sit the sibling planes the composites use: per-goal events, timers,\nsessions, and the journal that holds durable facts. Every request carries the caller as\nthree forge-locked tokens, `owner`, `actor`, and lifecycle `uid`, plus an unguessable\nnonce, so the broker polices who is calling in the subject grammar itself. See\n[SPEC \xA713.2](../SPEC.md#132-grammar) for the grammar and [\xA713.5](../SPEC.md#135-verbs) for\nthe verbs (`call`, `cast`, `watch`, `claim`, `scatter`).\n\n## Lifecycle identity\n\nA principal `owner.actor` is a reusable routing alias: a despawn frees the actor name and a\nlater spawn may legitimately reuse it, so the alias alone is never authority. Two further\ncoordinates make an identity durable: a **lifecycle uid**, an unguessable, never-reused id\nfor one managed lifecycle under a principal, and a **process epoch**, the fenced ownership\nepoch of the process currently animating it, advanced on every restart or takeover. At most\none live epoch owns an identity, and a superseded epoch must stop serving. Durables and\ncredentials key on the lifecycle uid, not the reusable name, which is what lets a\nsupervised restart recover the same lifecycle instead of minting a new one. See\n[SPEC \xA713.1](../SPEC.md#131-lifecycle-identity) and [identity & auth](identity-and-auth.md).\n\n## Service discovery\n\nNo client has compile-time knowledge of any endpoint\'s commands. `cotal describe\n<endpoint>` resolves a registered endpoint\'s command set off the wire: the reserved\n`describe` command answers the registered contract digests, the schemas are fetched from the\nspace\'s content-addressed contract store, recompiled, and verified against those digests.\nEach command prints with its capability class and targeting shape. `cotal invoke <endpoint>\n<command> --args \'<json>\'` then calls one command by name, validating the arguments as they\nwill be sent (JSON drops a key whose value is undefined) against the fetched input schema before\npublish. A refusal at that check means nothing was sent, and it is marked `not-executed`. A\nsigned-in user invokes the same surface through their bearer, and the broker enforces each\ncommand\'s existing capability grant. A manager alias supplied through `--name` resolves through\nits name-keyed `inspect` command, so an authorized targeted call does not need the manager-wide\n`ps` enumeration grant. Every built-in manager command uses this\nsame trust chain, so there is nothing the built-ins can reach that a described contract cannot. The registered\n`auth` endpoint is describable the same way `manager` is: `cotal describe auth` lists\n`retire-lifecycle` and its exact-mode target shape.\nSee [SPEC \xA713.7](../SPEC.md#137-contracts-and-discovery) and [cli.md](cli.md).\n\nThe manager\'s `resolve-cwd` command is in the `manager.spawn` capability class. It accepts an\nabsolute path on that manager\'s host and returns its canonical directory plus the host name. It\nrefuses a relative, missing or non-directory path with `failed-precondition`; it creates nothing.\n`spawn` applies the same check at admission, before any credentials or durables are minted.\n\n### Inspecting a managed name\n\nManager `inspect` keeps its successful response as the live managed-agent row. A live hit does\nnot read durable lifecycle state, so a temporary records-store failure cannot break inspection of\nan agent the manager currently holds.\n\nOn a live miss, a static manager point-reads its durable slot row. A name with no slot, or a slot\nwhose phase is `retired`, remains `not-found`. A nonterminal slot returns\n`failed-precondition` with `error.details[].kind =\nai.cotal.manager.static-slot-observation`. The detail carries the slot\'s `slotPhase`,\n`owner`, `actor`, `slotLifecycleUid`, `cleanupComplete` when recorded, and `slotRevision`. It\nthen carries the separate lifecycle head\'s `headState`, `headOp` when present,\n`headLifecycleUid`, and `headRevision`. Head fields are absent when provisioning has not written\nthe lifecycle head yet.\nThe error message carries the same diagnostic summary so string-only operator paths do not hide\nthe structured detail.\n\nA slot row records the manager instance that owns it. In a space with more than one manager, the\nclass queue can hand `inspect` to an instance that does not host the name. When the row names a\ndifferent instance and is not `retired`, the miss returns `failed-precondition` with the same\ndetail plus `ownerInstanceId`, which names the only manager that can act on it. The message names\nboth instances, so a caller that reads only the string can tell it from `not-found`. A sibling\'s\n`retired` row remains `not-found`.\n\nThe slot is read before the head. These records do not form one atomic snapshot, so the detail\nalso carries `readOrder: ["slot", "head"]` and `consistency: "ordered-not-atomic"`. A head can\nadvance between the reads. The issuance gate is not projected because the retirement operation\nneeded for this diagnosis is already recorded on the head, and reading a third record would add\nanother non-atomic edge without changing the per-name result.\n\nIf either durable read fails or exceeds its bound, the miss returns `unavailable` with\n`ai.cotal.manager.static-slot-read-failed` rather than claiming the name is absent. That detail\nnames the inspected `name`, the failed `record` (`slot`, `head`, or `slot-or-head` when the layer\ncannot distinguish them), and `operation: "read"`. User-auth managers do not own `mgrslot` rows,\nso their inspect misses remain live-map reads.\n\nFor Linux custodied seats, retirement requires the runtime\'s process-exit evidence before\nfreeing the alias or deleting its credentials and delivery state. Socket loss alone is not\nproof of exit. The runtime retains the record captured at launch or adoption so a clean\ncustodian exit can unlink its file without losing the recorded boot and process identities.\nIf the file is missing, reaping uses that retained record and the existing kernel identity\nchecks. An unknown reference without either record refuses cleanup. Reused process ids\nare never signalled on the strength of the old record.\n\n### Listing the durable slots\n\nManager `slots` (`manager.read`, untargeted) lists the durable static slot rows this manager\nowns. Only static managers hold these rows: a user-mode or open manager answers\n`failed-precondition`, and a manager whose durable store is not standing answers `unavailable`.\nEach row carries the same `readOrder` and `consistency` fields `inspect` uses, because the list\nis read the same way: torn across rows as well as within each row\'s slot/head pair. A `retired`\nrow is never listed. `live` reflects the manager\'s live roster at render time, not the durable\nrow.\n\n## Spawn is a goal\n\nLong-running commands are **actions** ([SPEC \xA713.6](../SPEC.md#136-composites)): the caller\nsubmits with a client-generated `goalId` and a request fingerprint, the endpoint records a\ndurable accept or reject decision, progress rides per-goal events, and the work ends in one\nterminal outcome (`succeeded`, `failed`, `cancelled`, `expired`, or `uncertain`). Spawn is\nthe reference case. Rather than block the caller for up to 30 seconds while an agent comes\nup, the manager accepts the goal and returns the allocated identity at once:\n\n```json\n{\n  "name": "reviewer-2",\n  "owner": "u_...", "actor": "reviewer", "uid": "...",\n  "goalId": "...", "fingerprint": "...",\n  "readinessDeadlineMs": 30000,\n  "executor": { "lifecycleUid": "...", "epoch": 3 }\n}\n```\n\nThe name is the one actually allocated: a persona-derived collision is auto-numbered\n(`reviewer`, then `reviewer-2`), while a hard-pinned `--name` that collides with a live\nagent is refused at accept, before anything is minted. Auto-numbering never hands out a numbered\nname it has already issued in that manager process, even after the agent holding it is gone, so\na collision takes the next number. Only numbering consults that history: a hard-pinned `--name`,\nor a persona whose own name is a numbered string, takes that name whenever it is free, and\nnumbering does not skip a string such a spawn held before. The triple plus `goalId` let the\ncaller follow progress (connector handoff, process launched, presence join) and reconcile\nlater against the exact instance that accepted. Presence within the manager\'s default\n30-second readiness window, or a connector\'s declared bounded window, settles the goal\n`succeeded`; an early process exit is `failed`; the window passing with neither is `uncertain`,\na bounded, durable outcome that a later `ps` or status read settles against the live roster.\n`uncertain` is a real terminal outcome, not an absence and not a silent hang. It carries the\ndiagnosis of whoever owned the deadline: for a launch that\nnames the agent and says to inspect it rather than re-issue, since re-issuing after a launch\nthat in fact succeeded mints a duplicate. A committer that supplies no diagnosis falls back to\n"the success signal did not arrive within the readiness deadline". The agent\'s own eventual\nstate is then observable on its presence record.\n\nThe acceptance carries that exact `readinessDeadlineMs`. A synchronous follower treats its own\nrequest deadline as a floor and waits through the accepted readiness budget plus delivery margin,\nso a connector-specific slow boot cannot be reported as a caller timeout while the manager is\nstill legitimately waiting for its terminal.\n\nA spawn that is **refused** because a lifecycle barrier already holds the actor (a frozen\nissuance gate, a retiring alias, a retired uid) is not a wait-timeout. The manager already\nknows the blocked op (`registration` / `retirement` / `activation` / `takeover`), the `opId`\nholding it, and the remedy when one exists (`retry`, `cotal reconcile-gate`). The detail\ncarries `headState` (`active` / `retiring` / `retired`) only when the refusing site read the\nlifecycle head, and `gateState` (`frozen` / `retired`) only when it read the issuance gate. A\ngate frozen by a takeover or a registration says nothing about the head, so that refusal\ncarries `gateState=frozen` and no `headState`. Those facts ride `error.details[]` as\n`kind = ai.cotal.ep.lifecycle-blocked` and are also appended to the error string, so a\ncaller that only prints `error.message` still sees them. A connector that collapses the\nrefusal to "startup failed (unknown)" or a SPEC 13.6 wait-timeout is hiding a knowable\nstate, not reporting a missing one.\n\n## Instance routing\n\nA space can run more than one manager. Each manager persists a stable logical instance id\nacross restarts and advances its process epoch when it comes back, so callers address a\nspecific manager without caring which process currently serves it. A start serves only at the\nepoch its own registration committed, never at the epoch of a later start of the same instance.\nOn a static or open mesh,\nan untargeted spawn rides class anycast (any manager may accept, and the acceptance records which one did).\n`cotal spawn <persona> --detach --on <instance>` and `cotal_spawn(instance: "<instance>")`\npin one instance by its exact id. A foreground CLI spawn has no manager to pin and refuses the\nflag. An MCP pin that does not resolve is refused without falling back to class anycast. There are no ordinal\naliases and no short forms: wherever a display names an instance you can address, it prints\nthe whole id, because both surfaces take nothing else.\n\nOn a user-auth mesh, manager commands obtain a short-lived `manager-caller` view from the\nexchange. It authorizes one concrete manager instance using the caller\'s current actor grant and\nthe host\'s registered service records. Discovery and invocation both use that instance\'s `inst`\nroute. This view grants no registry scan, class queue, or additional command capability. An absent,\nambiguous or unauthorized selection refuses before the command is sent.\n\nManaged launches carry `COTAL_MANAGER_INSTANCE` so their tools address the manager that launched\nthem. Existing unbound sessions can use the exchange\'s unique authorized selection without\nreplacing their actor or conversation. The connector uses a separate control connection; the\nstanding message connection and its credential source are unchanged. Accepted spawn goals are\nfollowed on that renewing connection, using its existing caller-scoped progress grant, so a long\nreadiness budget does not depend on the short-lived control credential. The follower confirms its\nprogress subscription with the broker before submitting on the separate connection. A caller still\nchecks the resolved instance and epoch, and never retries an ambiguous mutation outcome.\n\nThe manager\'s `goal-result` command accepts `{goalId}` and returns `{goalId, result?}`. It reads\nonly the authenticated caller\'s owner, actor and lifecycle through the manager\'s separate trusted\ngoal-writer connection. The caller receives an attributed reply, never a raw JetStream reader\ngrant. Each read is admitted by the connection\'s broker-enforced command grant. A live user-auth\nconnection remains bounded by its bearer expiry after revocation; a renewed connection is checked\nagainst fresh authority. There is no separate per-read ledger check. An absent `result` means no\nterminal is recorded; it does not prove the goal is running or permit another submission. The\nexisting trusted goal-writer\'s leader-served EPF read is space-wide at the broker; the handler\nconfines it to this endpoint and caller triple.\n\nA followed mutation requires a manager whose attributed describe includes `goal-result`. Update\nthe manager, issuer and client together before using that recovery path. Reloading an issuer alone\ncannot change an already-running participant manager. Recovery re-resolves the accepting instance\'s\nepoch, preserves the caller lifecycle and validates the result against the accepted goal and any\nacceptance fingerprint. Stopping the caller ends its observation, not the already accepted goal.\n\nCancellation before submission reports `not-executed`. Once submission starts, cancellation or a\nlost reply reports an unknown outcome unless an attributed refusal proves otherwise. A received\nrefusal remains a refusal even when stop races it. Local failures do not invent responder identities.\nThe follower owns its subscription, timers and read cancellation signal. Reconciliation begins\nbefore the wait deadline, and late read completions cannot settle an expired observation. Its read\ncallback receives the accepting caller triple, remaining budget and abort signal; borrowed bearer\ncommands and control connections use that signal. An in-flight dial that finishes after cancellation\ncloses without publishing. A local reply-subscription failure prevents publication and is observed\nby the same request promise, including when the transport is closing or draining. Request\ncancellation does not revoke or resubmit the accepted operation.\n\n"Only one manager per space" is not the current invariant. A split topology that keeps the\nbroker host manager-free is still a topology choice: `cotal up` on that host starts a\nmanager you then stop with `cotal down manager` after `\u2713 manager up` in\n`.cotal/manager.<spaceKey>.log` (detach stdout listing `manager` is pidfile liveness, not a\nteardown boundary), and `cotal supervise\n--server` runs the manager elsewhere ([Run a mesh](run-a-mesh.md)). Extra live managers\nare addressable, not an error.\n\nThe reserved `describe` bootstrap is the one request the resolver may repeat while waiting: it is\nread-only, it is re-published under the same request binding, and every attempt stays inside the\noriginal deadline. This covers the startup window where Core NATS discards the first request before\nthe manager has subscribed. If the connection closes while the resolver waits, the describe fails\ncleanly instead of throwing from the retry timer. The resolved command is never repeated by this\nreadiness behavior.\n\nThe resolve and the invoke are separate trips through the same anycast queue, so in a\nmulti-manager space an unpinned call can land on an instance the caller did not resolve. Every\ncall carries the incarnation it resolved against, and a manager that is not that incarnation\n**refuses before running the command**, so the failure an operator sees says the command did\nnot run, and re-issuing it cannot duplicate the effect. That is the difference that matters for\na mutation: the older behaviour detected the mismatch on the reply, after the manager had\nalready acted, and could only tell you to go and check. `--on` still matters for reaching a\nspecific manager (`ps`, `stop`, `attach`, `spawn --detach`), but it is no longer what stands\nbetween a split and a duplicated spawn. Against a manager older than this fence the refusal is\nstill after the fact, and its message says so. The re-issue is automatic only when the refusal\nstates `not-executed` in its `outcome` field; a refusal that omits the field, or states\n`unknown`, is surfaced to the caller instead of repaired, because neither proves the command did\nnot run. The CLI\'s manager commands, `cotal invoke` and the manager row of `cotal status` re-describe\nand re-issue an unpinned call after each such refusal, up to 16 times, so a split reaches the\noperator only when every attempt split. A pinned call is never re-issued.\n\nA manager whose boot inventory marked every declared connector unavailable does not subscribe\n`spawn` or `launch` on the class `one` rail. Those commands stay on scatter and on this\ninstance\'s `inst` rail, so a sibling that can launch them can take an unpinned spawn, and a\ncaller that pins this instance with `--on` still gets a named harness refusal. `describe`\nstill lists the commands: the instance rail serves them, and `describe` itself stays on the\nclass rail (SPEC 13.7). An unpinned `spawn` can therefore bind-fence: `describe` may land on\nthe skip member while `spawn` lands on a sibling, the command was not run, and the caller\nre-issues or pins `--on`. `status` reports `classSpawn: false` when that skip is in effect.\nA manager that can launch some connectors keeps the class rail. If the queue hands it a\nharness its inventory marked unavailable, the refusal names `--on` because the standing serve\ncredential cannot read sibling inventories. Pin the capable instance (the whole id, as `ps`\nprints it).\n\n`ps` and\n`status` become a **scatter** across every registered instance: the caller freezes the\nexpected set from the service registry, invokes each under a shared deadline, and merges the\nresults with per-instance attribution. A non-answering instance is labelled as registered\nwith no answer within the deadline, never silently omitted. See [SPEC \xA713.5](../SPEC.md#135-verbs) (scatter) and [cli.md](cli.md).\n\nThe expected set comes from the **registry**, which records registration rather than liveness.\nAn instance that crashes never deregisters, so it stays in the set and the gather has nothing\nleft to wait for but an answer that cannot come. It pays the whole deadline, on every scatter,\nindefinitely. A scatter can therefore be given a per-instance liveness probe: when the broker\nitself reports that an instance holds no subscription on its own instance rail, the gather stops\nwaiting for it. Only that affirmative report counts. A lapsed presence entry, a probe that timed\nout, and a probe that failed are all *absence of evidence*, and treating any of them as death\nwould turn a slow correct answer into a fast wrong one, so they leave the full deadline standing.\nNothing about the outcome changes either way: an instance that did not answer is still\nunreachable, still surfaced, and the scatter is still not complete.\n\nThe probe is supplied by the **caller**, not invented by the scatter. Asking about an instance is\na publish on that instance\'s rail, and a credential that holds no row for it is refused by the\nbroker asynchronously, while the publish itself returns normally. The probe verb watches for that\nrefusal and raises it as `permission-denied` naming the rail, so it is never mistaken for a quiet\ninstance, and it never burns the probe budget waiting out a refusal. Only the layer that\nminted the credential knows which ids it may ask about, so that layer asks about those and no\nothers. `cotal ps` freezes the class on its first connection, re-mints an instrument pinned only\nto the frozen ids, and scatters on a second; a refusal the broker raises anyway is printed and\nthe instance\'s row says the probe was refused, which is a fact about the credential, not about\nthe instance.\n\nThis does not help against an instance that is **connected but not answering**. A hung manager\nholds its subscriptions, so it is indistinguishable from a slow one, and it still costs the full\ndeadline. That is the correct result, not a gap in the probe.\n\n### Deregistration\n\nA probe makes a dead registration cheap to skip; it does not remove it. Removal is the\nregistration\'s own exit, and there are two explicit routes to it\n([SPEC \xA713.5](../SPEC.md#135-verbs): a deleted `svc` spec *is* the deregistration).\n\nA manager that stops cleanly removes its own registration if it still owns the recorded revision,\nso an ordinary shutdown leaves no stale row. It refuses that delete while this instance holds the\nendpoint governance slot at the live issuance-gate generation (a registration still completing\nits reopen). A leftover slot whose generation is behind that live generation is not in-flight and\ndoes not block the stop. A manager that cannot renew or read its lease keeps serving, stays\nregistered, and retries. If another process holds the same instance key, that process has taken\nthe instance over, so this one logs the conflict and exits without deregistering, leaving the\nsuccessor\'s registration alone.\n\nA restart that died *mid-registration* is a different residue: the issuance gate stays frozen under\nthat op. The successor completes the dead registration on boot when the freeze-holder is\naffirmatively gone under a complete CONNZ sweep (the same composition as\n[`cotal reconcile-gate`](cli.md#reconcile-gate)). A committed spec write is finished under that\nsame freeze; only a definite no-commit abort-reopens and then runs the normal takeover.\nIt does not invent a TTL and it does not start a new freeze over a still-held one.\n\nThat residue has a second half, and it is the endpoint governance slot rather than the gate. Every\nregistration takes the endpoint-wide slot before it publishes its spec and holds it until its own\ngate reopens, which is what serializes registration for the endpoint. An instance that stopped\nbetween those two points leaves the slot held with no registration behind it, so the endpoint\nrefuses new registrations while nothing is actually in flight. The slot is stamped with the\ngeneration of the gate its holder had frozen when it took it, and a slot is promoted only at that\nsame generation. So once the holder\'s gate has reopened past the stamp, the slot can never be\npromoted by anyone, and the next registration for that endpoint replaces it. That reclaim is part of\nan ordinary start and needs no operator step.\n\nA slot whose holder\'s gate is still at the stamped generation is a registration that is genuinely in\nflight, and it keeps refusing. The two states read differently only in the holder\'s gate coordinate,\nso reopening that gate is what separates them: the holder\'s own restart heals it on boot, and\n[`cotal reconcile-gate`](cli.md#reconcile-gate) is the operator\'s route when the boot path cannot\nrun. The registration path is the slot\'s only writer, and neither repair command writes it.\nA registration that cannot read the holder\'s gate at all refuses, because an unreadable gate does\nnot distinguish the two states either. Each of these refusals carries\n`kind = ai.cotal.ep.foreign-slot-held` in `error.details[]` with the holder\'s instance id and the\n`condition` that refused: `in-flight` for a holder gate still at the stamp, or `no-seam`,\n`unreadable`, `garbled` or `behind` when the registration could not read that gate or read it below\nthe stamp. A remote manager asks its host to reconcile the holder only on `in-flight`, the one\ncondition a gate repair can clear.\n\nFor the instance that cannot cooperate, an operator names it:\n`cotal deregister-instance --instance <id>` ([cli.md](cli.md#deregister-instance)). It removes the\nrecord only on the same evidence `cotal ps` acts on: the broker reporting nothing subscribed on\nthat instance\'s own rail. It refuses if the instance answers a describe, refuses if the probe could\nnot run at all, and refuses if the instance is merely quiet, because a hung process still holds its\nsubscriptions and is therefore not affirmed gone. It also refuses while that instance holds the\nendpoint governance slot at the live issuance-gate generation (a registration still completing);\na leftover slot behind that generation is not in-flight and does not block. Nothing sweeps the\nregistry on an age threshold or on silence.\nAn instance that is deregistered while it is merely wedged re-registers over the tombstone on its\nnext start, which is what makes the operator\'s decision a recoverable one.\n\n## Attach sessions\n\n`cotal attach` no longer returns a `ws://127.0.0.1` URL. It creates a one-use, holder-bound\nsession offer: the manager mints a token bound to the caller, the target lifecycle, its own\ninstance id and epoch, and an expiry, and replies with a session id and expiry only, no URL\nand no secret in the reply. The CLI redeems the offer over the mesh (a second redeem is\nrefused). On a registered open mesh that redeem is a bare connection, the same path other\ncontrol commands already use; on a static-auth mesh it is still a session-caller credential\nminted from the resolved root\'s seed. On a user-auth mesh the CLI holds no seed: it exchanges its\nlogin and the grant for a `session-caller` view bearer, and the callout mints the same caller rails\nwith the grant\'s expiry. Terminal bytes then stream on core-NATS session subjects\nscoped to the two parties. Backpressure is a bounded in-flight window with an explicit drop notice, never\nsilent loss; a late attach still repaints the full screen from a replayed terminal\nsnapshot. Close, expiry, target despawn, and a manager restart are distinct, surfaced end\nstates: a restarted manager\'s successor refuses the old epoch\'s sessions and the client\nshows "manager restarted; re-attach".\n\n## Seat input\n\n`attach` is a stream, so it is the wrong shape for a program that wants to send one line: it\nholds a session open and expects a terminal at the caller\'s end. The `input` command is the\nother half. One authorized call writes text into a running seat\'s terminal as if it had been\ntyped there, and answers with the seat and the number of bytes delivered.\n\nIt exists for **harness commands**. A line beginning with `/` (`/compact`, `/clear`, `/model`)\nis neither chat nor an event: the agent\'s own harness handles it, and the keyboard is the only\nway in. An external control surface that can already read a seat\'s turns and talk to it still\ncannot drive it without this.\n\nThe op is targeted, rides the `manager.lifecycle` capability, and declares authz modes `owner`\nand `any`, the row shape `attach` and `despawn` already carry, checked by the same authorization.\nEnter is appended unless the caller suppresses it, and nothing is echoed back, since the resulting\nturns already have somewhere to go.\n\n**Who may call it is narrower than either of those**, and the reasoning is worth stating because\nthe natural assumption is wrong. `despawn` and `attach` are granted to anything holding `spawn`;\n`input` is granted only to operator credentials. The tempting argument for treating them alike is\nthat an attach session\'s `write` already reaches the same terminal, so `input` adds nothing. It\ndoes not reach it: an attach yields a signed session offer, and redeeming one needs a per-session\ncredential minted from the space signing seed, which no agent holds. So `input` would be new\nauthority, and the own-owner rule that bounds `despawn` covers every seat under an owner rather\nthan only the ones a caller launched. Killing a peer is denial; typing into a peer is control of\nit. The write therefore sits with the credential that is already the administrative authority for\nthe domain.\n\nOnly a runtime that owns the child\'s input stream can serve it. The `pty` runtime does; the\nexternal terminal runtimes attach to a process they do not own, and there the command refuses\nand names the runtime rather than dropping the keystroke. A seat that is not running refuses for\nits own reason, and the two are distinguishable, so a caller can tell "this will never work"\nfrom "not right now". See [cli.md](cli.md#input).\n\n## Grants\n\nThere is no broad control credential. A caller holds one capability row per command it is\nallowed to send, and minting maps each named capability to the request subjects it needs and no\nothers. The manager serves over a scoped serve credential that can answer and\nreply but cannot, for instance, write another endpoint\'s records or forge a goal terminal;\nthe goal-fact writer and the session writer are separate, narrowly scoped credentials the\nbroker fences by subject. Authorization is checked at the serving boundary, and for actions\nit linearises at acceptance: a spawn refused there mints no reservation and leaves no\nprocess. See [SPEC \xA713.9](../SPEC.md#139-authority-boundary) and\n[identity & auth](identity-and-auth.md).\n\n## See also\n\n- [Architecture](architecture.md), where the manager and the wire fit in the whole system.\n- [CLI](cli.md), for `describe`, `invoke`, `spawn`, `ps`, `status`, `attach`, and `input`.\n- [SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04), the normative contract.\n'
     },
     {
       "slug": "define-a-team",
@@ -19685,7 +19699,7 @@ var DOCS_BUNDLE = {
       "title": "Embedding Cotal",
       "kind": "Guide (informative)",
       "summary": "The cotal binary in this repo is one composition root: an operator CLI.",
-      "body": "# Embedding Cotal\n\n> **Guide** (informative) \xB7 **For:** implementers building a service on top of Cotal \xB7 **Prereqs:** [Architecture](architecture.md), [Identity and auth](identity-and-auth.md), [Delivery daemon](delivery-daemon.md)\n\nThe `cotal` binary in this repo is one composition root: an operator CLI. A separate service\n(for example a hosted, multi-tenant Cotal) does not fork this repo. It writes its **own**\ncomposition root that depends on the published `@cotal-ai/*` packages and imports the surfaces it\nwants. `bin/cotal.ts` uses the same composition pattern. This page is the contract for that: what is a real library\nexport you can build against, how to boot the server-side daemons from those exports, and where the\ncurrent export surface stops short of a fully hosted composition.\n\nThis is the \"guarded substrate\" boundary in practice. Nothing here reveals or assumes a specific\nhost; it documents the public seams any embedder composes.\n\n## What you embed\n\nThe supported reference shape here is **one broker operator serving one space** (one tenant: a\ndedicated data account, under an operator that also holds the system account and a quarantined\nauth-callout account) plus three standalone processes. The trust layer itself composes many spaces\nunder one broker operator today (`createBrokerAuth` + `createSpaceAccountAuth` + N-space\n`serverConfig`); what does not exist yet is the per-space **lifecycle** on a shared broker (see\n[Known gaps](#hosted-composition-gaps)). The three processes:\n\n| daemon | package | what it is |\n|---|---|---|\n| auth-service | `@cotal-ai/auth` | the NATS auth callout, the IdP token exchange, and JWKS. Plane 1 to Plane 2. |\n| delivery | `@cotal-ai/delivery` | the Plane-3 durable backstop: fan-out writer plus trusted reader, per space. |\n| supervise | `@cotal-ai/manager` | the per-machine agent lifecycle (spawn/despawn/attach), per space. |\n\n`mint`, `deliver`, and `auth-service` expose their behavior as direct library primitives, and the\nsupported one-space bootstrap below re-composes from exported low-level primitives. `supervise` and\nthe full `up` orchestration are **not** public runners: `up` also does broker bring-up, restore,\nprocess and registry management, and lifecycle work, and `supervise`'s orchestration is private (see\n[Supervisor signing authority](#supervisor-signing-authority)).\n\n## The export surface\n\nEverything below is a real export of a published package, reachable from the package root (each\npackage publishes only `.` via `dist/index.{js,d.ts}` and ships `files: [\"dist\"]`). Type-only names\nare marked; import them with `import type`.\n\n**Daemon runners and lifecycle**\n\n| symbol | package | purpose |\n|---|---|---|\n| `runAuthService(args, store?)` | `@cotal-ai/auth` | boot the auth-service daemon; `store` injects the secret material. |\n| `runDelivery(args, store?)` | `@cotal-ai/delivery` | boot the delivery daemon; `store` injects the scoped `delivery` cred. |\n| `startAuthService(inputs)` | `@cotal-ai/auth` | start one account-scoped auth-service context and return an `AuthServiceHandle` with the loopback `url`, the per-start `cap`, `readiness`, `drain`, and idempotent `close`. With the optional `publicFace` input it also serves the public exchange face and carries `publicUrl`. With the optional `platformControl` input the handle also has `platformControlAuthority`, the in-process platform control door, `platformControlReadiness`, its read-only readiness read, `observeManagerGate`, the manager gate read a host composing the delegated user intent decisions passes them, and `activateManagedLifecycle`, the activation that host runs at a delegated launch's pinned lifecycle UID. With `platformControl.host` it also has `registerHostIncarnation`, which registers the host process's own endpoint instance and returns the incarnation a delegated execution pins, `observeHostGate`, the read of that endpoint's issuance gate, and `awaitHostFence`, which resolves once a later registration or barrier fences an incarnation. `runAuthService` remains the CLI entry. |\n| `PlatformControlAuthorityRequest`, `PlatformControlInnerRequest`, `PlatformControlAuthorityResult`, `PlatformControlAssignment` *(types)* | `@cotal-ai/core` | the closed envelope, its inner request union, its result and the backend's assignment row for `platformControlAuthority`. `platformControlOwner` in `@cotal-ai/auth` derives the `p_` owner the door issues under. |\n| `startDeliveryService(inputs)` | `@cotal-ai/delivery` | start one account-scoped delivery instance and return a `HostedServiceHandle` with `readiness`, `drain`, and idempotent `close`. The process runner remains the CLI entry. |\n| `deliveryCredsKey(space, composition)`, `membershipRwCredsKey(space, composition)` | `@cotal-ai/workspace` | build the secret-store keys the delivery cred and the membership feed's rw cred are read/re-signed under. Keys are **per-space**: `space.<hex>/<kind>`. A hosted composition passes `{ injected: true }`. |\n| `retireManagerInstanceIdentity(root, space, expected)` | `@cotal-ai/workspace` | remove a persisted manager identity only if its complete instance id and serve identity still match `expected`. Returns `removed` or `absent`; refuses malformed, nonregular, and changed records. `absent` is not proof of ownership or successful teardown. The caller must separately prove stop and retirement ownership before using it. |\n| `DELIVERY_CREDS_KIND`, `MEMBERSHIP_RW_CREDS_KIND` | `@cotal-ai/workspace` | the operator-facing KIND names (`delivery.creds`, `membership-rw.creds`) those keys are built from, and what renewal results report. A kind is **not** a key: putting a cred under the bare kind writes the pre-0.4 flat location, which nothing reads. |\n| `Manager`, `ManagerOptions` *(type)* | `@cotal-ai/manager` | construct and run a supervisor in-process; `ManagerOptions.secretStore` injects the one store it reads/writes every secret through. `ManagerOptions.remoteAuthority` is the hosted manager-service authority bundle, including host-owned release, retained-validation, goal-index, and serve-time admin-authorization callbacks. |\n| `ManagerOptions.pooled` | `@cotal-ai/manager` | require signerless remote authority and an explicit non-custodial runtime before local execution starts. A pooled composition must supply the assigned account key and all-duty renewal callback; the CLI's default remains unchanged. A signed-in human's manager gets that material from `managerServiceAuthority`. A platform-run control manager gets it from `AuthServiceHandle.platformControlAuthority` with the shipped `remoteManagerClient` builders, as the [platform control authority](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/platform-pooled-control-authority.md) design describes. |\n| `createRuntime`, `Runtime` *(type)* | `@cotal-ai/manager` | resolve the spawn backend (pty built in). |\n| `liveKvEntries(kv, filterOrOptions?, options?)`, `LiveKvEntriesOptions` *(type)* | `@cotal-ai/core` | read live KV entries in one finite scan. Pass `{ signal }` as the second argument or after a key filter to cancel. An interrupted scan throws `IncompleteKvScan`; cancellation throws the signal reason, including during an empty-bucket bind. The scan deletes only its owned consumer; broker inactivity expiry remains the crash or deletion-failure backstop. |\n\nThe remote manager authority parser accepts `renewStandingBundle` and `renewRunDriver` only with\nan assigned account nkey, the current manager process epoch, and a host-authenticated registration\nproof. A run renewal also names its active holder, takeover, epoch, fencing token, and the two\nexisting nkeys. The host must fresh-check those coordinates against its registration gate and run\njournal before issuing server-selected profiles. A host without that renewal authorization refuses\nthe request. Until the host issuer wires the operations and validates them on real connections,\nthe presence of these types is not an operational pooled renewal guarantee.\n\nWith `renewStandingBundle` configured, the manager renews all five standing credentials together.\nIt checks every returned credential for the held nkey and assigned account, test-connects each one,\nand adopts them only if the serve epoch has not moved. A refused or failed candidate leaves the\ncurrent credentials in place and records the refusal as cleanup debt until a later renewal succeeds.\nOn shutdown, after the standing context is drained, an expired maintenance executor is renewed\nthrough the existing scoped host operation so deregistration can finish without restarting duties.\n\n**Provisioning and minting** (all `@cotal-ai/core`)\n\n| symbol | purpose |\n|---|---|\n| `createBrokerAuth(label)` | mint BROKER trust: the operator and system account one nats-server trusts. One per broker, shared by every space on it. |\n| `createSpaceAccountAuth(broker, space)` | mint one space's own data account, signed by that broker's operator: the add-a-tenant primitive. |\n| `createSpaceAuth(space)` | the one-space convenience: broker trust + one account in a single composed bundle. |\n| `setupSpaceStreams({ servers, space, creds })` | create the space's JetStream streams. |\n| `ensureDefaultDeliveryClass({ servers, space, creds?, deliveryClass })` | write the space's default delivery class at creation so it is wire-discoverable (SPEC section 4). |\n| `serverConfig(broker, spaces, { storeDir, maxFileStore?, extraAccounts?, port?, host? })` | render the broker config: one operator, N space accounts. `storeDir` is required, `maxFileStore` caps JetStream file storage in bytes (omitted, nats-server's dynamic default applies), and `extraAccounts` preloads the auth-callout account. |\n| `mintCreds(auth, identity, profile, opts?)` | mint a scoped cred for any `Profile`. |\n| `mintMembershipObserverCreds`, `mintConnectionEvictorCreds` | mint the membership/eviction scoped creds. |\n| `provisionAgent`, `provisionAgentDurables` | create a principal's bind-only durables. |\n| `newIdentity`, `stripSpaceAuth` | a fresh nkey identity; a stripped signer bundle (data signing seed only). |\n| `Profile`, `CredentialKind`, `MintOpts`, `SpaceAuth` *(types)*, `CREDENTIAL_LIFETIMES` | the profile matrix and cred lifetime policy. |\n\n**Auth building blocks** (all `@cotal-ai/auth`)\n\n| symbol | purpose |\n|---|---|\n| `createCalloutAuth`, `startAuthCallout` | the NATS auth-callout responder. |\n| `createUserTokenIssuer`, `pinnedJwksResolver` | mint and verify the Cotal user bearer. |\n| `createIdpBridge` | exchange a verified IdP JWT for a Cotal bearer (see [the callout contract](identity-and-auth.md#the-idp-callout-contract)). |\n| `deriveOwnerToken`, `validateUserToken` | owner derivation; strict bearer validation. |\n| `cotalAuthProvider` | the self-registering `auth-provider` extension. |\n| `ensureCalloutAuth`/`loadCalloutAuth`, `ensureIssuer`/`loadIssuer`, `ensureOwnerSecret`/`loadOwnerSecret` | read/write the auth secret kinds through a `SecretStore`. |\n\n**Seams and the wire** (all `@cotal-ai/core` unless noted)\n\n| symbol | purpose |\n|---|---|\n| `SecretStore` *(type)* | the durable hosted-secret seam (get/put/delete); `get()` returns raw seeds/keys into process memory, so it is a blob seam, not HSM/KMS signing. |\n| `FsSecretStore`, `workspaceSecretStore(root)` | the filesystem default. **These live in `@cotal-ai/workspace`, not core.** |\n| `AuthProvider` *(type)*, `Connector` *(type)*, `Runtime` *(type)*, `Command` *(type)* | the extension contracts; implementations self-register on import. |\n| `registry` | the shared registry a composition root pulls surfaces into. |\n| `CotalEndpoint`, subjects, message types | the wire client and shapes. |\n| `ParsedArgs` *(type)* | the shape the daemon runners take (see below). |\n\nFor a Linux Unix-socket adapter, `peerCredentials(socket)` from `@cotal-ai/seat` returns\nkernel-observed peer `pid`, `uid` and `gid`. Compare these against the host's authorization\npolicy; request-supplied identity and process liveness do not replace that policy or a\nlifecycle fence. The helper starts no custodian and refuses unsupported platforms or a\nmissing native helper.\n\nThe runners take a CLI-shaped `ParsedArgs`, not a typed options object, so a host fabricates one:\n\n```ts\nconst args: ParsedArgs = { values: { space, server, port: \"0\" }, positionals: [], raw: [] };\n```\n\nFor an embedded delivery instance, use `startDeliveryService` instead. Its `HostedContextInputs`\ninclude the account public key and lifecycle UID, space, broker URL, injected store, stable\n`storeIdentity`, and an explicit `stateDir`. The store must declare that same injected identity.\nThe initial delivery credential must belong to the assigned account. The function returns only\nafter the delivery responder is bound. `close()` withdraws serving and releases only the lease\nowned by that instance. It closes both membership connections even when a disconnected drain\nfails, so they cannot reconnect after closure. Credential-expiry health state clears after\nsuccessful broker-verified adoption through the existing `reloadCreds` rail. A failed start\nrefuses locally without exiting the host process or stopping another account's delivery service.\nIf a health fault occurs during an asynchronous store read, startup rejects when the read returns\nand closes any resources created by that late completion.\n\n`startAuthService` takes the same `HostedContextInputs`. The store must declare the assigned\ninjected identity, and its data account must be the assigned account. The IdP pin and ledger live\nunder the explicit `stateDir`. The context never resolves a workspace root from the working\ndirectory and has no local manager, so only remote manager gates can be selected. It returns after\nthe authority plane, the callout subscription and the loopback listener are bound. A fenced plane or\na lost broker connection makes that context `unavailable` and closes it without exiting the process.\nThe host writes no discovery file for it. The handle carries what `auth-service.json` holds for a\nCLI start: the loopback `url`, `publicUrl` when a public face runs, and the per-start `cap`. The cap\nalone authorizes the loopback host actions, lifecycle retirement and managed-agent enrollment\nverification, so keep it in the authority process. `publicFace` takes the CLI's public face inputs\n(`port`, `url`, `trustedProxy`, `advertisedServer`, `agentProvisioningUrl`) under the same rules,\nand a face without a port refuses to start.\n\nTwo optional inputs serve a platform composition. `platformControl: { observeAssignment }` adds\n`platformControlAuthority` to the handle. It is a typed in-process method, served on no listener,\nthat issues the manager-service request family for the one control manager the backend assigned to\nthis account, under a derived `p_` owner. It reads the assignment fresh on every call and refuses\nan IdP token, another account, a stale revision, another instance or lifecycle, and an instance\nanother owner registered. It refuses `prepare` and `activate` while the assignment's named\npredecessor is still registered or frozen. The same input adds `platformControlReadiness(instanceId)`,\nthe route for a host that needs to know whether its assigned control manager is serving. It returns\nthat instance's attributed `status` reply and refuses any instance the current assignment does not\nname, or one whose gate another owner holds. It reads over the context's own connection, whose\ngrant is the assigned instance's `describe` and `status` and its own reply rail. That connection\nrenews in process like the context's other connections and never leaves it, so the host lends no\nhuman or operator credential to a worker, mints no control instrument per read, and does not read\nliveness off the manager process. Without the input both members are `undefined`.\n`standingRenewableTtlSeconds` is forwarded unchanged to the authority plane, which bounds it to 5\nto 86400 seconds. It is a trusted-host input for the renewal rehearsal, and no request or CLI flag\nsets it. SPEC \xA713.1 and \xA713.6 define the view.\n\nThe auth plane can renew a registered manager's\nfive standing credentials from the current service registration. Run-driver renewal still\nrefuses without an authoritative activated-run reader, so these handles do not yet make a\ncomplete pooled auth and delivery host. A fresh auth plane can initialize without a\ndelivery-admin responder. Reclaiming a held claim from a dead predecessor needs the delivery\ninstance first: its admin rail must complete the broker connection-liveness sweep before the\nauth plane takes the claim. An absent or inconclusive oracle refuses the reclaim.\n\n### Remote manager client composition\n\n`@cotal-ai/manager` exports the `remoteManagerClient` namespace, containing the stock remote\nrequest builders and response validators, and `registerRemoteManagerAuthority` for registration\nwith a host-issued prepare credential. It returns the process epoch and registration revision its\nown registration committed. When a later start of the same instance registers before this start\nauthorizes its serve grant, this start is refused with `expired`.\n`RemoteManagerIdentityState` describes the five private\nmanager identities stored under an explicit account-local root. Use these public exports when\ncomposing `ManagerOptions.remoteAuthority`; do not copy CLI validators or import private modules.\n`managerClusterArtifacts()` returns the canonical document, manifest and their digests used by\nregistration. Supply its `[document, manifest]` pair when constructing the activation request\nwith `remoteManagerClient.remoteManagerAuthorityRequest` and the stock registration proof.\nThe host still validates the artifact closure and current registration before activation.\nThe namespace includes closed standing/run renewal, admission, maintenance, enrollment and\nretirement helpers. It provides no signer or new grant. The host still owns authenticated issuance,\ncurrent registration and activated-run observations, and any guarded foreign-holder repair.\nAn embedding must preserve those checks and supply a supported runtime; the client exports alone\ndo not provide a pooled runtime, an authority service or a complete hosted context.\n\n### Long-lived endpoints take a bearer function\n\n`EndpointOptions.bearer` accepts either a string or a function, and the difference is not stylistic.\nA string is minted once, so when it expires (which it will: callout bearers live minutes) the\nendpoint has nothing to renew with. It will not present the dead token to the broker, since that is\na guaranteed denial that still costs a full auth-callout round trip. It refuses to reconnect, emits\n`warning` saying which case it is in, and retries on a widening backoff until the process\nre-authenticates and rebuilds it. Retry notices use `warning` rather than `error` because Node\nrethrows an unhandled `error` event and would kill a host the endpoint is still trying to recover.\n\nPass a **function** for anything that outlives one bearer. That is a renewal source: it is called\nahead of each expiry and again whenever a reconnect finds the cached bearer dead, and it requires\nexplicit `card.owner` and `card.actor`. The first-party surfaces already do this\n(`UserViewAuth.source`, the connector's `agentBearerCommand`). A string bearer is for a short\none-shot connection.\n\nLong-lived hosts must also subscribe to the endpoint's `warning` event. It carries conditions the\nendpoint is surviving, including failed credential renewal, reconnect retries, and a durable leave\nit keeps retrying after the broker refuses a durable channel's live subscription. A host may choose\nto ignore warnings for a one-shot endpoint whose awaited operation owns the verdict, but that choice\nshould be explicit. An unhandled warning is nonfatal and silent.\n\n## Booting the daemons\n\n### auth-service\n\n`runAuthService(args, store?)` reads its provisioned long-lived secret kinds (service keys, callout\naccount, issuer keys, owner secret) through the injected `SecretStore`; a host provisions those into\nthe store first. It is a **signer and identity authority**, not a scoped daemon: at runtime it holds\nthe data-account and callout-account signing seeds, the issuer's private JWKs, and the\nowner-derivation secret in process memory (`SecretStore.get` exports raw values). The IdP pin and the\nactor ledger are **not** store-injected: `runAuthService` resolves them under\n`userAuthStateDir(findCotalRoot(), space)`, a path relative to the process working directory, so a\nhost provisions those into that exact directory (neither `store` nor `COTAL_HOME` selects it). It\nalso writes an ephemeral `auth-service.json` discovery file there that carries the live exchange\ncapability. That file appears only after every plane is bound, so waiting on it is the readiness\nsignal: a host that also passes the daemon's pid to the provider's `ready()` gets a process-bound\nwait. The wait extends past the base timeout while that pid is alive, up to a fixed bound, and it\nends at once when the pid exits.\n\n```ts\nimport { runAuthService } from \"@cotal-ai/auth\";\n// store implements SecretStore over your secret backend; get() returns raw seeds into memory.\n// Provision the auth secret kinds into the store, AND the IdP pin + actor ledger under\n// userAuthStateDir(findCotalRoot(), space), before this call.\nawait runAuthService(\n  { values: { space, server: brokerUrl, port: \"8081\" }, positionals: [], raw: [] },\n  store,\n);\n```\n\n### delivery\n\n`runDelivery(args, store?)` runs from a **pre-minted scoped `delivery` cred** and never loads the\nsigner. Provide the cred either through the injected store (under\n`deliveryCredsKey(space, { injected: true })`) or with a\n`--creds` file; the two are mutually exclusive. The daemon re-fetches the cred from the store at 75%\nof its JWT lifetime and fails loud rather than riding to expiry, so **something must re-sign a fresh\ncred into that same store**. When that read finds the previous generation still there, the daemon\nreports the missed remint and retries in 60 seconds. The current cred stays live until its expiry,\nand the store is read once per retry rather than once per second.\n\n```ts\nimport { runDelivery } from \"@cotal-ai/delivery\";\nawait runDelivery({ values: { space, server: brokerUrl }, positionals: [], raw: [] }, store);\n```\n\nThat renewal is a **signer** operation, not the delivery daemon's:\n`remintDaemonCreds(root, space, store?, { preflight? })` (`@cotal-ai/workspace`) reads the `SpaceAuth`\nsigner **through the same resolved `store`** (`getSpaceAuth(store ?? workspaceSecretStore(root), space)`,\nkeys `auth/broker.json` + `auth/account.<key>.json`; the pre-split `auth/auth.json` monolith is\nmigration input and the container signer mount only) and re-signs the daemon creds (`delivery.creds` and the membership feed's\n`membership-rw.creds`) back into that store. The injected `store` is both the signer source and the\ncredential destination, never a split. `space` is **required** and validated against the store's signer, so a\nstore swapped to a different space cannot re-sign over the wrong broker's creds. `preflight` is a\ncaller-supplied proof that the broker accepts the credential. The reference `Manager` passes a\n`probeConnect` over its `servers`. It gates **every** candidate before overwriting the last-good,\nwhether the signer is a full bundle or a stripped projection: a bundle's JWT chain proves only that\nit is self-consistent and\nnamed the space, NOT that its account is the broker's *current* account for that space (two\n`createSpaceAuth(space)` calls yield same-named, different-account chains), so a same-label alternate\nsigner would otherwise mint a broker-dead cred and clobber the good one. The offline local repair (`doctor auth --fix`) has no preflight. It permits the overwrite only\nunder **authority continuity**: the candidate must be signed by the same account signing key (`iss`) as the current\n(already broker-accepted) cred. A same-label alternate account breaks continuity and is refused, full or\nstripped; a legitimate local re-sign is continuous and proceeds without a network. The reference\n`Manager` runs it on a schedule against its **own**\n`secretStore` (see below), so passing the manager and the delivery daemon the *same* store closes the\nrenewal loop end-to-end on an injected backend: the manager reads the signer from the store, re-signs\ninto it, and the daemon adopts each generation on a preflight-proven 75% timer. The stock\ncross-host composition cannot satisfy that by writing one filesystem and fingerprinting another:\n`Manager.start()` and every later remint challenge the daemon's `reloadStoreIdentity` and a\ndivergent pair is refused naming both stores. The identity is the store the daemon actually\nreloads: an injected coordinate, the workstation root only when `--creds` is\n`<root>/.cotal/<spaceSegment(space)>/delivery.creds` (matching the canonical arm), the\nfile's own directory for any other `--creds` path, or the workstation root. Uninjected\n`--creds` that names one real workstation while process cwd resolves another is refused\nat start, naming both, because membership-rw still uses `findCotalRoot`. A `--creds`\npath that is not under any `.cotal` tree is not that case and is not refused here. It never\nwalks ancestors with `findCotalRoot`. No bound daemon is not a named\nstore, so start proceeds; a later daemon on a foreign store is refused on the next remint.\nThe first-party filesystem adapter declares its workspace-root identity on the store itself. Other\ninjected adapters declare their stable coordinate on `SecretStore.identity`, or name it in\n`COTAL_SECRET_STORE` on both processes. It never throws: it\nreturns per-file results (`skipped: \"no-auth\"` when the store holds no signer records),\nso the caller must check them or the cred still rides to expiry. A composition whose signer lives in\nKMS/Vault simply injects that store; no bespoke renewal is needed. A `--creds` file path must be\nreplaced atomically before the 75% read. The signer can now be injected behind the store seam, which\nresolves custody. The remaining hosted gap is signer **isolation**. The seed is still decrypted\nin-process at the manager's uid, so it needs an OS sandbox or remote signer.\n\n### Supervisor signing authority\n\n`@cotal-ai/manager` exports the `Manager` class; there is **no** `runSupervise(opts)` runner. The\nprivate CLI `runManager` also does broker-reachability checks, space/default resolution,\nroster/launch parsing and materialization, installed-extension resolution, signal handling, staged\npre-spawn, and the forever wait. A host composes that lifecycle itself around `Manager`:\n\n```ts\nimport { Manager } from \"@cotal-ai/manager\";\nconst mgr = new Manager({ space, servers: brokerUrl, workspaceRoot });\nawait mgr.start();          // then wire your own SIGINT/SIGTERM -> mgr.stop()\n```\n\n`stop()` runs once. A later call joins the stop in progress and settles with it, and a call that\nasks for a different `withAgents` than the running stop is refused.\n\nUnlike delivery, the manager is **not** a pre-minted-scoped-cred daemon (auth-service is also a\nsigner: it holds fewer artifacts than the full trust bundle, but its data-account signing seed still\ngrants complete data-account mint authority on compromise, so this is not least-privilege). On `start()`\nthe manager reads its space's full trust chain **through its `secretStore`** (`getSpaceAuth(this.secrets,\nthis.space)`, composed from `auth/broker.json` + `auth/account.<key>.json`; a container may instead\nmount a stripped signer bundle at the legacy `auth/auth.json` key) and **self-mints** its supervisor cred and renewals from the\ndata-account signing seed. In static mode it also mints every per-agent cred from that seed; in user\nmode agents instead receive callout-minted bearers, but the manager still holds the signing seed for\nits own creds and renewal. So a hosted supervisor is a **trusted per-tenant account-signer process**,\nnot a least-privilege connect client. It additionally requires a `~/.cotal/meshes/space.<key>.json`\nregistry record and the workspace user-auth marker to start in user mode. `ManagerOptions.secretStore`\ninjects the one `SecretStore` the manager uses for **the signer itself (the split trust\nrecords)**, daemon-credential renewal (`remintDaemonCreds`), and per-agent secrets,\ndefaulting to the workspace filesystem store; pass the delivery daemon the *same* store for end-to-end\nhosted renewal. The store declares the same identity on both processes, or both set\n`COTAL_SECRET_STORE` to the same coordinate. The manager\nremints no daemon credential when the daemon names a different store, including a daemon that binds\nafter start; it keeps running and serving its own agents, so one space can carry a manager on more\nthan one workspace root. That manager also stays off the space's renewal lease, so a manager or a\n`cotal doctor auth --fix` on the daemon's store can still take it. Pointing several managers at one coordinate is safe: the store identity\nalone cannot pick an owner (it carries no holder and no tiebreak, so every manager sharing the store\nmatches), so the manager that also holds the space's renewal lease is the one that remints and the\nrest skip it. Without that lease two owners would remint on independent timers with no ordering\nbetween them, and one write would land between the other's re-sign and its fingerprint-only\n`reloadCreds`. `cotal doctor auth --fix` takes the same lease before it re-signs, so a live manager\nand a local repair never race each other either. The signer IS now injectable: a hosted composition injects a KMS/Vault store and no\nsigning seed lands on the hosted disk. What remains is signer **isolation**. The seed is decrypted\nin-process at the manager's uid. That issue needs an OS sandbox or remote signer; it is no longer a\ncustody problem. The other knobs are `workspaceRoot` and the process-global `COTAL_HOME`.\n\n> Scope note: the **static-auth** operator paths (`cotal spawn`/`join`/`status`/`web`, via\n> `mesh-target` \u2192 `connect`/`preflight`) still read the signer from the local split records (sync\n> `loadSpaceAuth`). That is the single-machine composition, where the signer is on local disk by the\n> static-auth model; multi-tenant hosting runs **user mode**, which never mints from on-disk trust. The\n> store-injectable signer path is the hosted-server set: the manager, `remintDaemonCreds`, and delivery.\n\nThe typed remote-manager authority contract includes a one-shot terminal phase. A host implements\n`remoteAuthority.prepareAgentRetirement` to revoke the managed grant and finish its resumable\nrelease while preserving the UID, then `remoteAuthority.mintRetirementRequester` returns the\nhost-signed JWT for a fresh participant-owned nkey. The credential is pinned to the authenticated\nowner, server-derived manager serve principal, current instance epoch, and exact target lifecycle.\nThe manager then uses the existing auth `retireLifecycle` rail with the operation id derived by\n`managedRetirementOpId(target.lifecycleUid)`. This derivation is the reference remote-Manager\ncomposition's closed contract, not a rule for every retirement entry point; interactive retirement\nkeeps its existing operation identity and remains compatible. The `retireLifecycle` rail independently\nrecomputes the managed id from its broker-pinned target before any gate, head, intent, or barrier\naccess, so mint-time validation is not the terminal boundary. A failure keeps\nthe alias held. This does not expose the auth barrier or give the participant signer authority.\n\nIf the participant disappears after prepare, the host finishes the retirement itself on the auth\nservice's loopback face: `POST /managed-lifecycle/retire` (exported as `MANAGED_RETIRE_PATH` from\n`@cotal-ai/auth`) with the `Bearer <cap>` from `auth-service.json` and only\n`{ owner, actor, lifecycleUid }`. It has the interactive door's guards (POST only, no `Origin`, JSON,\ncapability, closed body) and is never served on the public face. The managed grant must already be\nrevoked at that uid, or it answers 409. It runs the same `managedRetirementOpId(uid)` operation as\nthe rail, and the rail and the door share one in-process flight, so a late participant request and\nthe host call converge on one barrier.\n\n| lifecycle head | answer |\n| --- | --- |\n| absent, or `retired` at another uid | `200 { retired: false, lifecycleUid, notStarted: true }` |\n| `active`/`retiring` at another uid | `409` |\n| `retired` at this uid | `200 { retired: true, lifecycleUid, alreadyRetired: true }` |\n| `active`/`retiring` at this uid | the barrier runs, then `200 { retired: true, lifecycleUid }` |\n\nDeprovisioning durables stays with `deprovisionAgent` and a `deprovisioner` credential. Pass `memberChannels` to both to also purge the retired lifecycle's durable membership rows on those concrete channels. The manager fills that list from the launch's concrete read channels and the delivery daemon's read-only `lifecycleMemberships` admin verb. When that verb cannot answer, rows on other channels stay retained, the teardown logs the inventory as incomplete, and retirement remains held pending retry rather than releasing the alias. Each teardown examines two exact consumers, one ACL key and the named member keys. KV deletion uses a native revision condition; a lost condition with a live replacement refuses rather than claiming absence. Consumer INFO checks before and after DELETE distinguish verified prior absence from disappearance. `acknowledged` counts native DELETE success replies. `disappeared` counts observed live-to-absent consumers and live KV rows whose conditional purge lost to a competing deletion. These KV rows were present at the first read, so they never count as prior `absent` or as this caller's `deleted`. The ACL and membership subtotals preserve that distinction. Neither establishes which concurrent caller uniquely removed a consumer, so `consumers.deleted` and the total `deleted` are `null` when a consumer disappears without a winner token. A repeat after verified absence reports zero, not an invented deletion. `refused` counts slots whose cleanup or state remains uncertain. A partial failure raises `DeprovisionError` carrying these bounded observations. The Manager's static sweep preserves unknown uniqueness rather than adding acknowledged requests as physical removals; its slot totals remain separate.\n\nA host that resumes retained managed actors also implements\n`remoteAuthority.validateRetainedAgent`. The participant sends back the actor token and sentinel it\nalready holds, plus the `nextRegistrationProof` returned by the activation response. That proof is\nhost-issued after registration and binds the manager owner, actor, lifecycle, identity nkeys, current\nregistration revision, and serving epoch. The host checks it against the current open manager gate,\nvalidates the retained secrets against its current managed row, and returns only the non-secret\nauthority shape. The manager binds every result coordinate and the returned authority back to its\ninventory before use. Do not copy the provider's `issuer.json` or `callout.json` into the participant\nstore. Both contain private signing or exchange authority.\n\nThe same composition supplies `remoteAuthority.agentBearerExchangeUrl`, the pinned public auth-service\nbase used by retained children. Remote adoption launches `agent-bearer --exchange-url <base>`; it must\nnot select the local `--dir` arm, which depends on a host-only auth-service process record.\n\nA host that lets a remote participant spawn FRESH managed agents implements\n`remoteAuthority.enrollManagedAgent`. The participant generates the standing actor token, writes it\nat mode 0600, and passes only its SHA-256 digest with the requested actor, label, role,\ncapabilities, and channel lists, so the plaintext secret never leaves the participant machine. There\nis deliberately no `lifecycleUid` input: the host selects the UID, because only the host sees the\nretirement tombstones that make a UID permanently unusable, and a participant-chosen UID could aim a\nfresh grant at a dead incarnation. The host authors the ledger grant, pre-creates the lifecycle-keyed\ndurables, clamps the requested lists to what the spawning owner already holds, and returns the owner,\nactor, chosen `lifecycleUid`, the space sentinel credentials, the effective lists, and\n`agentBearerExchangeUrl`. The manager binds every returned coordinate, re-keys the secret family onto\nthe returned UID, and launches `agent-bearer --exchange-url <base>`. When the hook is absent a\nsignerless manager refuses the user-mode spawn rather than authoring a local grant the host knows\nnothing about.\n\nBoth managed-agent operations ride the one verified `POST /manager-service-authority` transport as\n`kind: \"manager-managed-agent-enrollment\"` and `kind: \"manager-managed-agent-prepare-retirement\"`.\nStock `dispatchManagerAuthorityRequest` refuses both with `unimplemented`: they mutate host storage,\nand stock holds none of that composition. A host terminates its own public route, authenticates the\nhuman there, and asks the auth service for the decision at\n`POST /manager-service-authority/verify-enrollment` (exported as `VERIFY_ENROLLMENT_PATH` from\n`@cotal-ai/auth`) with the `Bearer <cap>` from `auth-service.json` and only `{ owner, request }`. That\ndoor has the managed retirement door's guards, derives the caller's scope from the local ledger rather\nthan the body, checks the manager gate and registration proof in-process, and answers\n`{ authorized: true, owner, actor, instanceId, serveEpoch }`. `authorizeRemoteManagedAgentEnrollment`\nand `authorizeRemoteManagedAgentPrepareRetirement` are exported too, for a host that composes the\ndecision without the HTTP hop. Both require ledger scope `supervise`; `spawn` and `admin` do not\nimply it.\n\nA host that runs managed agents on its own hosted runtime adds two more kinds on the same transport.\n`kind: \"manager-managed-agent-runtime-create\"` asks the host to create the runtime for one agent it\nalready enrolled, and `kind: \"manager-managed-agent-runtime-status\"` reads that runtime's state. Both\ncarry the manager envelope plus `target: { owner, actor, lifecycleUid }`, the coordinate the\nenrollment returned. Both schemas are closed. An unknown top-level or target field, including\n`providerRef`, `handle`, or `name`, is refused as `bad-request`, because the host alone issues and\nholds provider references. There is no stop, adopt, or probe kind: stop goes through\nprepare-retirement. Stock dispatch refuses both kinds with `unimplemented`, and the verify-enrollment\ndoor decides them. `authorizeRemoteManagedAgentRuntimeCreate` and\n`authorizeRemoteManagedAgentRuntimeStatus` apply the enrollment door's checks: host space, a target\nowner equal to the authenticated owner, the manager actor's own ledger row with `supervise`, the open\ngate, the current serve epoch, and the registration proof. Each returns only\n`{ owner, instanceId, actor, target }`. The door touches no provider and writes nothing. The host\nmatches the decision to its own intent record and performs the create afterwards. The host answers\nwith `state` (`reserved`, `creating`, `bound`, `create-unknown`, `closing`, or `closed`), `readiness`\n(`ready`, `bound-not-ready`, or `none`), and an optional `retirementPhase`. A manager builds requests\nwith `remoteManagerClient.remoteManagedAgentRuntimeRequest` and binds the answer with\n`remoteManagedAgentRuntimeState`.\n\nAn enrollment result may also carry `runtimeIntent: { state: \"reserved\" }` when the host reserved a\nhosted runtime for the agent. It is display-only. Older hosts omit it, the manager binds both shapes\nto the same material, and nothing reads it as authority.\n\nNo stock door lets a platform control holder launch or retire an agent for a signed-in user. The\nmanaged-agent kinds above act only under the authenticated owner and refuse a caller that is not\nthat user, so a platform could only run a user's agent by holding the user's login or by enrolling\nthe agent under its own owner. Both are refused. The\n[delegated user launch intent](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/delegated-user-launch-intent.md)\ndesign and SPEC \xA713.16 define the smallest addition. The user admits one launch or one retirement\non the host's authenticated route. The holder consumes that intent once, from its current\nregistration, epoch and lifecycle. The host then enrolls the agent under the user's `u_` owner with\nthe user's own actor as its ledger parent, so the envelope walk, membership and channel lists match\nwhat the user's own manager would produce. Retirement keeps the prepare, provider closure and\nterminal barrier order, and the host finishes it when the holder is gone. A launch the host had to\nundo keeps its agent name held until the host process that ran it confirms it has stopped, and\nwhile the name is held the host also refuses it to the user's own manager. `@cotal-ai/auth` ships the\ntwo decisions, `authorizeDelegatedUserIntentAdmission` and `authorizeDelegatedUserIntentExecution`,\nfor a host that owns an intent store and those writers to compose on its own routes. Both read the\nholder's gate through the handle's `observeManagerGate`, present with `platformControl`, which reads\nover the context's own connection, so the host opens no second data-account connection. It is an\nobservation for the decision: the consuming CAS and the writers still apply their own checks. The\nconsuming CAS pins the incarnation of the host process that runs the flight as the executor, never\nthe auth plane's, because the two can restart independently. `platformControl.host` names that\nprocess's reverse-DNS endpoint, the closure digest of its \xA713.7 cluster and every contract artifact\nthe closure needs, and the auth plane self-authorizes that one name.\n`registerHostIncarnation(instanceId)` publishes the artifacts, registers that instance through the\nceremony the plane runs for itself, and returns `{ instanceId, processEpoch }` with the epoch that\nregistration committed. The host calls it at every start with its persisted instance id, before it\nadmits or recovers any flight, so a restart fences its predecessor and advances the epoch. A start\nwhose confirming read of the gate finds that a later start of the same instance registered is\nrefused with `conflict`. The returned epoch is a committed coordinate and stays current only until\nthe next start registers, which can happen before the call returns. `observeHostGate(instanceId)`\nis a point-in-time read of an executor's gate, and answers null for an absent gate; a sweeper\ndecides on it. `awaitHostFence(instanceId, processEpoch)` resolves with the gate once it is no\nlonger open at that epoch, and with null once it is absent. The host arms it with its returned\nincarnation before it admits or recovers any flight, and stops serving when it resolves. It polls\nthe gate, because no runtime credential may watch the auth bucket. The\nhost's launch writer first activates the agent's lifecycle at the pinned UID through the handle's\n`activateManagedLifecycle`, before any ledger row or durable, and its compensation runs the same\ncall before the terminal barrier, so a launch whose agent never exchanged its bearer still reaches\nthe terminal barrier at that UID. The launched agent exchanges its bearer on the context's public\nface, so the host starts it with `publicFace`, and its retirement writer ends at\n`POST /managed-lifecycle/retire` with the handle's `cap`. Stock dispatch refuses both kinds as\n`unimplemented`. The holder's composition passes\n`remoteAuthority.executeDelegatedUserIntent`, which posts the execution request and binds the answer\nwith `parseRemoteDelegatedUserIntentExecutionResult`. It then starts the agent with\n`startAgent({ ..., delegatedIntent: { intentId, owner, parent } })` and retires it with\n`retireDelegatedAgent(name, intentId)`, which stops the agent only after the host confirms\n`retired: true` for its exact target. A delegated agent's stop, exit or failed launch keeps its name\nheld until that retirement confirms.\n\nRemote user-mode managers must also supply `remoteAuthority.authorizeAdmin`. The manager builds each\nrequest only from the caller tuple parsed from the broker-authenticated endpoint subject, then relays\nthat tuple over the current registered manager lifecycle. HTTPS does not separately authenticate the\nrelayed caller. The host authenticates the manager operator, binds the request to the current open\nmanager gate, registration proof, serving epoch, and identity nkeys, then reads the caller's unified\nauthoritative row fresh. It returns only the manager owner and `authorized: boolean`, with every request\ncoordinate echoed. Missing, revoked, narrowed, foreign-owner, and stale-lifecycle callers all return\n`false`; malformed coordinates or corrupt and unavailable authority state fail the operation. The\nparticipant never reads or mirrors the host ledger, and the remote branch has no local fallback. The\nsame callback gates all `manager.admin` handlers, any-mode cross-owner control, and `ps` or `inspect`\ncross-owner visibility. Launch keeps its owner-equality policy.\n\nThe remote authority's instance executor remains the scoped maintenance credential for clean service\nderegistration and exact instance registration operations. It carries no records-stream consumer\nlifecycle authority. The manager's boot `goalidx` sweep uses the authenticated host operation, which\nreturns parsed `goalidx.manager.<owner>.>` entries for that owner only. The host keeps the sealed\nconsumer connection and its create/delete rights. The five-minute executor already renews through\n`remoteAuthority.renewExecutor`. The signerless supervisor, serve, goal-writer, session-ledger and\nper-run driver credentials do not yet have a complete remote renewal and adoption path. The\n[hosted runtime contract](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/hosted-runtime-contracts.md) records the bounded additions and\ntheir ownership; it is not a shipped pooled service.\n\n**Signer isolation needs an OS sandbox.** The default pty runtime\nruns agent children under the *same* OS uid and the *same* `workspaceRoot`, so mode-0600 on\nthe trust records does not stop a hostile same-uid agent from reading their absolute paths. The reference\n[deploy](deploy.md) tree does not solve this: it mounts the signer into the agent's own container, so\nits phase-1 boundary isolates agents from each other, not the signer from the agent. A hosted\ncomposition must run the manager/minter that holds the signer in a different uid, container, or mount\nnamespace from the agent children, which mount no signer at all; that split is future\nhosted-composition work, so until it (or a remote/injected minter) exists, do not run untrusted\nagents under this manager.\n\n### Delegated seats outside the manager's filesystem\n\nThe [portable lifecycle bootstrap](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/portable-lifecycle-bootstrap.md)\ndesign and SPEC \xA713.17 define how a managed agent that `enrollManagedAgent` already enrolled starts\nin a child that cannot see the manager's filesystem. The ordinary `spawn` path writes the token and\nsentinel under the manager's workspace root and hands the runtime a launch whose bearer command and\nmaterial file are paths on that filesystem, so such a child needs this path instead.\n\nThe delegation boundary is one optional runtime method. A runtime that implements\n`Runtime.spawnDelegated(launch, handoff)` receives two values and no paths: a `DelegatedSeatLaunch`\n(connector name, persona text, model and the other launch choices) and a `ManagedLifecycleHandoff`\n(space, owner, actor, the host-chosen `lifecycleUid`, broker and IdP pins, the pinned exchange base,\nthe sentinel, the channel lists, and the raw actor token). The manager enrolls once, as it does\ntoday, and builds the handoff from what it holds. It never sends the token to the host, never copies\na file from its workspace or secret store, and never builds a local launch for that seat. No signer,\nissuer or callout record, loopback capability, provisioner or manager credential, control token, or\nmanager path crosses. A spawn choice that only the manager's host can honour is refused before\nenrollment: `--resume`, a manifest agent's `continuity: exact`, `--cwd`, and any shared MCP server,\nwhether from `--share-tools` or the config default (`--share-tools none` passes).\n\nThe runtime creates one provider resource under `managedRuntimeKey(target)`, writes the handoff into\nit as one 0600 file and the persona beside it, and runs the stock bootstrap there:\n`cotal spawn --config <persona-file> --space <space> --name <actor> --expect-owner <owner> --expect-lifecycle-uid <uid>`\nwith `COTAL_MANAGED_HANDOFF_FILE` naming the file. `delegatedSeatCommand` builds that argv. The\n`cotal` entry reads the file into memory, deletes it and drops the variable before it parses flags,\nprints help or loads extensions, so every outcome, a refusal of its own flags included, leaves no\nfile. It refuses before any broker connection or exchange request when the\nspace, owner, actor, or lifecycle UID differ from the expected values, and then runs the\nenrollment-redeem consumer: it registers the mesh in its own home, writes the token to its own 0600\nfile, and exchanges it through `agent-bearer --exchange-url` unchanged. It never enrolls, redeems, or\nmints a token or UID.\n\nReadiness is still mesh presence. A create whose answer is lost leaves the handle running, so the\nlaunch settles uncertain and stays held; the manager never retries it. A provider read that finds no\nresource under the key is not an exit, because the create may still land. Every close by\n`managedRuntimeKey` is fenced: it completes only once the create was answered or the provider refuses\nany later create under the key. A provider that names its own resources may run the create as a\ndurable operation keyed by `managedRuntimeKey` and close through the identifier its authenticated\ncreate response returned, kept where the host can read it without the manager. Only that response\nbinds an identifier to the key; one derived from the key or found by name or listing is never closed\nor adopted, and while the response is unknown the launch stays held. Every stop, the reap of a child\nwhose parent exited and `Manager.stop({ withAgents: true })` included, runs `prepareAgentRetirement`\nfor the UID-exact target, then `stop()` on the handle `spawnDelegated` returned, then the terminal\nbarrier. `preparePreservation` refuses a cut that holds a delegated seat, and a `Manager.stop()` after\na refused cut retires the seat through the same steps. After the manager is gone\nthe host runs the same steps, makes the same fenced close by `managedRuntimeKey`, and finishes at\n`MANAGED_RETIRE_PATH`. Supply `spawnDelegated` only from a runtime whose host can make that fenced\nclose without the manager. The enrollment redeem\n(`COTAL_ENROLLMENT_FILE`) stays for lifecycles whose token the host generated itself; a host cannot\nmint one for a manager-enrolled lifecycle because it holds only the digest.\n\n## Provisioning a space (one-space reference shape)\n\n```ts\nimport { createSpaceAuth, setupSpaceStreams, ensureDefaultDeliveryClass, mintCreds, newIdentity } from \"@cotal-ai/core\";\nconst auth = await createSpaceAuth(space);                       // trust bundle (in-memory seeds)\nconst provisionerCreds = await mintCreds(auth, newIdentity(), \"provisioner\");\nawait setupSpaceStreams({ servers: brokerUrl, space, creds: provisionerCreds });\n// SPEC section 4: write the default delivery class at space creation so it is wire-discoverable,\n// never inferred from the resolution fallback. A daemon-backed space is \"durable\".\nawait ensureDefaultDeliveryClass({ servers: brokerUrl, space, creds: provisionerCreds, deliveryClass: \"durable\" });\nconst deliveryCreds = await mintCreds(auth, newIdentity(), \"delivery\");\n// put deliveryCreds into your SecretStore under deliveryCredsKey(space, { injected: true })\n// (@cotal-ai/workspace) before booting delivery \u2014 the key is per-space, not the bare kind.\n```\n\nRendering the broker config for a user-auth space is `serverConfig(broker, spaces, { storeDir,\nmaxFileStore?, extraAccounts })`, where `extraAccounts` must include the callout account from\n`createCalloutAuth` so the auth-service has a broker account to answer on. That account never shares\nthe data account. `maxFileStore` is an optional positive integer byte cap; any other value throws.\n\nBroker trust and space accounts are separate authorities: `createBrokerAuth` mints the one\noperator + system account a broker trusts, `createSpaceAccountAuth(broker, space)` signs each\ntenant's data account under it, and `serverConfig(broker, spaces, opts)` renders them all into one\nconfig. A host composition can therefore provision several spaces on one broker today. `cotal up`\nrenders that config from every tenant the root's auth directory holds, so booting one space keeps\nthe broker trusting its siblings, and it refuses to render at all while any account record is\nunreadable. The rest of the CLI lifecycle is still broker-wide: `down`, `clean` and `backup` refuse\non a multi-space root rather than scoping to one tenant, and the per-space lifecycle is the\nremaining multi-space operator layer. See\n[Known gaps](#hosted-composition-gaps).\n\n## Hazardous provisioning primitives\n\n`mintCreds`, the full `Profile`/`CredentialKind` matrix, `createSpaceAuth`, and `stripSpaceAuth` are\nlow-level operator primitives. Handle them as account-authority material:\n\n- A holder of a `SpaceAuth` (or a `stripSpaceAuth` bundle, which **keeps** the data signing seed) is\n  a fully-trusted tenant-account authority: it can mint `admin`, `provisioner`, and destructive\n  profiles, not merely `supervisor`, and mint a DM-reading identity. `createSpaceAuth`'s full result\n  holds operator, system, and account seeds in memory.\n- Choose `profile` and `MintOpts` from **server-side constants**, never from tenant input. `MintOpts`\n  can widen the bounded TTL defaults; cap it at your boundary. `CREDENTIAL_LIFETIMES` is a policy\n  record, not an authorization boundary.\n- Never log signer material or export it into env. Do not co-locate signer access with an untrusted\n  connector/runtime process at the same OS uid (file permissions do not contain a same-uid reader;\n  see the manager's isolation note). Segregate per tenant; rotate on compromise\n  (`rotateDataAccountSigningKey`).\n\n## Hosted composition gaps\n\nThe primitives above are present as exports, but three capabilities are **not** cleanly composable\nfrom the public contract today. Each is tied to work in flight; a host either waits for the seam or\nscopes the capability out. None is a wire concern.\n\n1. **Delivery immediate live eviction and a fully-hosted membership feed.** The renewable\n   `membership-rw.creds` is now a `SecretStore` kind. `startMembership` reads it through the\n   injected store, and the manager re-signs it there. The graph-feed writer therefore renews on a hosted\n   backend (its data connection adopts each generation on a preflight-proven 75% timer). What still\n   reads from a fixed on-disk path are the *static* `membership-observer.creds` and\n   `connection-evictor.creds` ($SYS creds, minted at the `up` that provisions the account and renewed by `up --rotate-sys`) and `membership.json`\n   (`{accountId}`, non-secret config); those, plus the private provisioning wrapper, keep immediate\n   live eviction and a fully-hosted feed a partial gap. Missing files degrade membership to\n   traffic-only and make live eviction refuse (loudly). The supported delivery contract here is the\n   Plane-3 durable backstop.\n2. **Supervisor signer isolation.** `ManagerOptions.secretStore` now injects the one `SecretStore` the\n   manager reads/writes every secret through, including the composed `SpaceAuth`\n   signer (the split trust records), its daemon-cred renewal, and its per-agent kinds. What remains is process\n   isolation: the manager still decrypts the signer in-process at its uid, so untrusted agent children\n   must run under a different uid/container/mount namespace or behind a future remote signer.\n3. **Per-space lifecycle on a shared broker.** The trust layer is multi-space\n   (`createBrokerAuth` + `createSpaceAccountAuth` + N-space `serverConfig`, persisted as\n   `broker.json` + `account.<key>.json`) and `cotal up` renders the whole tenant list, but there is\n   no per-space provisioning verb and no per-space teardown/backup/restore: the CLI's broker-wide\n   lifecycle verbs refuse on a multi-space root, naming the tenants.\n   This is the remaining multi-space operator layer.\n4. **A non-Better-Auth production IdP.** The exchange core (`createIdpBridge`) is EdDSA-generic, but\n   the stock provider and login client are Better-Auth-endpoint-shaped, `cotalAuthProvider`\n   self-registers on import (colliding with a host-owned provider under `resolveAuthProvider`), and\n   the login flow speaks Better Auth's device-code endpoints. A different IdP is a host-built auth\n   composition on the low-level primitives, not a configuration change (see\n   [the IdP callout contract](identity-and-auth.md#the-idp-callout-contract)).\n\n## Hosted durability\n\nSpace-durable **coordination** state (chat/DM/task history, live presence, membership runtime, the\ndurable ACL registry, leases) lives in **JetStream**, written by the delivery daemon and the\nendpoints. It is broker-resident and needs no host-side durable path.\n\nWhat is **not** in JetStream, and is hosting-critical, is trust and authorization state a host must\nplace and keep:\n\n| state | class | where today | hosted injection |\n|---|---|---|---|\n| full `SpaceAuth` trust chain (`auth/broker.json` + `auth/account.<key>.json`, composed; a stripped signer bundle may instead be mounted at the legacy `auth/auth.json` key) | signing authority | `SecretStore` | `SecretStore` (manager + renewal) |\n| auth kinds: callout account/creds/xkey, issuer private keys, owner-derivation secret, data-signer projection | signing/identity authority | four `SecretStore` kinds | `SecretStore` (auth-service) |\n| `delivery.creds` | standing scoped cred | `SecretStore` or `--creds` | `SecretStore` (delivery) |\n| actor ledger, IdP pin | authorization + trust config | ambient `userAuthStateDir(findCotalRoot(), space)` | none (root-relative; not `store`/`COTAL_HOME`) |\n| `membership-rw.creds` | standing scoped cred | `SecretStore` | `SecretStore` (delivery + manager renewal) |\n| membership-observer / connection-evictor creds + `membership.json` | scoped $SYS creds / config | workspace filesystem | none (see gap 1) |\n| manager agent creds, actor tokens, sentinel creds | lifecycle authority | `SecretStore` | `SecretStore` (manager `secretStore`) |\n| `~/.cotal/meshes/space.<key>.json` record (holds IdP trust pins/root pointers) | non-secret, integrity-critical | machine home | process-global `COTAL_HOME` only |\n| auth-health, renewal records | non-secret diagnostics | workspace filesystem | `workspaceRoot` |\n\nThe `SpaceAuth` trust chain and the auth-service store kinds are **separate** identities/projections,\nnever parts of one document. `auth-service.json` (the live exchange capability) is ephemeral runtime\nstate, not durable, but is sensitive while the daemon runs. `@cotal-ai/workspace` is machine-local\noperator tooling by design; personas, PID files, and the `current-mesh` pointer are truly local and\nmust **not** sit on a hosted durable path. Everything classed above as an authority is what a hosted\ncomposition must provision and persist: signer-bearing server secrets now have `SecretStore` seams;\nthe remaining non-injectable rows are the explicit ambient `workspaceRoot`/cwd paths above.\n\n## See also\n\n- [Substrate stability](stability.md): what v0.3 and the 0.x packages guarantee, and the projected v0.4 break.\n- [Identity and auth](identity-and-auth.md): the profile matrix, the signer, and the IdP callout contract.\n- [Delivery daemon](delivery-daemon.md): the Plane-3 durable backstop.\n- [Deploy](deploy.md): the reference container against an external broker.\n"
+      "body": "# Embedding Cotal\n\n> **Guide** (informative) \xB7 **For:** implementers building a service on top of Cotal \xB7 **Prereqs:** [Architecture](architecture.md), [Identity and auth](identity-and-auth.md), [Delivery daemon](delivery-daemon.md)\n\nThe `cotal` binary in this repo is one composition root: an operator CLI. A separate service\n(for example a hosted, multi-tenant Cotal) does not fork this repo. It writes its **own**\ncomposition root that depends on the published `@cotal-ai/*` packages and imports the surfaces it\nwants. `bin/cotal.ts` uses the same composition pattern. This page is the contract for that: what is a real library\nexport you can build against, how to boot the server-side daemons from those exports, and where the\ncurrent export surface stops short of a fully hosted composition.\n\nThis is the \"guarded substrate\" boundary in practice. Nothing here reveals or assumes a specific\nhost; it documents the public seams any embedder composes.\n\n## What you embed\n\nThe supported reference shape here is **one broker operator serving one space** (one tenant: a\ndedicated data account, under an operator that also holds the system account and a quarantined\nauth-callout account) plus three standalone processes. The trust layer itself composes many spaces\nunder one broker operator today (`createBrokerAuth` + `createSpaceAccountAuth` + N-space\n`serverConfig`); what does not exist yet is the per-space **lifecycle** on a shared broker (see\n[Known gaps](#hosted-composition-gaps)). The three processes:\n\n| daemon | package | what it is |\n|---|---|---|\n| auth-service | `@cotal-ai/auth` | the NATS auth callout, the IdP token exchange, and JWKS. Plane 1 to Plane 2. |\n| delivery | `@cotal-ai/delivery` | the Plane-3 durable backstop: fan-out writer plus trusted reader, per space. |\n| supervise | `@cotal-ai/manager` | the per-machine agent lifecycle (spawn/despawn/attach), per space. |\n\n`mint`, `deliver`, and `auth-service` expose their behavior as direct library primitives, and the\nsupported one-space bootstrap below re-composes from exported low-level primitives. `supervise` and\nthe full `up` orchestration are **not** public runners: `up` also does broker bring-up, restore,\nprocess and registry management, and lifecycle work, and `supervise`'s orchestration is private (see\n[Supervisor signing authority](#supervisor-signing-authority)).\n\n## The export surface\n\nEverything below is a real export of a published package, reachable from the package root (each\npackage publishes only `.` via `dist/index.{js,d.ts}` and ships `files: [\"dist\"]`). Type-only names\nare marked; import them with `import type`.\n\n**Daemon runners and lifecycle**\n\n| symbol | package | purpose |\n|---|---|---|\n| `runAuthService(args, store?)` | `@cotal-ai/auth` | boot the auth-service daemon; `store` injects the secret material. |\n| `runDelivery(args, store?)` | `@cotal-ai/delivery` | boot the delivery daemon; `store` injects the scoped `delivery` cred. |\n| `startAuthService(inputs)` | `@cotal-ai/auth` | start one account-scoped auth-service context and return an `AuthServiceHandle` with the loopback `url`, the per-start `cap`, `readiness`, `drain`, and idempotent `close`. With the optional `publicFace` input it also serves the public exchange face and carries `publicUrl`. With the optional `platformControl` input the handle also has `platformControlAuthority`, the in-process platform control door, `platformControlReadiness`, its read-only readiness read, `observeManagerGate`, the manager gate read a host composing the delegated user intent decisions passes them, and `activateManagedLifecycle`, the activation that host runs at a delegated launch's pinned lifecycle UID. With `platformControl.host` it also has `registerHostIncarnation`, which registers the host process's own endpoint instance and returns the incarnation a delegated execution pins, `observeHostGate`, the read of that endpoint's issuance gate, and `awaitHostFence`, which resolves once a later registration or barrier fences an incarnation. `runAuthService` remains the CLI entry. |\n| `PlatformControlAuthorityRequest`, `PlatformControlInnerRequest`, `PlatformControlAuthorityResult`, `PlatformControlAssignment` *(types)* | `@cotal-ai/core` | the closed envelope, its inner request union, its result and the backend's assignment row for `platformControlAuthority`. `platformControlOwner` in `@cotal-ai/auth` derives the `p_` owner the door issues under. |\n| `startDeliveryService(inputs)` | `@cotal-ai/delivery` | start one account-scoped delivery instance and return a `HostedServiceHandle` with `readiness`, `drain`, and idempotent `close`. The process runner remains the CLI entry. |\n| `deliveryCredsKey(space, composition)`, `membershipRwCredsKey(space, composition)` | `@cotal-ai/workspace` | build the secret-store keys the delivery cred and the membership feed's rw cred are read/re-signed under. Keys are **per-space**: `space.<hex>/<kind>`. A hosted composition passes `{ injected: true }`. |\n| `retireManagerInstanceIdentity(root, space, expected)` | `@cotal-ai/workspace` | remove a persisted manager identity only if its complete instance id and serve identity still match `expected`. Returns `removed` or `absent`; refuses malformed, nonregular, and changed records. `absent` is not proof of ownership or successful teardown. The caller must separately prove stop and retirement ownership before using it. |\n| `DELIVERY_CREDS_KIND`, `MEMBERSHIP_RW_CREDS_KIND` | `@cotal-ai/workspace` | the operator-facing KIND names (`delivery.creds`, `membership-rw.creds`) those keys are built from, and what renewal results report. A kind is **not** a key: putting a cred under the bare kind writes the pre-0.4 flat location, which nothing reads. |\n| `Manager`, `ManagerOptions` *(type)* | `@cotal-ai/manager` | construct and run a supervisor in-process; `ManagerOptions.secretStore` injects the one store it reads/writes every secret through. `ManagerOptions.remoteAuthority` is the hosted manager-service authority bundle, including host-owned release, retained-validation, goal-index, and serve-time admin-authorization callbacks. |\n| `ManagerOptions.pooled` | `@cotal-ai/manager` | require signerless remote authority and an explicit non-custodial runtime before local execution starts. A pooled composition must supply the assigned account key and all-duty renewal callback; the CLI's default remains unchanged. A signed-in human's manager gets that material from `managerServiceAuthority`. A platform-run control manager gets it from `AuthServiceHandle.platformControlAuthority` with the shipped `remoteManagerClient` builders, as the [platform control authority](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/platform-pooled-control-authority.md) design describes. |\n| `createRuntime`, `Runtime` *(type)* | `@cotal-ai/manager` | resolve the spawn backend (pty built in). |\n| `liveKvEntries(kv, filterOrOptions?, options?)`, `LiveKvEntriesOptions` *(type)* | `@cotal-ai/core` | read live KV entries in one finite scan. Pass `{ signal }` as the second argument or after a key filter to cancel. An interrupted scan throws `IncompleteKvScan`; cancellation throws the signal reason, including during an empty-bucket bind. The scan deletes only its owned consumer; broker inactivity expiry remains the crash or deletion-failure backstop. |\n\nThe remote manager authority parser accepts `renewStandingBundle` and `renewRunDriver` only with\nan assigned account nkey, the current manager process epoch, and a host-authenticated registration\nproof. A run renewal also names its active holder, takeover, epoch, fencing token, and the two\nexisting nkeys. The host must fresh-check those coordinates against its registration gate and run\njournal before issuing server-selected profiles. A host without that renewal authorization refuses\nthe request. Until the host issuer wires the operations and validates them on real connections,\nthe presence of these types is not an operational pooled renewal guarantee.\n\nWith `renewStandingBundle` configured, the manager renews all five standing credentials together.\nIt checks every returned credential for the held nkey and assigned account, test-connects each one,\nand adopts them only if the serve epoch has not moved. A refused or failed candidate leaves the\ncurrent credentials in place and records the refusal as cleanup debt until a later renewal succeeds.\nOn shutdown, after the standing context is drained, an expired maintenance executor is renewed\nthrough the existing scoped host operation so deregistration can finish without restarting duties.\n\n**Provisioning and minting** (all `@cotal-ai/core`)\n\n| symbol | purpose |\n|---|---|\n| `createBrokerAuth(label)` | mint BROKER trust: the operator and system account one nats-server trusts. One per broker, shared by every space on it. |\n| `createSpaceAccountAuth(broker, space)` | mint one space's own data account, signed by that broker's operator: the add-a-tenant primitive. |\n| `createSpaceAuth(space)` | the one-space convenience: broker trust + one account in a single composed bundle. |\n| `setupSpaceStreams({ servers, space, creds })` | create the space's JetStream streams. |\n| `ensureDefaultDeliveryClass({ servers, space, creds?, deliveryClass })` | write the space's default delivery class at creation so it is wire-discoverable (SPEC section 4). |\n| `serverConfig(broker, spaces, { storeDir, maxFileStore?, extraAccounts?, port?, host? })` | render the broker config: one operator, N space accounts. `storeDir` is required, `maxFileStore` caps JetStream file storage in bytes (omitted, nats-server's dynamic default applies), and `extraAccounts` preloads the auth-callout account. |\n| `mintCreds(auth, identity, profile, opts?)` | mint a scoped cred for any `Profile`. |\n| `mintMembershipObserverCreds`, `mintConnectionEvictorCreds` | mint the membership/eviction scoped creds. |\n| `provisionAgent`, `provisionAgentDurables` | create a principal's bind-only durables. |\n| `newIdentity`, `stripSpaceAuth` | a fresh nkey identity; a stripped signer bundle (data signing seed only). |\n| `Profile`, `CredentialKind`, `MintOpts`, `SpaceAuth` *(types)*, `CREDENTIAL_LIFETIMES` | the profile matrix and cred lifetime policy. |\n\n**Auth building blocks** (all `@cotal-ai/auth`)\n\n| symbol | purpose |\n|---|---|\n| `createCalloutAuth`, `startAuthCallout` | the NATS auth-callout responder. |\n| `createUserTokenIssuer`, `pinnedJwksResolver` | mint and verify the Cotal user bearer. |\n| `createIdpBridge` | exchange a verified IdP JWT for a Cotal bearer (see [the callout contract](identity-and-auth.md#the-idp-callout-contract)). |\n| `deriveOwnerToken`, `validateUserToken` | owner derivation; strict bearer validation. |\n| `cotalAuthProvider` | the self-registering `auth-provider` extension. |\n| `ensureCalloutAuth`/`loadCalloutAuth`, `ensureIssuer`/`loadIssuer`, `ensureOwnerSecret`/`loadOwnerSecret` | read/write the auth secret kinds through a `SecretStore`. |\n\n**Seams and the wire** (all `@cotal-ai/core` unless noted)\n\n| symbol | purpose |\n|---|---|\n| `SecretStore` *(type)* | the durable hosted-secret seam (get/put/delete); `get()` returns raw seeds/keys into process memory, so it is a blob seam, not HSM/KMS signing. |\n| `FsSecretStore`, `workspaceSecretStore(root)` | the filesystem default. **These live in `@cotal-ai/workspace`, not core.** |\n| `AuthProvider` *(type)*, `Connector` *(type)*, `Runtime` *(type)*, `Command` *(type)* | the extension contracts; implementations self-register on import. |\n| `registry` | the shared registry a composition root pulls surfaces into. |\n| `CotalEndpoint`, subjects, message types | the wire client and shapes. |\n| `ParsedArgs` *(type)* | the shape the daemon runners take (see below). |\n\nFor a Linux Unix-socket adapter, `peerCredentials(socket)` from `@cotal-ai/seat` returns\nkernel-observed peer `pid`, `uid` and `gid`. Compare these against the host's authorization\npolicy; request-supplied identity and process liveness do not replace that policy or a\nlifecycle fence. The helper starts no custodian and refuses unsupported platforms or a\nmissing native helper.\n\nThe runners take a CLI-shaped `ParsedArgs`, not a typed options object, so a host fabricates one:\n\n```ts\nconst args: ParsedArgs = { values: { space, server, port: \"0\" }, positionals: [], raw: [] };\n```\n\nFor an embedded delivery instance, use `startDeliveryService` instead. Its `HostedContextInputs`\ninclude the account public key and lifecycle UID, space, broker URL, injected store, stable\n`storeIdentity`, and an explicit `stateDir`. The store must declare that same injected identity.\nThe initial delivery credential must belong to the assigned account. The function returns only\nafter the delivery responder is bound. `close()` withdraws serving and releases only the lease\nowned by that instance. It closes both membership connections even when a disconnected drain\nfails, so they cannot reconnect after closure. Credential-expiry health state clears after\nsuccessful broker-verified adoption through the existing `reloadCreds` rail. A failed start\nrefuses locally without exiting the host process or stopping another account's delivery service.\nIf a health fault occurs during an asynchronous store read, startup rejects when the read returns\nand closes any resources created by that late completion.\n\n`startAuthService` takes the same `HostedContextInputs`. The store must declare the assigned\ninjected identity, and its data account must be the assigned account. The IdP pin and ledger live\nunder the explicit `stateDir`. The context never resolves a workspace root from the working\ndirectory and has no local manager, so only remote manager gates can be selected. It returns after\nthe authority plane, the callout subscription and the loopback listener are bound. A fenced plane or\na lost broker connection makes that context `unavailable` and closes it without exiting the process.\nThe host writes no discovery file for it. The handle carries what `auth-service.json` holds for a\nCLI start: the loopback `url`, `publicUrl` when a public face runs, and the per-start `cap`. The cap\nalone authorizes the loopback host actions, lifecycle retirement and managed-agent enrollment\nverification, so keep it in the authority process. `publicFace` takes the CLI's public face inputs\n(`port`, `url`, `trustedProxy`, `advertisedServer`, `agentProvisioningUrl`) under the same rules,\nand a face without a port refuses to start.\n\nTwo optional inputs serve a platform composition. `platformControl: { observeAssignment }` adds\n`platformControlAuthority` to the handle. It is a typed in-process method, served on no listener,\nthat issues the manager-service request family for the one control manager the backend assigned to\nthis account, under a derived `p_` owner. It reads the assignment fresh on every call and refuses\nan IdP token, another account, a stale revision, another instance or lifecycle, and an instance\nanother owner registered. It refuses `prepare` and `activate` while the assignment's named\npredecessor is still registered or frozen. The same input adds `platformControlReadiness(instanceId)`,\nthe route for a host that needs to know whether its assigned control manager is serving. It returns\nthat instance's attributed `status` reply and refuses any instance the current assignment does not\nname, or one whose gate another owner holds. It reads over the context's own connection, whose\ngrant is the assigned instance's `describe` and `status` and its own reply rail. That connection\nrenews in process like the context's other connections and never leaves it, so the host lends no\nhuman or operator credential to a worker, mints no control instrument per read, and does not read\nliveness off the manager process. Without the input both members are `undefined`.\n`standingRenewableTtlSeconds` is forwarded unchanged to the authority plane, which bounds it to 5\nto 86400 seconds. It is a trusted-host input for the renewal rehearsal, and no request or CLI flag\nsets it. SPEC \xA713.1 and \xA713.6 define the view.\n\nThe auth plane can renew a registered manager's\nfive standing credentials from the current service registration. Run-driver renewal still\nrefuses without an authoritative activated-run reader, so these handles do not yet make a\ncomplete pooled auth and delivery host. A fresh auth plane can initialize without a\ndelivery-admin responder. Reclaiming a held claim from a dead predecessor needs the delivery\ninstance first: its admin rail must complete the broker connection-liveness sweep before the\nauth plane takes the claim. An absent or inconclusive oracle refuses the reclaim.\n\n### Remote manager client composition\n\n`@cotal-ai/manager` exports the `remoteManagerClient` namespace, containing the stock remote\nrequest builders and response validators, and `registerRemoteManagerAuthority` for registration\nwith a host-issued prepare credential. It returns the process epoch and registration revision its\nown registration committed. When a later start of the same instance registers before this start\nauthorizes its serve grant, this start is refused with `expired`.\n`RemoteManagerIdentityState` describes the five private\nmanager identities stored under an explicit account-local root. Use these public exports when\ncomposing `ManagerOptions.remoteAuthority`; do not copy CLI validators or import private modules.\n`managerClusterArtifacts()` returns the canonical document, manifest and their digests used by\nregistration. Supply its `[document, manifest]` pair when constructing the activation request\nwith `remoteManagerClient.remoteManagerAuthorityRequest` and the stock registration proof.\nThe host still validates the artifact closure and current registration before activation.\nThe namespace includes closed standing/run renewal, admission, maintenance, enrollment and\nretirement helpers. It provides no signer or new grant. The host still owns authenticated issuance,\ncurrent registration and activated-run observations, and any guarded foreign-holder repair.\nAn embedding must preserve those checks and supply a supported runtime; the client exports alone\ndo not provide a pooled runtime, an authority service or a complete hosted context.\n\n### Long-lived endpoints take a bearer function\n\n`EndpointOptions.bearer` accepts either a string or a function, and the difference is not stylistic.\nA string is minted once, so when it expires (which it will: callout bearers live minutes) the\nendpoint has nothing to renew with. It will not present the dead token to the broker, since that is\na guaranteed denial that still costs a full auth-callout round trip. It refuses to reconnect, emits\n`warning` saying which case it is in, and retries on a widening backoff until the process\nre-authenticates and rebuilds it. Retry notices use `warning` rather than `error` because Node\nrethrows an unhandled `error` event and would kill a host the endpoint is still trying to recover.\n\nPass a **function** for anything that outlives one bearer. That is a renewal source: it is called\nahead of each expiry and again whenever a reconnect finds the cached bearer dead, and it requires\nexplicit `card.owner` and `card.actor`. The first-party surfaces already do this\n(`UserViewAuth.source`, the connector's `agentBearerCommand`). A string bearer is for a short\none-shot connection.\n\nLong-lived hosts must also subscribe to the endpoint's `warning` event. It carries conditions the\nendpoint is surviving, including failed credential renewal, reconnect retries, and a durable leave\nit keeps retrying after the broker refuses a durable channel's live subscription. A host may choose\nto ignore warnings for a one-shot endpoint whose awaited operation owns the verdict, but that choice\nshould be explicit. An unhandled warning is nonfatal and silent.\n\n## Booting the daemons\n\n### auth-service\n\n`runAuthService(args, store?)` reads its provisioned long-lived secret kinds (service keys, callout\naccount, issuer keys, owner secret) through the injected `SecretStore`; a host provisions those into\nthe store first. It is a **signer and identity authority**, not a scoped daemon: at runtime it holds\nthe data-account and callout-account signing seeds, the issuer's private JWKs, and the\nowner-derivation secret in process memory (`SecretStore.get` exports raw values). The IdP pin and the\nactor ledger are **not** store-injected: `runAuthService` resolves them under\n`userAuthStateDir(findCotalRoot(), space)`, a path relative to the process working directory, so a\nhost provisions those into that exact directory (neither `store` nor `COTAL_HOME` selects it). It\nalso writes an ephemeral `auth-service.json` discovery file there that carries the live exchange\ncapability. That file appears only after every plane is bound, so waiting on it is the readiness\nsignal: a host that also passes the daemon's pid to the provider's `ready()` gets a process-bound\nwait. The wait extends past the base timeout while that pid is alive, up to a fixed bound, and it\nends at once when the pid exits.\n\n```ts\nimport { runAuthService } from \"@cotal-ai/auth\";\n// store implements SecretStore over your secret backend; get() returns raw seeds into memory.\n// Provision the auth secret kinds into the store, AND the IdP pin + actor ledger under\n// userAuthStateDir(findCotalRoot(), space), before this call.\nawait runAuthService(\n  { values: { space, server: brokerUrl, port: \"8081\" }, positionals: [], raw: [] },\n  store,\n);\n```\n\n### delivery\n\n`runDelivery(args, store?)` runs from a **pre-minted scoped `delivery` cred** and never loads the\nsigner. Provide the cred either through the injected store (under\n`deliveryCredsKey(space, { injected: true })`) or with a\n`--creds` file; the two are mutually exclusive. The daemon re-fetches the cred from the store at 75%\nof its JWT lifetime and fails loud rather than riding to expiry, so **something must re-sign a fresh\ncred into that same store**. When that read finds the previous generation still there, the daemon\nreports the missed remint and retries in 60 seconds. The current cred stays live until its expiry,\nand the store is read once per retry rather than once per second.\n\n```ts\nimport { runDelivery } from \"@cotal-ai/delivery\";\nawait runDelivery({ values: { space, server: brokerUrl }, positionals: [], raw: [] }, store);\n```\n\nThat renewal is a **signer** operation, not the delivery daemon's:\n`remintDaemonCreds(root, space, store?, { preflight? })` (`@cotal-ai/workspace`) reads the `SpaceAuth`\nsigner **through the same resolved `store`** (`getSpaceAuth(store ?? workspaceSecretStore(root), space)`,\nkeys `auth/broker.json` + `auth/account.<key>.json`; the pre-split `auth/auth.json` monolith is\nmigration input and the container signer mount only) and re-signs the daemon creds (`delivery.creds` and the membership feed's\n`membership-rw.creds`) back into that store. The injected `store` is both the signer source and the\ncredential destination, never a split. `space` is **required** and validated against the store's signer, so a\nstore swapped to a different space cannot re-sign over the wrong broker's creds. `preflight` is a\ncaller-supplied proof that the broker accepts the credential. The reference `Manager` passes a\n`probeConnect` over its `servers`. It gates **every** candidate before overwriting the last-good,\nwhether the signer is a full bundle or a stripped projection: a bundle's JWT chain proves only that\nit is self-consistent and\nnamed the space, NOT that its account is the broker's *current* account for that space (two\n`createSpaceAuth(space)` calls yield same-named, different-account chains), so a same-label alternate\nsigner would otherwise mint a broker-dead cred and clobber the good one. The offline local repair (`doctor auth --fix`) has no preflight. It permits the overwrite only\nunder **authority continuity**: the candidate must be signed by the same account signing key (`iss`) as the current\n(already broker-accepted) cred. A same-label alternate account breaks continuity and is refused, full or\nstripped; a legitimate local re-sign is continuous and proceeds without a network. The reference\n`Manager` runs it on a schedule against its **own**\n`secretStore` (see below), so passing the manager and the delivery daemon the *same* store closes the\nrenewal loop end-to-end on an injected backend: the manager reads the signer from the store, re-signs\ninto it, and the daemon adopts each generation on a preflight-proven 75% timer. The stock\ncross-host composition cannot satisfy that by writing one filesystem and fingerprinting another:\n`Manager.start()` and every later remint challenge the daemon's `reloadStoreIdentity` and a\ndivergent pair is refused naming both stores. The identity is the store the daemon actually\nreloads: an injected coordinate, the workstation root only when `--creds` is\n`<root>/.cotal/<spaceSegment(space)>/delivery.creds` (matching the canonical arm), the\nfile's own directory for any other `--creds` path, or the workstation root. Uninjected\n`--creds` that names one real workstation while process cwd resolves another is refused\nat start, naming both, because membership-rw still uses `findCotalRoot`. A `--creds`\npath that is not under any `.cotal` tree is not that case and is not refused here. It never\nwalks ancestors with `findCotalRoot`. No bound daemon is not a named\nstore, so start proceeds; a later daemon on a foreign store is refused on the next remint.\nThe first-party filesystem adapter declares its workspace-root identity on the store itself. Other\ninjected adapters declare their stable coordinate on `SecretStore.identity`, or name it in\n`COTAL_SECRET_STORE` on both processes. It never throws: it\nreturns per-file results (`skipped: \"no-auth\"` when the store holds no signer records),\nso the caller must check them or the cred still rides to expiry. A composition whose signer lives in\nKMS/Vault simply injects that store; no bespoke renewal is needed. A `--creds` file path must be\nreplaced atomically before the 75% read. The signer can now be injected behind the store seam, which\nresolves custody. The remaining hosted gap is signer **isolation**. The seed is still decrypted\nin-process at the manager's uid, so it needs an OS sandbox or remote signer.\n\n### Supervisor signing authority\n\n`@cotal-ai/manager` exports the `Manager` class; there is **no** `runSupervise(opts)` runner. The\nprivate CLI `runManager` also does broker-reachability checks, space/default resolution,\nroster/launch parsing and materialization, installed-extension resolution, signal handling, staged\npre-spawn, and the forever wait. A host composes that lifecycle itself around `Manager`:\n\n```ts\nimport { Manager } from \"@cotal-ai/manager\";\nconst mgr = new Manager({ space, servers: brokerUrl, workspaceRoot });\nawait mgr.start();          // then wire your own SIGINT/SIGTERM -> mgr.stop()\n```\n\n`stop()` runs once. A later call joins the stop in progress and settles with it, and a call that\nasks for a different `withAgents` than the running stop is refused.\n\nUnlike delivery, the manager is **not** a pre-minted-scoped-cred daemon (auth-service is also a\nsigner: it holds fewer artifacts than the full trust bundle, but its data-account signing seed still\ngrants complete data-account mint authority on compromise, so this is not least-privilege). On `start()`\nthe manager reads its space's full trust chain **through its `secretStore`** (`getSpaceAuth(this.secrets,\nthis.space)`, composed from `auth/broker.json` + `auth/account.<key>.json`; a container may instead\nmount a stripped signer bundle at the legacy `auth/auth.json` key) and **self-mints** its supervisor cred and renewals from the\ndata-account signing seed. In static mode it also mints every per-agent cred from that seed; in user\nmode agents instead receive callout-minted bearers, but the manager still holds the signing seed for\nits own creds and renewal. So a hosted supervisor is a **trusted per-tenant account-signer process**,\nnot a least-privilege connect client. It additionally requires a `~/.cotal/meshes/space.<key>.json`\nregistry record and the workspace user-auth marker to start in user mode. `ManagerOptions.secretStore`\ninjects the one `SecretStore` the manager uses for **the signer itself (the split trust\nrecords)**, daemon-credential renewal (`remintDaemonCreds`), and per-agent secrets,\ndefaulting to the workspace filesystem store; pass the delivery daemon the *same* store for end-to-end\nhosted renewal. The store declares the same identity on both processes, or both set\n`COTAL_SECRET_STORE` to the same coordinate. The manager\nremints no daemon credential when the daemon names a different store, including a daemon that binds\nafter start; it keeps running and serving its own agents, so one space can carry a manager on more\nthan one workspace root. That manager also stays off the space's renewal lease, so a manager or a\n`cotal doctor auth --fix` on the daemon's store can still take it. Pointing several managers at one coordinate is safe: the store identity\nalone cannot pick an owner (it carries no holder and no tiebreak, so every manager sharing the store\nmatches), so the manager that also holds the space's renewal lease is the one that remints and the\nrest skip it. Without that lease two owners would remint on independent timers with no ordering\nbetween them, and one write would land between the other's re-sign and its fingerprint-only\n`reloadCreds`. `cotal doctor auth --fix` takes the same lease before it re-signs, so a live manager\nand a local repair never race each other either. The signer IS now injectable: a hosted composition injects a KMS/Vault store and no\nsigning seed lands on the hosted disk. What remains is signer **isolation**. The seed is decrypted\nin-process at the manager's uid. That issue needs an OS sandbox or remote signer; it is no longer a\ncustody problem. The other knobs are `workspaceRoot` and the process-global `COTAL_HOME`.\n\n> Scope note: the **static-auth** operator paths (`cotal spawn`/`join`/`status`/`web`, via\n> `mesh-target` \u2192 `connect`/`preflight`) still read the signer from the local split records (sync\n> `loadSpaceAuth`). That is the single-machine composition, where the signer is on local disk by the\n> static-auth model; multi-tenant hosting runs **user mode**, which never mints from on-disk trust. The\n> store-injectable signer path is the hosted-server set: the manager, `remintDaemonCreds`, and delivery.\n\nThe typed remote-manager authority contract includes a one-shot terminal phase. A host implements\n`remoteAuthority.prepareAgentRetirement` to revoke the managed grant and finish its resumable\nrelease while preserving the UID, then `remoteAuthority.mintRetirementRequester` returns the\nhost-signed JWT for a fresh participant-owned nkey. The credential is pinned to the authenticated\nowner, server-derived manager serve principal, current instance epoch, and exact target lifecycle.\nThe manager then uses the existing auth `retireLifecycle` rail with the operation id derived by\n`managedRetirementOpId(target.lifecycleUid)`. This derivation is the reference remote-Manager\ncomposition's closed contract, not a rule for every retirement entry point; interactive retirement\nkeeps its existing operation identity and remains compatible. The `retireLifecycle` rail independently\nrecomputes the managed id from its broker-pinned target before any gate, head, intent, or barrier\naccess, so mint-time validation is not the terminal boundary. A failure keeps\nthe alias held. This does not expose the auth barrier or give the participant signer authority.\n\nIf the participant disappears after prepare, the host finishes the retirement itself on the auth\nservice's loopback face: `POST /managed-lifecycle/retire` (exported as `MANAGED_RETIRE_PATH` from\n`@cotal-ai/auth`) with the `Bearer <cap>` from `auth-service.json` and only\n`{ owner, actor, lifecycleUid }`. It has the interactive door's guards (POST only, no `Origin`, JSON,\ncapability, closed body) and is never served on the public face. The managed grant must already be\nrevoked at that uid, or it answers 409. It runs the same `managedRetirementOpId(uid)` operation as\nthe rail, and the rail and the door share one in-process flight, so a late participant request and\nthe host call converge on one barrier.\n\n| lifecycle head | answer |\n| --- | --- |\n| absent, or `retired` at another uid | `200 { retired: false, lifecycleUid, notStarted: true }` |\n| `active`/`retiring` at another uid | `409` |\n| `retired` at this uid | `200 { retired: true, lifecycleUid, alreadyRetired: true }` |\n| `active`/`retiring` at this uid | the barrier runs, then `200 { retired: true, lifecycleUid }` |\n\nDeprovisioning durables stays with `deprovisionAgent` and a `deprovisioner` credential. Pass `memberChannels` to both to also purge the retired lifecycle's durable membership rows on those concrete channels. The manager fills that list from the launch's concrete read channels and the delivery daemon's read-only `lifecycleMemberships` admin verb. When that verb cannot answer, rows on other channels stay retained, the teardown logs the inventory as incomplete, and retirement remains held pending retry rather than releasing the alias. Each teardown examines two exact consumers, one ACL key and the named member keys. KV deletion uses a native revision condition; a lost condition with a live replacement refuses rather than claiming absence. Consumer INFO checks before and after DELETE distinguish verified prior absence from disappearance. `acknowledged` counts native DELETE success replies. `disappeared` counts observed live-to-absent consumers and live KV rows whose conditional purge lost to a competing deletion. These KV rows were present at the first read, so they never count as prior `absent` or as this caller's `deleted`. The ACL and membership subtotals preserve that distinction. Neither establishes which concurrent caller uniquely removed a consumer, so `consumers.deleted` and the total `deleted` are `null` when a consumer disappears without a winner token. A repeat after verified absence reports zero, not an invented deletion. `refused` counts slots whose cleanup or state remains uncertain. A partial failure raises `DeprovisionError` carrying these bounded observations. The Manager's static sweep preserves unknown uniqueness rather than adding acknowledged requests as physical removals; its slot totals remain separate.\n\nA host that resumes retained managed actors also implements\n`remoteAuthority.validateRetainedAgent`. The participant sends back the actor token and sentinel it\nalready holds, plus the `nextRegistrationProof` returned by the activation response. That proof is\nhost-issued after registration and binds the manager owner, actor, lifecycle, identity nkeys, current\nregistration revision, and serving epoch. The host checks it against the current open manager gate,\nvalidates the retained secrets against its current managed row, and returns only the non-secret\nauthority shape. The manager binds every result coordinate and the returned authority back to its\ninventory before use. Do not copy the provider's `issuer.json` or `callout.json` into the participant\nstore. Both contain private signing or exchange authority.\n\nThe same composition supplies `remoteAuthority.agentBearerExchangeUrl`, the pinned public auth-service\nbase used by retained children. Remote adoption launches `agent-bearer --exchange-url <base>`; it must\nnot select the local `--dir` arm, which depends on a host-only auth-service process record.\n\nA host that lets a remote participant spawn FRESH managed agents implements\n`remoteAuthority.enrollManagedAgent`. The participant generates the standing actor token, writes it\nat mode 0600, and passes only its SHA-256 digest with the requested actor, label, role,\ncapabilities, and channel lists, so the plaintext secret never leaves the participant machine. There\nis deliberately no `lifecycleUid` input: the host selects the UID, because only the host sees the\nretirement tombstones that make a UID permanently unusable, and a participant-chosen UID could aim a\nfresh grant at a dead incarnation. The host authors the ledger grant, pre-creates the lifecycle-keyed\ndurables, clamps the requested lists to what the spawning owner already holds, and returns the owner,\nactor, chosen `lifecycleUid`, the space sentinel credentials, the effective lists, and\n`agentBearerExchangeUrl`. The manager binds every returned coordinate, re-keys the secret family onto\nthe returned UID, and launches `agent-bearer --exchange-url <base>`. When the hook is absent a\nsignerless manager refuses the user-mode spawn rather than authoring a local grant the host knows\nnothing about.\n\nBoth managed-agent operations ride the one verified `POST /manager-service-authority` transport as\n`kind: \"manager-managed-agent-enrollment\"` and `kind: \"manager-managed-agent-prepare-retirement\"`.\nStock `cotal auth-service` answers both itself, because it owns the actor ledger and the space's\nprovisioning authority. An enrollment writes the managed grant at a fresh UID with the supervising\nactor as its parent, provisions that UID's durables, and returns the daemon's public exchange URL as\n`agentBearerExchangeUrl`; a daemon started without `--exchange-public-port` refuses enrollment. A\nretry with the same token digest answers the same UID while the supervising actor's current grant\ncovers it, and a fresh enrollment's refusal otherwise. While the agent's grant stands, an enrollment\nwith another digest is refused with `conflict` until that lifecycle's retirement is prepared. A\nprepare-retirement releases the target UID's broker footprint and then revokes its grant, so the\nmanager's terminal rail finds the grant gone. A platform that keeps these writers in its own storage\nintercepts both kinds instead. It terminates its own public route, authenticates the human there,\nand asks the auth service for the decision at\n`POST /manager-service-authority/verify-enrollment` (exported as `VERIFY_ENROLLMENT_PATH` from\n`@cotal-ai/auth`) with the `Bearer <cap>` from `auth-service.json` and only `{ owner, request }`. That\ndoor has the managed retirement door's guards, derives the caller's scope from the local ledger rather\nthan the body, checks the manager gate and registration proof in-process, and answers\n`{ authorized: true, owner, actor, instanceId, serveEpoch }`. `authorizeRemoteManagedAgentEnrollment`\nand `authorizeRemoteManagedAgentPrepareRetirement` are exported too, for a host that composes the\ndecision without the HTTP hop. Both require ledger scope `supervise`; `spawn` and `admin` do not\nimply it.\n\nA host that runs managed agents on its own hosted runtime adds two more kinds on the same transport.\n`kind: \"manager-managed-agent-runtime-create\"` asks the host to create the runtime for one agent it\nalready enrolled, and `kind: \"manager-managed-agent-runtime-status\"` reads that runtime's state. Both\ncarry the manager envelope plus `target: { owner, actor, lifecycleUid }`, the coordinate the\nenrollment returned. Both schemas are closed. An unknown top-level or target field, including\n`providerRef`, `handle`, or `name`, is refused as `bad-request`, because the host alone issues and\nholds provider references. There is no stop, adopt, or probe kind: stop goes through\nprepare-retirement. Stock dispatch refuses both kinds with `unimplemented`, and the verify-enrollment\ndoor decides them. `authorizeRemoteManagedAgentRuntimeCreate` and\n`authorizeRemoteManagedAgentRuntimeStatus` apply the enrollment door's checks: host space, a target\nowner equal to the authenticated owner, the manager actor's own ledger row with `supervise`, the open\ngate, the current serve epoch, and the registration proof. Each returns only\n`{ owner, instanceId, actor, target }`. The door touches no provider and writes nothing. The host\nmatches the decision to its own intent record and performs the create afterwards. The host answers\nwith `state` (`reserved`, `creating`, `bound`, `create-unknown`, `closing`, or `closed`), `readiness`\n(`ready`, `bound-not-ready`, or `none`), and an optional `retirementPhase`. A manager builds requests\nwith `remoteManagerClient.remoteManagedAgentRuntimeRequest` and binds the answer with\n`remoteManagedAgentRuntimeState`.\n\nAn enrollment result may also carry `runtimeIntent: { state: \"reserved\" }` when the host reserved a\nhosted runtime for the agent. It is display-only. Older hosts omit it, the manager binds both shapes\nto the same material, and nothing reads it as authority.\n\nNo stock door lets a platform control holder launch or retire an agent for a signed-in user. The\nmanaged-agent kinds above act only under the authenticated owner and refuse a caller that is not\nthat user, so a platform could only run a user's agent by holding the user's login or by enrolling\nthe agent under its own owner. Both are refused. The\n[delegated user launch intent](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/delegated-user-launch-intent.md)\ndesign and SPEC \xA713.16 define the smallest addition. The user admits one launch or one retirement\non the host's authenticated route. The holder consumes that intent once, from its current\nregistration, epoch and lifecycle. The host then enrolls the agent under the user's `u_` owner with\nthe user's own actor as its ledger parent, so the envelope walk, membership and channel lists match\nwhat the user's own manager would produce. Retirement keeps the prepare, provider closure and\nterminal barrier order, and the host finishes it when the holder is gone. A launch the host had to\nundo keeps its agent name held until the host process that ran it confirms it has stopped, and\nwhile the name is held the host also refuses it to the user's own manager. `@cotal-ai/auth` ships the\ntwo decisions, `authorizeDelegatedUserIntentAdmission` and `authorizeDelegatedUserIntentExecution`,\nfor a host that owns an intent store and those writers to compose on its own routes. Both read the\nholder's gate through the handle's `observeManagerGate`, present with `platformControl`, which reads\nover the context's own connection, so the host opens no second data-account connection. It is an\nobservation for the decision: the consuming CAS and the writers still apply their own checks. The\nconsuming CAS pins the incarnation of the host process that runs the flight as the executor, never\nthe auth plane's, because the two can restart independently. `platformControl.host` names that\nprocess's reverse-DNS endpoint, the closure digest of its \xA713.7 cluster and every contract artifact\nthe closure needs, and the auth plane self-authorizes that one name.\n`registerHostIncarnation(instanceId)` publishes the artifacts, registers that instance through the\nceremony the plane runs for itself, and returns `{ instanceId, processEpoch }` with the epoch that\nregistration committed. The host calls it at every start with its persisted instance id, before it\nadmits or recovers any flight, so a restart fences its predecessor. The first registration of an\ninstance commits epoch 0, which is open and serving like any later epoch, and each later start of\nthat instance commits the previous epoch plus one. A consumer compares epochs for equality and never\nreads 0 as absent or not ready. A start\nwhose confirming read of the gate finds that a later start of the same instance registered is\nrefused with `conflict`. The returned epoch is a committed coordinate and stays current only until\nthe next start registers, which can happen before the call returns. `observeHostGate(instanceId)`\nis a point-in-time read of an executor's gate, and answers null for an absent gate; a sweeper\ndecides on it. `awaitHostFence(instanceId, processEpoch)` resolves with the gate once it is no\nlonger open at that epoch, and with null once it is absent. It takes any non-negative safe integer\nepoch, 0 included, and refuses any other value with `bad-request`. The host arms it with its returned\nincarnation before it admits or recovers any flight, and stops serving when it resolves. It polls\nthe gate, because no runtime credential may watch the auth bucket. The\nhost's launch writer first activates the agent's lifecycle at the pinned UID through the handle's\n`activateManagedLifecycle`, before any ledger row or durable, and its compensation runs the same\ncall before the terminal barrier, so a launch whose agent never exchanged its bearer still reaches\nthe terminal barrier at that UID. The launched agent exchanges its bearer on the context's public\nface, so the host starts it with `publicFace`, and its retirement writer ends at\n`POST /managed-lifecycle/retire` with the handle's `cap`. Stock dispatch refuses both kinds as\n`unimplemented`. The holder's composition passes\n`remoteAuthority.executeDelegatedUserIntent`, which posts the execution request and binds the answer\nwith `parseRemoteDelegatedUserIntentExecutionResult`. It then starts the agent with\n`startAgent({ ..., delegatedIntent: { intentId, owner, parent } })` and retires it with\n`retireDelegatedAgent(name, intentId)`, which stops the agent only after the host confirms\n`retired: true` for its exact target. A delegated agent's stop, exit or failed launch keeps its name\nheld until that retirement confirms.\n\nRemote user-mode managers must also supply `remoteAuthority.authorizeAdmin`. The manager builds each\nrequest only from the caller tuple parsed from the broker-authenticated endpoint subject, then relays\nthat tuple over the current registered manager lifecycle. HTTPS does not separately authenticate the\nrelayed caller. The host authenticates the manager operator, binds the request to the current open\nmanager gate, registration proof, serving epoch, and identity nkeys, then reads the caller's unified\nauthoritative row fresh. It returns only the manager owner and `authorized: boolean`, with every request\ncoordinate echoed. Missing, revoked, narrowed, foreign-owner, and stale-lifecycle callers all return\n`false`; malformed coordinates or corrupt and unavailable authority state fail the operation. The\nparticipant never reads or mirrors the host ledger, and the remote branch has no local fallback. The\nsame callback gates all `manager.admin` handlers, any-mode cross-owner control, and `ps` or `inspect`\ncross-owner visibility. Launch keeps its owner-equality policy.\n\nThe remote authority's instance executor remains the scoped maintenance credential for clean service\nderegistration and exact instance registration operations. It carries no records-stream consumer\nlifecycle authority. The manager's boot `goalidx` sweep uses the authenticated host operation, which\nreturns parsed `goalidx.manager.<owner>.>` entries for that owner only. The host keeps the sealed\nconsumer connection and its create/delete rights. The five-minute executor already renews through\n`remoteAuthority.renewExecutor`. The signerless supervisor, serve, goal-writer, session-ledger and\nper-run driver credentials do not yet have a complete remote renewal and adoption path. The\n[hosted runtime contract](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/hosted-runtime-contracts.md) records the bounded additions and\ntheir ownership; it is not a shipped pooled service.\n\n**Signer isolation needs an OS sandbox.** The default pty runtime\nruns agent children under the *same* OS uid and the *same* `workspaceRoot`, so mode-0600 on\nthe trust records does not stop a hostile same-uid agent from reading their absolute paths. The reference\n[deploy](deploy.md) tree does not solve this: it mounts the signer into the agent's own container, so\nits phase-1 boundary isolates agents from each other, not the signer from the agent. A hosted\ncomposition must run the manager/minter that holds the signer in a different uid, container, or mount\nnamespace from the agent children, which mount no signer at all; that split is future\nhosted-composition work, so until it (or a remote/injected minter) exists, do not run untrusted\nagents under this manager.\n\n### Delegated seats outside the manager's filesystem\n\nThe [portable lifecycle bootstrap](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/portable-lifecycle-bootstrap.md)\ndesign and SPEC \xA713.17 define how a managed agent that `enrollManagedAgent` already enrolled starts\nin a child that cannot see the manager's filesystem. The ordinary `spawn` path writes the token and\nsentinel under the manager's workspace root and hands the runtime a launch whose bearer command and\nmaterial file are paths on that filesystem, so such a child needs this path instead.\n\nThe delegation boundary is one optional runtime method. A runtime that implements\n`Runtime.spawnDelegated(launch, handoff)` receives two values and no paths: a `DelegatedSeatLaunch`\n(connector name, persona text, model and the other launch choices) and a `ManagedLifecycleHandoff`\n(space, owner, actor, the host-chosen `lifecycleUid`, broker and IdP pins, the pinned exchange base,\nthe sentinel, the channel lists, and the raw actor token). The manager enrolls once, as it does\ntoday, and builds the handoff from what it holds. It never sends the token to the host, never copies\na file from its workspace or secret store, and never builds a local launch for that seat. No signer,\nissuer or callout record, loopback capability, provisioner or manager credential, control token, or\nmanager path crosses. A spawn choice that only the manager's host can honour is refused before\nenrollment: `--resume`, a manifest agent's `continuity: exact`, `--cwd`, and any shared MCP server,\nwhether from `--share-tools` or the config default (`--share-tools none` passes).\n\nThe runtime creates one provider resource under `managedRuntimeKey(target)`, writes the handoff into\nit as one 0600 file and the persona beside it, and runs the stock bootstrap there:\n`cotal spawn --config <persona-file> --space <space> --name <actor> --expect-owner <owner> --expect-lifecycle-uid <uid>`\nwith `COTAL_MANAGED_HANDOFF_FILE` naming the file. `delegatedSeatCommand` builds that argv. The\n`cotal` entry reads the file into memory, deletes it and drops the variable before it parses flags,\nprints help or loads extensions, so every outcome, a refusal of its own flags included, leaves no\nfile. It refuses before any broker connection or exchange request when the\nspace, owner, actor, or lifecycle UID differ from the expected values, and then runs the\nenrollment-redeem consumer: it registers the mesh in its own home, writes the token to its own 0600\nfile, and exchanges it through `agent-bearer --exchange-url` unchanged. It never enrolls, redeems, or\nmints a token or UID.\n\nReadiness is still mesh presence. A create whose answer is lost leaves the handle running, so the\nlaunch settles uncertain and stays held; the manager never retries it. A provider read that finds no\nresource under the key is not an exit, because the create may still land. Every close by\n`managedRuntimeKey` is fenced: it completes only once the create was answered or the provider refuses\nany later create under the key. A provider that names its own resources may run the create as a\ndurable operation keyed by `managedRuntimeKey` and close through the identifier its authenticated\ncreate response returned, kept where the host can read it without the manager. Only that response\nbinds an identifier to the key; one derived from the key or found by name or listing is never closed\nor adopted, and while the response is unknown the launch stays held. Every stop, the reap of a child\nwhose parent exited and `Manager.stop({ withAgents: true })` included, runs `prepareAgentRetirement`\nfor the UID-exact target, then `stop()` on the handle `spawnDelegated` returned, then the terminal\nbarrier. `preparePreservation` refuses a cut that holds a delegated seat, and a `Manager.stop()` after\na refused cut retires the seat through the same steps. After the manager is gone\nthe host runs the same steps, makes the same fenced close by `managedRuntimeKey`, and finishes at\n`MANAGED_RETIRE_PATH`. Supply `spawnDelegated` only from a runtime whose host can make that fenced\nclose without the manager. The enrollment redeem\n(`COTAL_ENROLLMENT_FILE`) stays for lifecycles whose token the host generated itself; a host cannot\nmint one for a manager-enrolled lifecycle because it holds only the digest.\n\n## Provisioning a space (one-space reference shape)\n\n```ts\nimport { createSpaceAuth, setupSpaceStreams, ensureDefaultDeliveryClass, mintCreds, newIdentity } from \"@cotal-ai/core\";\nconst auth = await createSpaceAuth(space);                       // trust bundle (in-memory seeds)\nconst provisionerCreds = await mintCreds(auth, newIdentity(), \"provisioner\");\nawait setupSpaceStreams({ servers: brokerUrl, space, creds: provisionerCreds });\n// SPEC section 4: write the default delivery class at space creation so it is wire-discoverable,\n// never inferred from the resolution fallback. A daemon-backed space is \"durable\".\nawait ensureDefaultDeliveryClass({ servers: brokerUrl, space, creds: provisionerCreds, deliveryClass: \"durable\" });\nconst deliveryCreds = await mintCreds(auth, newIdentity(), \"delivery\");\n// put deliveryCreds into your SecretStore under deliveryCredsKey(space, { injected: true })\n// (@cotal-ai/workspace) before booting delivery \u2014 the key is per-space, not the bare kind.\n```\n\nRendering the broker config for a user-auth space is `serverConfig(broker, spaces, { storeDir,\nmaxFileStore?, extraAccounts })`, where `extraAccounts` must include the callout account from\n`createCalloutAuth` so the auth-service has a broker account to answer on. That account never shares\nthe data account. `maxFileStore` is an optional positive integer byte cap; any other value throws.\n\nBroker trust and space accounts are separate authorities: `createBrokerAuth` mints the one\noperator + system account a broker trusts, `createSpaceAccountAuth(broker, space)` signs each\ntenant's data account under it, and `serverConfig(broker, spaces, opts)` renders them all into one\nconfig. A host composition can therefore provision several spaces on one broker today. `cotal up`\nrenders that config from every tenant the root's auth directory holds, so booting one space keeps\nthe broker trusting its siblings, and it refuses to render at all while any account record is\nunreadable. The rest of the CLI lifecycle is still broker-wide: `down`, `clean` and `backup` refuse\non a multi-space root rather than scoping to one tenant, and the per-space lifecycle is the\nremaining multi-space operator layer. See\n[Known gaps](#hosted-composition-gaps).\n\n## Hazardous provisioning primitives\n\n`mintCreds`, the full `Profile`/`CredentialKind` matrix, `createSpaceAuth`, and `stripSpaceAuth` are\nlow-level operator primitives. Handle them as account-authority material:\n\n- A holder of a `SpaceAuth` (or a `stripSpaceAuth` bundle, which **keeps** the data signing seed) is\n  a fully-trusted tenant-account authority: it can mint `admin`, `provisioner`, and destructive\n  profiles, not merely `supervisor`, and mint a DM-reading identity. `createSpaceAuth`'s full result\n  holds operator, system, and account seeds in memory.\n- Choose `profile` and `MintOpts` from **server-side constants**, never from tenant input. `MintOpts`\n  can widen the bounded TTL defaults; cap it at your boundary. `CREDENTIAL_LIFETIMES` is a policy\n  record, not an authorization boundary.\n- Never log signer material or export it into env. Do not co-locate signer access with an untrusted\n  connector/runtime process at the same OS uid (file permissions do not contain a same-uid reader;\n  see the manager's isolation note). Segregate per tenant; rotate on compromise\n  (`rotateDataAccountSigningKey`).\n\n## Hosted composition gaps\n\nThe primitives above are present as exports, but three capabilities are **not** cleanly composable\nfrom the public contract today. Each is tied to work in flight; a host either waits for the seam or\nscopes the capability out. None is a wire concern.\n\n1. **Delivery immediate live eviction and a fully-hosted membership feed.** The renewable\n   `membership-rw.creds` is now a `SecretStore` kind. `startMembership` reads it through the\n   injected store, and the manager re-signs it there. The graph-feed writer therefore renews on a hosted\n   backend (its data connection adopts each generation on a preflight-proven 75% timer). What still\n   reads from a fixed on-disk path are the *static* `membership-observer.creds` and\n   `connection-evictor.creds` ($SYS creds, minted at the `up` that provisions the account and renewed by `up --rotate-sys`) and `membership.json`\n   (`{accountId}`, non-secret config); those, plus the private provisioning wrapper, keep immediate\n   live eviction and a fully-hosted feed a partial gap. Missing files degrade membership to\n   traffic-only and make live eviction refuse (loudly). The supported delivery contract here is the\n   Plane-3 durable backstop.\n2. **Supervisor signer isolation.** `ManagerOptions.secretStore` now injects the one `SecretStore` the\n   manager reads/writes every secret through, including the composed `SpaceAuth`\n   signer (the split trust records), its daemon-cred renewal, and its per-agent kinds. What remains is process\n   isolation: the manager still decrypts the signer in-process at its uid, so untrusted agent children\n   must run under a different uid/container/mount namespace or behind a future remote signer.\n3. **Per-space lifecycle on a shared broker.** The trust layer is multi-space\n   (`createBrokerAuth` + `createSpaceAccountAuth` + N-space `serverConfig`, persisted as\n   `broker.json` + `account.<key>.json`) and `cotal up` renders the whole tenant list, but there is\n   no per-space provisioning verb and no per-space teardown/backup/restore: the CLI's broker-wide\n   lifecycle verbs refuse on a multi-space root, naming the tenants.\n   This is the remaining multi-space operator layer.\n4. **A non-Better-Auth production IdP.** The exchange core (`createIdpBridge`) is EdDSA-generic, but\n   the stock provider and login client are Better-Auth-endpoint-shaped, `cotalAuthProvider`\n   self-registers on import (colliding with a host-owned provider under `resolveAuthProvider`), and\n   the login flow speaks Better Auth's device-code endpoints. A different IdP is a host-built auth\n   composition on the low-level primitives, not a configuration change (see\n   [the IdP callout contract](identity-and-auth.md#the-idp-callout-contract)).\n\n## Hosted durability\n\nSpace-durable **coordination** state (chat/DM/task history, live presence, membership runtime, the\ndurable ACL registry, leases) lives in **JetStream**, written by the delivery daemon and the\nendpoints. It is broker-resident and needs no host-side durable path.\n\nWhat is **not** in JetStream, and is hosting-critical, is trust and authorization state a host must\nplace and keep:\n\n| state | class | where today | hosted injection |\n|---|---|---|---|\n| full `SpaceAuth` trust chain (`auth/broker.json` + `auth/account.<key>.json`, composed; a stripped signer bundle may instead be mounted at the legacy `auth/auth.json` key) | signing authority | `SecretStore` | `SecretStore` (manager + renewal) |\n| auth kinds: callout account/creds/xkey, issuer private keys, owner-derivation secret, data-signer projection | signing/identity authority | four `SecretStore` kinds | `SecretStore` (auth-service) |\n| `delivery.creds` | standing scoped cred | `SecretStore` or `--creds` | `SecretStore` (delivery) |\n| actor ledger, IdP pin | authorization + trust config | ambient `userAuthStateDir(findCotalRoot(), space)` | none (root-relative; not `store`/`COTAL_HOME`) |\n| `membership-rw.creds` | standing scoped cred | `SecretStore` | `SecretStore` (delivery + manager renewal) |\n| membership-observer / connection-evictor creds + `membership.json` | scoped $SYS creds / config | workspace filesystem | none (see gap 1) |\n| manager agent creds, actor tokens, sentinel creds | lifecycle authority | `SecretStore` | `SecretStore` (manager `secretStore`) |\n| `~/.cotal/meshes/space.<key>.json` record (holds IdP trust pins/root pointers) | non-secret, integrity-critical | machine home | process-global `COTAL_HOME` only |\n| auth-health, renewal records | non-secret diagnostics | workspace filesystem | `workspaceRoot` |\n\nThe `SpaceAuth` trust chain and the auth-service store kinds are **separate** identities/projections,\nnever parts of one document. `auth-service.json` (the live exchange capability) is ephemeral runtime\nstate, not durable, but is sensitive while the daemon runs. `@cotal-ai/workspace` is machine-local\noperator tooling by design; personas, PID files, and the `current-mesh` pointer are truly local and\nmust **not** sit on a hosted durable path. Everything classed above as an authority is what a hosted\ncomposition must provision and persist: signer-bearing server secrets now have `SecretStore` seams;\nthe remaining non-injectable rows are the explicit ambient `workspaceRoot`/cwd paths above.\n\n## See also\n\n- [Substrate stability](stability.md): what v0.3 and the 0.x packages guarantee, and the projected v0.4 break.\n- [Identity and auth](identity-and-auth.md): the profile matrix, the signer, and the IdP callout contract.\n- [Delivery daemon](delivery-daemon.md): the Plane-3 durable backstop.\n- [Deploy](deploy.md): the reference container against an external broker.\n"
     },
     {
       "slug": "examples",
@@ -19748,7 +19762,7 @@ var DOCS_BUNDLE = {
       "title": "Run a mesh",
       "kind": "Guide (informative)",
       "summary": "Day-to-day operation of a local mesh: what cotal up actually runs, how spawning resolves personas, harnesses, and models, how to reach a mesh from any directory, and the operator-only maintenance v\u2026",
-      "body": "# Run a mesh\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nDay-to-day operation of a local mesh: what `cotal up` actually runs, how spawning\nresolves personas, harnesses, and models, how to reach a mesh from any directory, and the\noperator-only maintenance verbs. Every command's full flag set is in the\n[CLI reference](cli.md).\n\n## The stack\n\n`cotal up` brings up the whole local stack and bare `cotal down` stops it. Managed\nagents stay running as unmanaged OS processes; pass `--with-agents` to take them\nwith the stack. Seats of the built-in pty runtime run inside the manager process, so\nthey stop with the manager either way. Ctrl-C on a foreground `up` follows the same sparing rule\nand prints the same report as bare down; when the manager cannot prove it can spare,\nCtrl-C refuses the teardown and leaves the stack running, and you end it with\n`cotal down --with-agents`. A current manager records what its stop does with its seats before\nbare down signals it. A pre-pin legacy manager instead receives a reduced-guarantee\nwarning and is signalled according to the documented upgrade contract. Its running binary\nmay still carry the older destructive SIGTERM handler, so the CLI does not claim its\npre-signal agent inventory was spared; those agents may have been reaped.\n\n- **Broker**: a local `nats-server` (logs to `.cotal/nats.log`).\n- **Delivery daemon**: the durable backstop, auth mode only\n  ([what it does](delivery-daemon.md)).\n- **Manager**: a detached supervisor answering the control plane, so\n  `cotal spawn --detach` and the `cotal_spawn` tool work right after `up`.\n\nCotal creates the presence bucket in memory storage. Its records are liveness that every endpoint\nrewrites each heartbeat, so nothing is lost when a broker restart empties it, and nats-server's file\nstore write latch cannot reach it. A broker stop removes the memory stream itself, so every `cotal up`,\nincluding the resume after `cotal down --preserve-state`, creates it again before any daemon starts.\nJetStream fixes a stream's storage class when it is created, so a presence bucket created file-backed\nby an older cotal stays file-backed until that stream is recreated.\n\nA file-backed presence bucket can remain open and watchable while refusing every write. A bound\nendpoint reports this as `presence-write-stuck` after one full presence TTL of consecutive failures.\nThe roster is last-known while that condition is active. Restarting the broker clears nats-server's\nin-memory store latch and preserves the JetStream root. Current credentials split the required stream\nauthority: the `cotal up` provisioner can create the presence stream but cannot delete it, while the\nteardown credential can delete it but cannot recreate it. Cotal therefore reports the condition but\ndoes not attempt an unsafe partial delete-and-recreate. Stop and restart the broker to recover.\nA broker below nats-server 2.14.5 carries the latch (nats-server fixed it in 2.14.5). When `cotal up` starts or finds such a broker and the space's presence bucket is file-backed, it says so. A memory-backed bucket gets no warning. A broker below the SPEC \xA713.12 floor of 2.12 is refused at connect with the floor sentence.\n\nThree modes:\n\n- **Default (static auth).** JWT-authed, on by default: sender authenticity and per-agent\n  ACLs, enforced by the broker ([how](identity-and-auth.md)).\n- **`--user-auth --idp <url>`.** Per-user auth: people `cotal login` once, the operator\n  grants their agents on the actor ledger, and every connect is authorized live against\n  that grant. Starts the space's auth service alongside the broker\n  ([how](identity-and-auth.md)).\n- **`--open`.** An unauthenticated, live-only dev mesh (no auth, no delivery daemon). For\n  quick local experiments.\n\nThe broker and local services bind **loopback** by default. `--host 0.0.0.0` widens the broker\nbind independently of the auth mode, so \"network-reachable\" never silently means\n\"unauthenticated\". With no explicit `--server`, `cotal up` auto-selects a free local port when\nthe default address is already held by another project; an explicit `--server` fails loud on\ncollision.\n\n`--host` is a boot flag, not a live rebind. A fresh `cotal up` writes the generated\n`.cotal/auth/server.conf` (project-local, not `~/.cotal`) with that bind and starts nats against\nit. If anything is already answering at the mesh URL, `up` refreshes the recorded mesh and\nleaves the running nats listener alone, so passing `--host 0.0.0.0` on a live or orphaned\nbroker does not change who can connect. To change the bind: `cotal down`, then `cotal up --host\n<addr>` against a stopped broker so the generated file is rewritten. Do not edit `server.conf`\nby hand; the next real boot overwrites it.\n\nOn a stopped shared broker, `up` renders every persisted space account and every enabled\nspace's auth-callout account into the resolver preload, regardless of which space starts\nthe broker. A missing callout account for an enabled space stops the boot rather than\nstarting with a reduced resolver. An already-running broker is refreshed without rewriting\nits config.\n\nA broker-only host is a first-class `up` mode. `cotal up --no-manager` boots the broker and, in\nauth mode, the delivery daemon, and no local manager, so the broker host never has a manager to\nstop and never leaves a manager slot stale. A refresh under the flag of a mesh whose manager is\nlive refuses rather than keeping or stopping it: `cotal down manager` first. Without the flag,\nauth-mode `up` still starts nats, the delivery daemon, and a\nlocal manager. A space may run more than one manager, addressed by instance id\n([control surface](control-surface.md#instance-routing)); putting no manager on the broker host\nis a topology choice, not a singleton invariant. A manager whose boot inventory has no\navailable connector does not take unpinned `spawn`/`launch` on the class rail, so a sibling\nthat can launch the harness can. `describe` still rides the class rail, so an unpinned spawn\ncan bind-fence when that skip member answered describe; re-issue, or pin `--on`. Pin one\ninstance with `--on` when a partial inventory still answers with a harness refusal. The\nsupported split is:\n\n```bash\n# broker host (project root that owns the generated conf, pidfiles, and logs)\ncotal up --detach --host 0.0.0.0 --space main --no-manager\n# no local manager starts: the summary lists nats-server + delivery daemon, and there is no\n# `.cotal/manager.<spaceKey>.log` to wait for on this host\n\n# manager host (registered remote mesh, same space)\ncotal meshes add --server nats://broker.example:4222 --root ~/meshes/main\ncotal supervise --space main --server nats://broker.example:4222\n```\n\nWait for `\u2713 manager up` in `.cotal/manager.<spaceKey>.log` on the manager host before spawning\nagents. On a broker host started without `--no-manager`, `cotal up --detach` prints `\u2713 running in\nthe background:` with `manager` listed once the manager pidfile is live; stop that local manager\nonly after the `\u2713 manager up` line. A host started WITH `--no-manager` never runs one, so neither\nthe wait nor the stop applies there. That detach stdout is not a safe teardown boundary: it is\npidfile liveness, not `\u2713 manager up`. `\u2713 manager up` is supervise's post-start line after\n`await mgr.start()`. `cotal down manager` after only the detach line can still default-terminate\nthe child during registration after it has taken the governance slot. Stopping before that\npost-start log line can leave the endpoint governance slot held until the holder's gate\nreopens past the stamp (the successor's boot heal, or\n[`cotal reconcile-gate`](cli.md#reconcile-gate) when that boot cannot run). See\n[Gate recovery](#gate-recovery).\n\nStandalone `cotal deliver --creds` is not a repair for that split. Production renewal needs\nthe manager and the daemon to address one credential store. The manager renews its own service\ncredential inside that credential's own window and re-dials its service connection with the\nrenewed credential; if the connection closes and cannot be restored within about forty seconds\nit releases its lease and exits so a restart can serve, while a broker that is briefly gone is\nwaited out. Separate host filesystems still\nleave manager root A writing and the daemon reloading root B; that composition is refused\nwhile the daemon stays up. Before every remint the manager challenges the delivery daemon's\nstore identity, and the answer must come from the process holding the delivery lease: the\nreply names the answering endpoint and the manager reads the lease row itself under its own\ncredential, so a non-holder answering on the queue-grouped admin rail is refused instead of\ncounting as the daemon's store. A rail that reports no responder is also settled from the\nlease row, so a live holder on record makes that outcome a refusal rather than an absent\ndaemon. Keep delivery on the broker host under `up`, and share one store\nonly when you are composing a hosted pair ([embedding](embedding.md#supervisor-signing-authority)).\nOn the `--no-manager` split above, the manager host's manager stays off the daemon-credential\nrenewal lease once its store check finds the daemon on another root. `cotal doctor auth --fix` on\nthe broker host then renews the daemon credentials once they pass their renewal point.\n\n### Split host bind\n\nA remote manager cannot reach a loopback broker. After changing `--host`, confirm the\ngenerated `host:` in `.cotal/auth/server.conf` and that nats is listening on that address\nbefore registering the mesh on the manager host. Detached child logs stay under the **project**\n`.cotal/` that `up` ran in (see [When something looks absent](#when-something-looks-absent));\nthey are not `~/.cotal` unless that directory is the mesh root.\n\nA user-auth mesh can expose only its credential exchange through an operator-owned HTTPS reverse\nproxy while leaving the existing local exchange untouched:\n\n```bash\ncotal up --user-auth --idp https://idp.example/api/auth \\\n  --exchange-public-port 7443 \\\n  --exchange-public-url https://auth.example\n```\n\nThe public listener itself still binds `127.0.0.1:7443`; configure the proxy to terminate TLS and\nforward to it. It serves only `/health`, `/jwks`, `/exchange`, and `/.well-known/cotal-mesh` with\nthe documented methods. It needs no local file capability: the signed IdP JWT or managed-agent\nactor token is the proof, while the original loopback listener remains capability-gated. Add\n`--exchange-trusted-proxy` only when that listener is reachable exclusively through your trusted\nproxy; it keys failure throttling by the last `X-Forwarded-For` hop instead of the socket address.\nThe well-known bundle includes IdP pins and a deny-all sentinel credential, so fetch it only from\nthe configured HTTPS origin. To change these listener flags, stop and restart the mesh; a refresh\nof an already-running service does not replace its bind or proxy policy. See\n[Identity & auth](identity-and-auth.md#per-user-authentication) for the trust boundary.\n\n### Remote supervised seats by enrollment\n\nA remote seat does not need to run `cotal login` when the mesh owner pre-mints a single-use\nenrollment for it. Mount the enrollment URL as a private file, place the seat persona on the remote\nmachine, and launch the foreground seat:\n\n```bash\nCOTAL_ENROLLMENT_FILE=/run/secrets/cotal-enrollment \\\n  cotal spawn --config ./worker.md --space main\n```\n\nThe URL is redeemed once with an unauthenticated GET. Redirects, off-machine plain HTTP, retries,\nand login fallback are refused. If the seat has no mesh record yet, the enrollment response's stock\nuser-bundle fields register it before the launch. The returned actor token then uses the same remote\nauth-service exchange as a login-provisioned agent. The enrollment URL and file path do not enter the\npreflight or harness environment. A failed or reused enrollment leaves no actor material on disk; ask the owner\nfor a fresh enrollment. When the foreground seat exits, this machine's credential files are removed\nand the mesh-side grant stays until the mesh operator revokes it; the launch line says so. The exact\nserver contract is in\n[Enrollment redeem](identity-and-auth.md#enrollment-redeem).\n\n`cotal status` prints the detailed setup, process, registry, and live mesh status. Its Machine\nsection names the running CLI's source checkout, installed package root, or npx package root beside\nthe version. It has one row per installed connector, which reports whether the executables that\nconnector declares in `requires` are on PATH. A connector whose setup provider reports health adds its\nown rows above those. The Claude Code connector reports its plugin and its skills plugin, and a stale\nskills row names the installed and CLI versions it compared. `cotal\nsetup` (after the first run) prints the compact card.\n\nBefore reporting ready, the manager resolves every installed connector's declared harness\nbinaries against its own environment. A missing binary does not stop unrelated manager work: boot\ncontinues, but prints a named `connector <name> unavailable` line and records that reason in the\nmanager's `status` response. Available connector rows record the absolute paths boot resolved.\nSpawn keeps the same pre-mint check as a backstop for connectors registered after boot.\n\nOn an authenticated manager start, unfinished static lifecycle rows reconcile while the control\nendpoint is already serving. The manager `status` response reports\nthe `staticReconciliation` state, the last sweep counts, and each failed alias with its durable\nphase and literal disposition. `cotal status --components` reports the state and per-alias failure\ndetails. A failed exact terminal is retried in the same process after 1, 5,\nand 30 seconds. Each attempt re-reads the durable slot and re-enters the same deterministic terminal\noperation; the delays only schedule work and never release the lifecycle fence.\n\nOn shutdown, the manager fences new reconciliation work and waits for an exact terminal that already\nstarted. The current serial sweep stops before its next alias, and startup cannot publish the manager\nservice after `stop()` completes.\n\nThe four-attempt budget is per manager process. An exhausted row stays held and reports\n`retry-exhausted` with the remedy to restart the manager. The next process derives a fresh budget\nfrom the still-authoritative durable row. A `recovered` row remains visible until the next static\nreconciliation sweep, then clears. This component reports reconciliation outcomes. It does not say\nwhether footprint cleanup completed independently of the terminal result; that separate durable\nprojection remains tracked by #1274.\n\n`cotal service install` is the supported way to run the manager as a user service\n([CLI reference](cli.md#service)): a systemd user unit on Linux, a launchd agent on macOS, one\nper mesh, surviving logout and reboot. On Linux that needs user lingering: install refuses while\nit is off and prints the root command that enables it. It installs only\nthe manager; the units below remain the process models for every other component, and they are\nstill **examples of process models** for those: copy them only after you decide which processes\nthe unit should own.\n\n### Supervising the detached stack\n\n`cotal up --detach` is a launcher: it starts the broker, delivery daemon, and manager, reports what\nstarted, then exits. Do not wrap it in a systemd service with `Type=oneshot` and\n`RemainAfterExit=yes` and treat `systemctl is-active` as stack health. That unit becomes `active\n(exited)` when the launcher exits successfully and stays active even if every detached process dies.\nWhen `up --detach` can identify that exact unit shape, it prints a warning but keeps the requested\nstartup behavior.\n\nFor a single-host stack, keep `cotal up` itself in the foreground so systemd tracks a long-running\nprocess and restarts the stack if that process fails:\n\n```ini\n[Service]\nType=simple\nWorkingDirectory=/srv/cotal-mesh\nExecStart=/usr/bin/cotal up --space main --host 0.0.0.0\nRestart=on-failure\nRestartSec=5s\n```\n\nAn active unit then proves the foreground launcher and broker are still running, but it still does\nnot prove that every child component serves. Pair it with the component check below. Also remember\nthat `cotal up` starts a local manager as well as the broker and delivery daemon; run\n`cotal up --no-manager` (add the flag to the unit's `ExecStart` too) on a host intended to be\nbroker-only, so the unit and the host agree.\n\nSeats spawned by the built-in `pty` runtime run with `oom_score_adj` 500, so under memory\npressure the kernel prefers a seat over the broker, manager and delivery daemon, which are left as\nthey were started; the extension runtimes do not own the seat's process and get no preference.\n\nThat `Type=simple` shape puts nats in the unit's cgroup with the foreground `up` process. A\n`Restart=always` (or `on-failure`) of **this** unit therefore restarts nats as well, so remote\nmanagers drop for the time it takes the broker to come back. Wrapping `cotal up --detach` in\n`Type=oneshot` with `RemainAfterExit=yes` does not move nats out of that cgroup. Detached\nspawn starts a new process group, not a new systemd cgroup, and the default\n`KillMode=control-group` still signals every process left in the service cgroup on stop or\nrestart, including the nats PID. Escaping that cgroup needs an explicit unit setting such as\n`KillMode=process`, or a separate nats unit; this CLI does not ship that escape. The\n`Type=oneshot` unit below is a `cotal status --components` liveness check, not a\n`--detach` launcher. Neither trade is universal from\n`Type=simple` alone; it follows from which processes the unit actually owns. `cotal service\ninstall` covers only the manager, so for the broker and its siblings pick the example that\nmatches the ownership you want, and treat\n`systemctl is-active` as unit health, not mesh health.\n\nA broker that crashes under that foreground `up` keeps its mesh record and exits non-zero, so the\nunit's restart takes the repair path against the recorded store rather than starting a second one.\n\nIf the deployment deliberately uses `cotal up --detach` as a boot action, monitor observed state\ninstead of the launcher's exit:\n\n```ini\n[Unit]\nDescription=Check Cotal component liveness\n\n[Service]\nType=oneshot\nWorkingDirectory=/srv/cotal-mesh\nExecStart=/usr/bin/cotal status --components --space main\n```\n\nRun that check from a systemd timer or another monitor and alert on a nonzero exit. The command\ndistinguishes `absent`, `not-serving`, and `refused` components and never treats a sibling's health as\nproof. Its delivery-process check is local to the broker host, so run it there. On a split topology,\nalso probe the broker URL from the manager host and monitor the manager's own service there. A remote\nmanager cannot observe the broker host's delivery PID, and an `active` unit on either host says\nnothing about the other host.\n\nStop one part without tearing down the mesh by naming its registered component: `cotal down\nmanager`, `cotal down delivery`, or `cotal down web`. Component names from installed extensions\njoin the same surface; `cotal down` with no names retains whole-stack behavior and\nleaves managed agents running as unmanaged OS processes, except pty seats, which stop with the\nmanager. `cotal down --with-agents` is the previous reap. If a pinned manager has no\nspare-capability record, stop its managed agents explicitly before running that whole-stack\ncommand. A current manager always publishes the record, so it is absent only for an older manager,\nwhich may not understand the reap request.\n\n## Remote supervised agents\n\nOn a remote user-auth mesh, foreground `cotal spawn` remains the default participant path. A\nparticipant can run detached agents only after the host advertises and operates the remote manager\nauthority service, and the participant's actor-ledger row includes `supervise`. This is not implied\nby `spawn` or `admin`.\n\nThe participant's loopback/operator exchange obtains one closed `manager-service` view for its\nordinary derived owner, a fixed server-selected manager actor, and one opaque manager instance.\nThe host, not the participant, issues the public-nkey JWT material via the replay-safe,\nlifecycle-bound prepare \u2192 activate \u2192 renew exchange, plus a one-shot target-pinned retirement\nrequest for a host-managed terminal. It never exports the space signer, a static\nprovisioner credential, or generic storage authority. Remote registration publishes its service\nstatus at the registered revision and current process epoch, so manager-caller selection can find it.\n\nStock participant supervision asks its host to enroll a detached agent and to prepare its terminal\nretirement, over the same manager-authority transport. The stock auth service refuses both requests\nas `unimplemented`, because it holds none of the storage they write: a host platform intercepts them\non its own route and asks the loopback verify-enrollment door for the decision. Successful remote\ndetached spawning therefore requires such a host composition; copying host secrets or actor-ledger\nfiles to a participant is not supported. Foreground spawning and operator-local hosted managers use\ntheir existing paths.\n\nThe remote manager that `cotal supervise` starts can host workflow runs through its host: the host\nadmits each run and signs only the run's own driver, mediator and operator credentials. A logged-in\nuser's `cotal run start` against it is admitted: the auth callout issues the user's manager\nconnection, and the host binds each run to the owner who registered the manager. The host's own\nmanager refuses user-auth runs by name.\n[User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path.\n\nThe registry entry decides the broker URL `supervise` dials, so a mesh published over `wss://` is\ndialed as a websocket. The manager-authority registration it runs first also takes its TLS\nrequirement from that entry, so the prepare credential is not exchanged over a plaintext\nconnection the record did not describe. `cotal meshes add` records both.\n\nWhen the authority service, login, or renewal is unavailable, the remote manager degrades\nfail-closed: it refuses new agents, restarts, and credential replacement rather than pretending\nlocal authority exists. Existing agents remain live only while their independent credentials are\nvalid. A hosted composition must revoke the managed grant and finish its resumable release before it\nrequests terminal retirement. Deleting DM or delivery consumers is not retirement and must not reset\na resumable lifecycle's frontier or pending state. The alias remains held until the terminal barrier\nconfirms. Restore service and renew successfully before asking it to recover an agent. See\n[Identity & auth](identity-and-auth.md#remote-manager-authority) and the [CLI\nreference](cli.md#supervise).\n\n## Spawning agents\n\n```bash\ncotal spawn                        # foreground: your default agent, in this terminal\ncotal spawn reviewer --detach      # supervised: the manager runs it in a PTY\ncotal attach --name reviewer       # watch/type into a detached agent (Ctrl-] detaches)\ncotal ps                           # what the manager is running\ncotal stop --name reviewer         # stop one\n```\n\nHow a spawn resolves:\n\n- **Persona.** A bare `cotal spawn` uses `.cotal/agents/default.md`; a positional name\n  picks `.cotal/agents/<name>.md`; `--config` takes an explicit ref or path. Set\n  `COTAL_DEFAULT_PERSONA=<name-or-path>` to change the fallback. Fields and format:\n  [agent files](agent-files.md).\n- **Harness.** Resolution order is an explicit `--agent` or `cotal_spawn` `agent` argument,\n  then the persona file's `agent:` pin, then the invoking caller's `COTAL_DEFAULT_AGENT`,\n  then the manager's `COTAL_DEFAULT_AGENT`, then the product default (Claude). Compared in\n  [Connectors](connectors.md); per-connector guides:\n  [Claude](connect-claude.md) \xB7 [OpenCode](connect-opencode.md) \xB7\n  [Hermes](connect-hermes.md) \xB7 [pi](connect-pi.md).\n- **Model.** `--model` overrides the persona file's `model:` (Claude: `opus` / `sonnet` or\n  a full id; OpenCode: `provider/model`). Connectors that expose a catalog report it via\n  `cotal models --agent opencode`: model ids plus available variants; pick one with\n  `--model provider/model --variant high`.\n- **Tools.** A spawned Claude Code agent gets the cotal tools plus the MCP servers the cotal\n  config shares, which first-run `cotal setup` fills with your own; narrow them per spawn with\n  `--share-tools` ([config](config.md)).\n- **Launch options.** `--opt key=value` (repeatable) passes a native harness flag straight\n  through; a persona or manifest `launchOptions:` mapping does the same declaratively (a\n  `--opt` wins per key). It is a **raw passthrough**, with no allow/deny list: Claude renders\n  each as `--key value` (a bare `--key` for an empty value), OpenCode merges them into its\n  agent config, and Hermes has no option surface so it fails loud. The trust boundary is the\n  `spawn` capability itself, not the flag set, so granting `spawn` is host-launch authority\n  ([security](security.md)). A key must be a plain flag name; malformed or prototype-polluting\n  keys are refused.\n\nDetach from an attached PTY with **Ctrl-]** (the agent keeps running); rebind it with\n`COTAL_DETACH_KEY=ctrl-<char>` when it clashes with a keybinding inside the agent's TUI.\n\n**Runtimes.** The manager spawns into a **pty** by default. It spawns the PTY in-process on\nevery platform, so replacing the manager worker closes its seats and the pty runtime gives no hot\nupdate. Any manager stop, bare `cotal down` included, stops and deprovisions those seats. A stopping\nmanager refuses new spawns and first waits for the ones it already accepted, so their seats stop too. On Linux\nit can still adopt and reap seats that an earlier manager launched under a detached per-seat\ncustodian, so those seats drain under the new manager; it starts no new custodian. A custodian whose agent has exited exits a few seconds later on its own. `cotal seats`\nlists the custodians left on the machine, and `cotal seats --drain` retires the ones whose agent\nhas exited while keeping every seat whose agent still runs ([cli.md](cli.md#seats)). When a pty\nagent exits on its own, in-process or under a custodian, the manager logs a `seat reaped:` line\nwith the exit code and, for a signalled child, the signal number. The line ends with the last line\nthe child printed that starts with a connector's `[cotal-<name>]` or `[cotal-<name>/<part>]`\nprefix, cut to 240 characters, when it printed one. A custodian keeps the same record beside the\nseat's custody record, so a later reap of that seat, including one by a\nsuccessor manager, reports how the child ended. When the custodian cannot write that record, it\nsays why in the seat's `custodian.log`, and a later reap of a child that ended on its own reports\nthe record as missing or unreadable. Optional runtimes are installed\nthrough the extension surface, for example `cotal ext add @cotal-ai/orca`, then selected with\n`--runtime orca` (similarly `@cotal-ai/tmux`, `@cotal-ai/cmux`, and `@cotal-ai/herdr`). They put teammates in native\nterminal surfaces rather than manager-owned PTYs. Runtime names are open-ended and resolved from\nthe registry; a missing provider or app throws, never silently falls back\n([architecture](architecture.md)).\n\n## Mesh registry\n\n`cotal up` records each running mesh in a machine-local registry\n(`~/.cotal/meshes/space.<key>.json`, named by a case-safe hex encoding of the space: broker URL, the project root holding its creds and\npersonas, and its mode). So a bare `cotal spawn <persona>` from *any* directory joins the\nrunning mesh with the right credentials instead of mistaking the cwd for a space:\n\n- `cotal use <name>` sets the default from every directory, including inside another mesh's\n  project. `--space <name>` overrides it for one command.\n- When one broker has records for several spaces, `cotal up --space <name>` refreshes that named\n  space.\n- A refresh rewrites only what that command decided: the server, root and mode, the user-auth\n  endpoints, and an explicit `--host` or `--max-sessions`. Every other field, such as the TLS\n  requirement, is kept as the record stands when the refresh writes it, so a change another\n  command made during the refresh survives. If the record was removed during the refresh, `up`\n  fails instead of writing it back.\n- With no live selected default, a project with its own `.cotal/` resolves to that project's\n  mesh; otherwise one running mesh is used automatically and several are an error.\n- `cotal meshes` lists them (a `*` marks the default); `cotal down` removes the entry.\n\nThe registry stores a *path*, never a secret; trust material stays in each project's\n`.cotal/auth`. If the mesh is down or won't take your creds, spawn fails with one\nsentence, never a raw NATS trace.\n\n### Meshes you did not start here\n\nA mesh running on another machine has no `cotal up` on this one, so register it by hand:\n\n```bash\ncotal meshes add            # guided: asks for the broker, probes it, offers what it finds\ncotal meshes add optiplex --server nats://100.90.12.34:4222 --root ~/meshes/optiplex \\\n  --allow-unencrypted-overlay      # see below: an overlay address needs this\ncotal meshes rm optiplex\n```\n\nOn a terminal, a bare `cotal meshes add` walks you through it: it probes the broker you name and\nreports whether it is open or requires credentials, offers the spaces the folder already holds\ncredentials for, and shows the record before writing it. Scripts and agents keep the flag form -\nwithout a terminal nothing prompts.\n\n`--root` is the local folder holding that mesh's `.cotal/auth` and `.cotal/agents` (its personas);\nthe mode is inferred from what that folder holds.\n\n**Know what you are copying.** For an authenticated mesh that folder carries the space's account\n**signing seed**, which is the authority to mint any identity in the space. A machine holding it\nis a certificate authority for the mesh rather than a client of it: anyone who reads it can\nimpersonate any agent, read every retained channel and DM, change ACLs, and keep issuing\nthemselves credentials. There is no per-machine revocation; undoing it means rotating the signing\nkey and re-minting every credential in the space. Copy it only to machines you would trust with\nthe whole mesh. `cotal mint` on its own does not substitute here: registering an `auth` mesh needs\nsigning material that composes, which a minted user credential is not. The\nbroker is probed before the record is written, so a bad address or a credential that mesh will not\naccept fails at registration rather than at your first `spawn` (`--force` records it without verifying,\nuseful when the mesh is simply down right now).\n\n#### Which addresses you may register\n\nRegistering a mesh is how this machine starts sending agent credentials to a broker it does not\nrun. NATS announces itself in plaintext before anyone authenticates, so an attacker on the path\ncan pose as the broker and read the credential out of the connect unless the connection\n**requires TLS**, which is recorded on the entry and enforced on every dial through it.\n\nWhat the record will require decides what you may register:\n\n- **Without required TLS**, the address is the gate: **loopback** (`127.0.0.0/8`, `::1`), or\n  **your private overlay** (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) with\n  `--allow-unencrypted-overlay`. The tunnel provides the protection, and this command cannot check\n  its state. Hostnames are refused because the lookup would choose which machine receives your\n  credentials.\n- **With required TLS**, set `--tls` or use a `tls://` URL. The recorded scheme enforces the TLS\n  requirement. A **hostname or public address** is accepted because the certificate chain and\n  hostname check identify the peer. A registration whose broker cannot complete the handshake\n  fails unless you pass `--force`, which records the entry without verification.\n\nOrdinary private ranges like `10.x` and `192.168.x` are refused in **both** modes. A caf\xE9's wifi\nis private but does not belong to you, and no public CA issues certificates for those ranges. An\naddress spelling changes nothing: `[::ffff:192.168.1.10]`, `3232235786`, `0300.0250.01.012`, and\n`192.168.257` all resolve to private addresses and receive the same refusal as the dotted form.\n`--force` exists for a mesh that is down. It never permits an unsafe credential destination.\n\n#### Registering a hosted user-auth mesh\n\nA user-auth space's IdP pins are established where the mesh runs and are never guessed. Register\none from **supplied** trust: `--user-auth-file bundle.json` (exported on the mesh's machine), or\n`--from https://\u2026/.well-known/cotal-mesh`, which asks before it contacts the address at all,\nfetches the discovery document over HTTPS, shows you the pins, and asks again before adopting\nthem. Redirects are refused because a 302 can walk a pinned fetch down to\nplaintext or onto another host, and the pinned exchange must be an `https://` URL too. The one\nexception is an exchange on **this machine**, where nothing leaves the box: plain `http://` is\naccepted for a loopback *literal* (`127.0.0.1`, `::1`, and any spelling of them), but **not** for\n`localhost`, which a hosts entry or poisoned lookup could point elsewhere. Use the\nliteral. Registration checks that the pinned exchange\nanswers `/health` and `/jwks` as the pinned issuer. It also checks that the broker refuses a\nbare connect; that refusal is the pass. The bundle's sentinel credentials are written to a private (0600) file\nunder the entry's root; the registry itself never carries the secret.\n\n**Without required TLS**, an overlay address is **refused unless you accept the dependency\nexplicitly**, with `--allow-unencrypted-overlay`. The address is not the guarantee: it is protected\nwhile the tunnel is up, and if the tunnel is down that range is ordinary carrier-grade NAT and\nwhoever answers the dial receives your credentials. Only you can know which it is, so the command\nasks you to say so. Your acceptance is recorded on the mesh entry rather than printed and\nforgotten, and the guided form asks the same question instead of taking the flag.\n\n**With required TLS** (`--tls`, or a `tls://` URL) that consent is no longer asked for, and the\nflag is not needed: the handshake is what protects the connection, so the acceptance it stood in\nfor has been replaced by proof rather than promise. `cotal meshes add <space> --server\nnats://100.64.0.1 --tls` registers an overlay address with no prompt, no flag and no recorded\nacceptance. This is the \"the flag disappears once the broker can be served over TLS\" case, and it\nhas now arrived.\n\nThis gate is on **registration**. `cotal join --creds --server <url>` deliberately takes an\nexplicit connection at face value and does not consult the registry, so it is not covered. Join\nthat way only to an address you would have registered.\n\nThe connection is still probed first, with the same second try at the longer budget the registry\npreflight uses, so a slow link reads as a connect that did not finish within that budget and a\nrefused port reads as a broker that is not running.\n\nRecords added this way are removed only by something that names them. A failed liveness probe\ndoes not delete any record: an unreachable broker, local or registered by hand, is shown as\n`offline` in `cotal meshes`. A bare command does not count that offline record as running;\nname it with `--space` to restart it. `cotal down` / `cotal clean all` still drop an `up` record for the\nproject they are tearing down, and they leave a hand-registered one alone even when `--root`\npointed at that project. A `cotal up` for that space refuses outright unless it is that same\nendpoint: finding a broker already answering there is a refresh that starts nothing and leaves the\nrecord's provenance alone, while actually starting the broker for that space, server and root\nmakes this machine the one running it, so the record becomes an ordinary local one that\n`cotal down` clears. The refusal names `cotal supervise --space <s> --server <url>` (plus `cotal\ndeliver`) when the registered broker is on another host, and `cotal meshes rm` when it is local.\n`cotal meshes rm` drops it and re-registering with `--force` replaces it. `rm` only forgets a\nmesh. To stop one running here, use `cotal down`.\n\n## Watching\n\n`cotal console` is the terminal view (TUI on a real terminal, plain line stream when\npiped); `cotal web` is the browser dashboard. Both are read-only observers; the\nwalkthrough is [Watch a mesh](watch-a-mesh.md).\n\n## History\n\nRetained history is operator-owned. `cotal clean history --force` purges a space's\nretained channel history; `--dms` also purges DMs (`cotal history clear` is an alias).\nIt is deliberately **not** an agent tool: agents cannot wipe the record\n([identity & auth](identity-and-auth.md)). For a **stopped** mesh, `cotal clean store\n--force` deletes the on-disk JetStream store outright, and `cotal clean all --force`\nalso resets the space identity ([CLI reference](cli.md#clean)).\n\n## Offline backup\n\nFor a coherent durable cut, preserve the whole stack first, then create the artifact while it stays\ndown:\n\n```bash\ncotal down --preserve-state\ncotal backup create ./space-backup        # full by default\n# later: deliberately resume the unchanged source\ncotal up --detach\n# or, from another preserved cut, restore before the normal listener opens\ncotal up --restore ./space-backup --detach\n```\n\nA refused cut leaves the mesh running and unfenced: fix what the refusal names and run\n`cotal down --preserve-state` again.\n\nUse `--store-dir` on both preservation and backup for a custom JetStream store. A store cap set\nwith `cotal up --max-file-store <bytes>` travels with the preserved state, and the resume renders it\nagain. nats-server reads the cap once at start and refuses a config reload that changes it, so a new\ncap always needs a restart. The cut records the chat stream's frontier per retained seat, so a\nresumed seat catches up from there instead of replaying its channels. `registry` is the\nonly partial selection (`backup create ... --only registry`; `up --restore ... --restore-only\nregistry`). Backup never stops or restarts a mesh implicitly, never opens the original store, and\ndoes not contain credentials or trust secrets. Backup/restore in every auth mode, open included,\nuses isolated, operation-specific maintenance logins; normal agent credentials cannot enter that\nlistener. Full\nrestore requires the same space and exact current local trust continuity, recreates conservative\nconsumer checkpoints bound to their snapshot stream sequence state, and resumes retained agents under\ntheir original principals. The trust commitment includes the cryptographically validated full\noperator/system/data-account root chain as well as static/user authority state. A registry-only\nrestore completes canonical empty infrastructure but leaves retained agents stopped because their\nDM/DLV/TASK/ACL state is outside that selection. Authenticated restore validates the complete space\ntrust bundle before staging or changing the preserved store. Interrupted ordinary resume retries the\nsame durable attempt after its prior listener is stopped. Restore re-entry can recover a surviving normal listener\nonly when its attempt nonce, NATS server name, process owner, endpoint, and target-store identity all\nmatch the fsynced proof. A provably dead uncommitted owner is retired under lock and replaced with a\nfresh attempt-bound listener; an occupied foreign listener or ambiguous owner is never adopted. The\nmanager commit validates while retained cleanup is still suppressed; the CLI durably records its\nattempt-bound 64-hex token in `manager-committed` / `resume-committed` before `finalizeResume` can\nrelease suppression. A retry from either committed state goes straight to exact-token finalization;\nfailure preserves the committed gate and retained cleanup suppression. Missing commit evidence,\ninterrupted finalization, a live recorded endpoint despite missing pidfiles, or ambiguous proof fails closed. See the [CLI\nbackup and restore contract](cli.md#backups) for artifact, checkpoint, fallback,\ndisaster-consent, and degraded-recovery details.\n\n## Personas from the CLI\n\n`cotal personas` manages the local catalog offline: `list` (`--running` overlays live\nmarkers), `show <name>`, `edit <name>` (re-validates on save), `new <name>`, `rm <name>\n--force`. The runtime write is `cotal_persona`; the runtime read is `cotal_personas`\n(list / show), both over the wire with the manager's ownership checks. Fields: [agent files](agent-files.md).\n\n## Gate recovery\n\nA manager that dies mid-registration leaves its issuance gate *frozen* under that registration\nop. The freeze is correct: it stops two incarnations serving at once. The successor now completes\nthat dead op on boot, using the same guard as [`cotal reconcile-gate`](cli.md#reconcile-gate): it\nacts only when the freeze-holder is affirmatively gone under a complete CONNZ sweep (`gone` and\n`sweepComplete=true`). If the dead op's spec write committed, it finishes that same freeze\n(promote and reopen at the committed registration revision). If the spec did not advance, it\nabort-reopens the gate (generation+1, processEpoch unchanged) and continues the normal takeover.\nBoot heal and the following re-registration use separate one-shot executor windows, so a large\npredecessor family cannot spend the takeover's credential lifetime. If that later registration\nstill crosses a connection lifetime, it retries the same frozen operation with fresh authority\nand resumes verified-holder progress instead of freezing a new generation.\nA live holder, an incomplete sweep, or an unreachable delivery daemon still\nrefuses. Silence is never evidence of death, and there is no TTL. If holder verification is\ninterrupted, the frozen operation resumes from its durable, operation-and-gate-revision-bound\nprogress after liveness is checked again. A later freeze cannot reuse that progress: the cursor\nbinds the exact op, gate revision, and holder set. Use `cotal reconcile-gate` when the boot path cannot run\n(daemon down, a non-manager endpoint, or you want to lift the freeze without starting a manager). A spawn that hits the same frozen gate names that verb in the refusal\n(`blockedOp=registration`, the holding `opId`, `remedy=cotal reconcile-gate`) instead of a\nwait-timeout: the facts were always in the manager log; they now reach the spawn caller too.\n\nGive reconciliation a **quiet manager**. Suspend systemd restart policies, watchdogs, health-check\nrestart loops, and any other automation that can start or kill `cotal supervise` while boot healing or\n`cotal reconcile-gate` is running. Leave one recovery attempt in control until it finishes.\nRestarting the manager during the walk interrupts the current authority window. Durable progress makes\nthat interruption resumable, but a quiet manager is still the fastest and safest incident procedure.\n\n### Last-resort JetStream store replacement\n\nStore replacement is not normal gate recovery, is never automatic, and is destructive to mesh history.\nUse it only after the retained store cannot be reconciled and after deciding that losing its durable\ncontents is acceptable.\n\n1. Stop every actor touching the space: supervisor, watchdog, manager, delivery daemon, and broker.\n   Confirm that no Cotal or NATS process still has the store open.\n2. Preserve the stopped store before changing anything. Move `.cotal/nats` aside to a dated backup and\n   archive both `nats` and `auth`. Do not delete the only copy.\n3. Understand the loss: replacing the store removes JetStream message and control history and durable\n   consumer state. Agent session files stored outside JetStream remain, but the mesh history they\n   referenced does not.\n4. Start the broker against a new empty store, then start one manager. Wait until it reports\n   serving successfully.\n5. Repopulate the mesh only after that manager is healthy. Re-enable supervisors, watchdogs, and other\n   restart automation last.\n\nKeep the preserved store until the incident is reviewed and any required forensic or manual recovery is\ncomplete. Restoring it later restores the old durable state, including the fault that led to this last\nresort, so do not swap it back into a live mesh casually.\n\n## When something looks absent\n\nPermission denials are **loud, never silent**: an over-tight ACL rejects the endpoint call and\nalso shows up as a logged denial, instead of returning an empty or incomplete result that looks\nsuccessful. Check\n`.cotal/manager.<key>.log`, `.cotal/delivery.<key>.log` (one pair per space, keyed as\n[Config](config.md#project-files) describes), and `.cotal/nats.log`; `cotal status` shows\nwhat is actually running. Those files live under the **project** `.cotal/`, not `~/.cotal`,\nunless the mesh root is the home directory. `cotal up --detach` redirects delivery and manager\nstdio onto those files, so an operator-created systemd unit around that launcher does not put\nthe child logs in that unit's journal. `journalctl -u <unit>` can be empty while the crash\nreason is already in the project log. Manager log lines start with the UTC time they were\nwritten. The access rules are collected in\n[Channels & permissions](channels-and-permissions.md).\n"
+      "body": "# Run a mesh\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nDay-to-day operation of a local mesh: what `cotal up` actually runs, how spawning\nresolves personas, harnesses, and models, how to reach a mesh from any directory, and the\noperator-only maintenance verbs. Every command's full flag set is in the\n[CLI reference](cli.md).\n\n## The stack\n\n`cotal up` brings up the whole local stack and bare `cotal down` stops it. Managed\nagents stay running as unmanaged OS processes; pass `--with-agents` to take them\nwith the stack. Seats of the built-in pty runtime run inside the manager process, so\nthey stop with the manager either way. Ctrl-C on a foreground `up` follows the same sparing rule\nand prints the same report as bare down; when the manager cannot prove it can spare,\nCtrl-C refuses the teardown and leaves the stack running, and you end it with\n`cotal down --with-agents`. A current manager records what its stop does with its seats before\nbare down signals it. A pre-pin legacy manager instead receives a reduced-guarantee\nwarning and is signalled according to the documented upgrade contract. Its running binary\nmay still carry the older destructive SIGTERM handler, so the CLI does not claim its\npre-signal agent inventory was spared; those agents may have been reaped.\n\n- **Broker**: a local `nats-server` (logs to `.cotal/nats.log`).\n- **Delivery daemon**: the durable backstop, auth mode only\n  ([what it does](delivery-daemon.md)).\n- **Manager**: a detached supervisor answering the control plane, so\n  `cotal spawn --detach` and the `cotal_spawn` tool work right after `up`.\n\nCotal creates the presence bucket in memory storage. Its records are liveness that every endpoint\nrewrites each heartbeat, so nothing is lost when a broker restart empties it, and nats-server's file\nstore write latch cannot reach it. A broker stop removes the memory stream itself, so every `cotal up`,\nincluding the resume after `cotal down --preserve-state`, creates it again before any daemon starts.\nJetStream fixes a stream's storage class when it is created, so a presence bucket created file-backed\nby an older cotal stays file-backed until that stream is recreated.\n\nA file-backed presence bucket can remain open and watchable while refusing every write. A bound\nendpoint reports this as `presence-write-stuck` after one full presence TTL of consecutive failures.\nThe roster is last-known while that condition is active. Restarting the broker clears nats-server's\nin-memory store latch and preserves the JetStream root. Current credentials split the required stream\nauthority: the `cotal up` provisioner can create the presence stream but cannot delete it, while the\nteardown credential can delete it but cannot recreate it. Cotal therefore reports the condition but\ndoes not attempt an unsafe partial delete-and-recreate. Stop and restart the broker to recover.\nA broker below nats-server 2.14.5 carries the latch (nats-server fixed it in 2.14.5). When `cotal up` starts or finds such a broker and the space's presence bucket is file-backed, it says so. A memory-backed bucket gets no warning. A broker below the SPEC \xA713.12 floor of 2.12 is refused at connect with the floor sentence.\n\nThree modes:\n\n- **Default (static auth).** JWT-authed, on by default: sender authenticity and per-agent\n  ACLs, enforced by the broker ([how](identity-and-auth.md)).\n- **`--user-auth --idp <url>`.** Per-user auth: people `cotal login` once, the operator\n  grants their agents on the actor ledger, and every connect is authorized live against\n  that grant. Starts the space's auth service alongside the broker\n  ([how](identity-and-auth.md)).\n- **`--open`.** An unauthenticated, live-only dev mesh (no auth, no delivery daemon). For\n  quick local experiments.\n\nThe broker and local services bind **loopback** by default. `--host 0.0.0.0` widens the broker\nbind independently of the auth mode, so \"network-reachable\" never silently means\n\"unauthenticated\". With no explicit `--server`, `cotal up` auto-selects a free local port when\nthe default address is already held by another project; an explicit `--server` fails loud on\ncollision.\n\n`--host` is a boot flag, not a live rebind. A fresh `cotal up` writes the generated\n`.cotal/auth/server.conf` (project-local, not `~/.cotal`) with that bind and starts nats against\nit. If anything is already answering at the mesh URL, `up` refreshes the recorded mesh and\nleaves the running nats listener alone, so passing `--host 0.0.0.0` on a live or orphaned\nbroker does not change who can connect. To change the bind: `cotal down`, then `cotal up --host\n<addr>` against a stopped broker so the generated file is rewritten. Do not edit `server.conf`\nby hand; the next real boot overwrites it.\n\nOn a stopped shared broker, `up` renders every persisted space account and every enabled\nspace's auth-callout account into the resolver preload, regardless of which space starts\nthe broker. A missing callout account for an enabled space stops the boot rather than\nstarting with a reduced resolver. An already-running broker is refreshed without rewriting\nits config.\n\nA broker-only host is a first-class `up` mode. `cotal up --no-manager` boots the broker and, in\nauth mode, the delivery daemon, and no local manager, so the broker host never has a manager to\nstop and never leaves a manager slot stale. A refresh under the flag of a mesh whose manager is\nlive refuses rather than keeping or stopping it: `cotal down manager` first. Without the flag,\nauth-mode `up` still starts nats, the delivery daemon, and a\nlocal manager. A space may run more than one manager, addressed by instance id\n([control surface](control-surface.md#instance-routing)); putting no manager on the broker host\nis a topology choice, not a singleton invariant. A manager whose boot inventory has no\navailable connector does not take unpinned `spawn`/`launch` on the class rail, so a sibling\nthat can launch the harness can. `describe` still rides the class rail, so an unpinned spawn\ncan bind-fence when that skip member answered describe; re-issue, or pin `--on`. Pin one\ninstance with `--on` when a partial inventory still answers with a harness refusal. The\nsupported split is:\n\n```bash\n# broker host (project root that owns the generated conf, pidfiles, and logs)\ncotal up --detach --host 0.0.0.0 --space main --no-manager\n# no local manager starts: the summary lists nats-server + delivery daemon, and there is no\n# `.cotal/manager.<spaceKey>.log` to wait for on this host\n\n# manager host (registered remote mesh, same space)\ncotal meshes add --server nats://broker.example:4222 --root ~/meshes/main\ncotal supervise --space main --server nats://broker.example:4222\n```\n\nWait for `\u2713 manager up` in `.cotal/manager.<spaceKey>.log` on the manager host before spawning\nagents. On a broker host started without `--no-manager`, `cotal up --detach` prints `\u2713 running in\nthe background:` with `manager` listed once the manager pidfile is live; stop that local manager\nonly after the `\u2713 manager up` line. A host started WITH `--no-manager` never runs one, so neither\nthe wait nor the stop applies there. That detach stdout is not a safe teardown boundary: it is\npidfile liveness, not `\u2713 manager up`. `\u2713 manager up` is supervise's post-start line after\n`await mgr.start()`. `cotal down manager` after only the detach line can still default-terminate\nthe child during registration after it has taken the governance slot. Stopping before that\npost-start log line can leave the endpoint governance slot held until the holder's gate\nreopens past the stamp (the successor's boot heal, or\n[`cotal reconcile-gate`](cli.md#reconcile-gate) when that boot cannot run). See\n[Gate recovery](#gate-recovery).\n\nStandalone `cotal deliver --creds` is not a repair for that split. Production renewal needs\nthe manager and the daemon to address one credential store. The manager renews its own service\ncredential inside that credential's own window and re-dials its service connection with the\nrenewed credential; if the connection closes and cannot be restored within about forty seconds\nit releases its lease and exits so a restart can serve, while a broker that is briefly gone is\nwaited out. Separate host filesystems still\nleave manager root A writing and the daemon reloading root B; that composition is refused\nwhile the daemon stays up. Before every remint the manager challenges the delivery daemon's\nstore identity, and the answer must come from the process holding the delivery lease: the\nreply names the answering endpoint and the manager reads the lease row itself under its own\ncredential, so a non-holder answering on the queue-grouped admin rail is refused instead of\ncounting as the daemon's store. A rail that reports no responder is also settled from the\nlease row, so a live holder on record makes that outcome a refusal rather than an absent\ndaemon. Keep delivery on the broker host under `up`, and share one store\nonly when you are composing a hosted pair ([embedding](embedding.md#supervisor-signing-authority)).\nOn the `--no-manager` split above, the manager host's manager stays off the daemon-credential\nrenewal lease once its store check finds the daemon on another root. `cotal doctor auth --fix` on\nthe broker host then renews the daemon credentials once they pass their renewal point.\n\n### Split host bind\n\nA remote manager cannot reach a loopback broker. After changing `--host`, confirm the\ngenerated `host:` in `.cotal/auth/server.conf` and that nats is listening on that address\nbefore registering the mesh on the manager host. Detached child logs stay under the **project**\n`.cotal/` that `up` ran in (see [When something looks absent](#when-something-looks-absent));\nthey are not `~/.cotal` unless that directory is the mesh root.\n\nA user-auth mesh can expose only its credential exchange through an operator-owned HTTPS reverse\nproxy while leaving the existing local exchange untouched:\n\n```bash\ncotal up --user-auth --idp https://idp.example/api/auth \\\n  --exchange-public-port 7443 \\\n  --exchange-public-url https://auth.example\n```\n\nThe public listener itself still binds `127.0.0.1:7443`; configure the proxy to terminate TLS and\nforward to it. It serves only `/health`, `/jwks`, `/exchange`, and `/.well-known/cotal-mesh` with\nthe documented methods. It needs no local file capability: the signed IdP JWT or managed-agent\nactor token is the proof, while the original loopback listener remains capability-gated. Add\n`--exchange-trusted-proxy` only when that listener is reachable exclusively through your trusted\nproxy; it keys failure throttling by the last `X-Forwarded-For` hop instead of the socket address.\nThe well-known bundle includes IdP pins and a deny-all sentinel credential, so fetch it only from\nthe configured HTTPS origin. To change these listener flags, stop and restart the mesh; a refresh\nof an already-running service does not replace its bind or proxy policy. See\n[Identity & auth](identity-and-auth.md#per-user-authentication) for the trust boundary.\n\n### Remote supervised seats by enrollment\n\nA remote seat does not need to run `cotal login` when the mesh owner pre-mints a single-use\nenrollment for it. Mount the enrollment URL as a private file, place the seat persona on the remote\nmachine, and launch the foreground seat:\n\n```bash\nCOTAL_ENROLLMENT_FILE=/run/secrets/cotal-enrollment \\\n  cotal spawn --config ./worker.md --space main\n```\n\nThe URL is redeemed once with an unauthenticated GET. Redirects, off-machine plain HTTP, retries,\nand login fallback are refused. If the seat has no mesh record yet, the enrollment response's stock\nuser-bundle fields register it before the launch. The returned actor token then uses the same remote\nauth-service exchange as a login-provisioned agent. The enrollment URL and file path do not enter the\npreflight or harness environment. A failed or reused enrollment leaves no actor material on disk; ask the owner\nfor a fresh enrollment. When the foreground seat exits, this machine's credential files are removed\nand the mesh-side grant stays until the mesh operator revokes it; the launch line says so. The exact\nserver contract is in\n[Enrollment redeem](identity-and-auth.md#enrollment-redeem).\n\n`cotal status` prints the detailed setup, process, registry, and live mesh status. Its Machine\nsection names the running CLI's source checkout, installed package root, or npx package root beside\nthe version. It has one row per installed connector, which reports whether the executables that\nconnector declares in `requires` are on PATH. A connector whose setup provider reports health adds its\nown rows above those. The Claude Code connector reports its plugin and its skills plugin, and a stale\nskills row names the installed and CLI versions it compared. `cotal\nsetup` (after the first run) prints the compact card.\n\nBefore reporting ready, the manager resolves every installed connector's declared harness\nbinaries against its own environment. A missing binary does not stop unrelated manager work: boot\ncontinues, but prints a named `connector <name> unavailable` line and records that reason in the\nmanager's `status` response. Available connector rows record the absolute paths boot resolved.\nSpawn keeps the same pre-mint check as a backstop for connectors registered after boot.\n\nOn an authenticated manager start, unfinished static lifecycle rows reconcile while the control\nendpoint is already serving. The manager `status` response reports\nthe `staticReconciliation` state, the last sweep counts, and each failed alias with its durable\nphase and literal disposition. `cotal status --components` reports the state and per-alias failure\ndetails. A failed exact terminal is retried in the same process after 1, 5,\nand 30 seconds. Each attempt re-reads the durable slot and re-enters the same deterministic terminal\noperation; the delays only schedule work and never release the lifecycle fence.\n\nOn shutdown, the manager fences new reconciliation work and waits for an exact terminal that already\nstarted. The current serial sweep stops before its next alias, and startup cannot publish the manager\nservice after `stop()` completes.\n\nThe four-attempt budget is per manager process. An exhausted row stays held and reports\n`retry-exhausted` with the remedy to restart the manager. The next process derives a fresh budget\nfrom the still-authoritative durable row. A `recovered` row remains visible until the next static\nreconciliation sweep, then clears. This component reports reconciliation outcomes. It does not say\nwhether footprint cleanup completed independently of the terminal result; that separate durable\nprojection remains tracked by #1274.\n\n`cotal service install` is the supported way to run the manager as a user service\n([CLI reference](cli.md#service)): a systemd user unit on Linux, a launchd agent on macOS, one\nper mesh, surviving logout and reboot. On Linux that needs user lingering: install refuses while\nit is off and prints the root command that enables it. It installs only\nthe manager; the units below remain the process models for every other component, and they are\nstill **examples of process models** for those: copy them only after you decide which processes\nthe unit should own.\n\n### Supervising the detached stack\n\n`cotal up --detach` is a launcher: it starts the broker, delivery daemon, and manager, reports what\nstarted, then exits. Do not wrap it in a systemd service with `Type=oneshot` and\n`RemainAfterExit=yes` and treat `systemctl is-active` as stack health. That unit becomes `active\n(exited)` when the launcher exits successfully and stays active even if every detached process dies.\nWhen `up --detach` can identify that exact unit shape, it prints a warning but keeps the requested\nstartup behavior.\n\nFor a single-host stack, keep `cotal up` itself in the foreground so systemd tracks a long-running\nprocess and restarts the stack if that process fails:\n\n```ini\n[Service]\nType=simple\nWorkingDirectory=/srv/cotal-mesh\nExecStart=/usr/bin/cotal up --space main --host 0.0.0.0\nRestart=on-failure\nRestartSec=5s\n```\n\nAn active unit then proves the foreground launcher and broker are still running, but it still does\nnot prove that every child component serves. Pair it with the component check below. Also remember\nthat `cotal up` starts a local manager as well as the broker and delivery daemon; run\n`cotal up --no-manager` (add the flag to the unit's `ExecStart` too) on a host intended to be\nbroker-only, so the unit and the host agree.\n\nSeats spawned by the built-in `pty` runtime run with `oom_score_adj` 500, so under memory\npressure the kernel prefers a seat over the broker, manager and delivery daemon, which are left as\nthey were started; the extension runtimes do not own the seat's process and get no preference.\n\nThat `Type=simple` shape puts nats in the unit's cgroup with the foreground `up` process. A\n`Restart=always` (or `on-failure`) of **this** unit therefore restarts nats as well, so remote\nmanagers drop for the time it takes the broker to come back. Wrapping `cotal up --detach` in\n`Type=oneshot` with `RemainAfterExit=yes` does not move nats out of that cgroup. Detached\nspawn starts a new process group, not a new systemd cgroup, and the default\n`KillMode=control-group` still signals every process left in the service cgroup on stop or\nrestart, including the nats PID. Escaping that cgroup needs an explicit unit setting such as\n`KillMode=process`, or a separate nats unit; this CLI does not ship that escape. The\n`Type=oneshot` unit below is a `cotal status --components` liveness check, not a\n`--detach` launcher. Neither trade is universal from\n`Type=simple` alone; it follows from which processes the unit actually owns. `cotal service\ninstall` covers only the manager, so for the broker and its siblings pick the example that\nmatches the ownership you want, and treat\n`systemctl is-active` as unit health, not mesh health.\n\nA broker that crashes under that foreground `up` keeps its mesh record and exits non-zero, so the\nunit's restart takes the repair path against the recorded store rather than starting a second one.\n\nIf the deployment deliberately uses `cotal up --detach` as a boot action, monitor observed state\ninstead of the launcher's exit:\n\n```ini\n[Unit]\nDescription=Check Cotal component liveness\n\n[Service]\nType=oneshot\nWorkingDirectory=/srv/cotal-mesh\nExecStart=/usr/bin/cotal status --components --space main\n```\n\nRun that check from a systemd timer or another monitor and alert on a nonzero exit. The command\ndistinguishes `absent`, `not-serving`, and `refused` components and never treats a sibling's health as\nproof. Its delivery-process check is local to the broker host, so run it there. On a split topology,\nalso probe the broker URL from the manager host and monitor the manager's own service there. A remote\nmanager cannot observe the broker host's delivery PID, and an `active` unit on either host says\nnothing about the other host.\n\nStop one part without tearing down the mesh by naming its registered component: `cotal down\nmanager`, `cotal down delivery`, or `cotal down web`. Component names from installed extensions\njoin the same surface; `cotal down` with no names retains whole-stack behavior and\nleaves managed agents running as unmanaged OS processes, except pty seats, which stop with the\nmanager. `cotal down --with-agents` is the previous reap. If a pinned manager has no\nspare-capability record, stop its managed agents explicitly before running that whole-stack\ncommand. A current manager always publishes the record, so it is absent only for an older manager,\nwhich may not understand the reap request.\n\n## Remote supervised agents\n\nOn a remote user-auth mesh, foreground `cotal spawn` remains the default participant path. A\nparticipant can run detached agents only after the host advertises and operates the remote manager\nauthority service, and the participant's actor-ledger row includes `supervise`. This is not implied\nby `spawn` or `admin`.\n\nThe participant's loopback/operator exchange obtains one closed `manager-service` view for its\nordinary derived owner, a fixed server-selected manager actor, and one opaque manager instance.\nThe host, not the participant, issues the public-nkey JWT material via the replay-safe,\nlifecycle-bound prepare \u2192 activate \u2192 renew exchange, plus a one-shot target-pinned retirement\nrequest for a host-managed terminal. It never exports the space signer, a static\nprovisioner credential, or generic storage authority. Remote registration publishes its service\nstatus at the registered revision and current process epoch, so manager-caller selection can find it.\n\nStock participant supervision asks its host to enroll a detached agent and to prepare its terminal\nretirement, over the same manager-authority transport. The stock auth service answers both when it\nruns with a public exchange face: it grants the agent under the participant's owner at a lifecycle\nUID it picks, bounded by the participant actor's own grant, provisions that UID's durables, and on\nretirement releases them and revokes the grant before the manager's terminal rail. It refuses a\nsecond enrollment of a name whose grant still stands until that agent's retirement is prepared. A\nhost platform that keeps these writers in its own storage intercepts both requests on its own route\ninstead. Copying host secrets or actor-ledger files to a participant is not supported. Foreground\nspawning and operator-local hosted managers use their existing paths.\n\nThe remote manager that `cotal supervise` starts can host workflow runs through its host: the host\nadmits each run and signs only the run's own driver, mediator and operator credentials. A logged-in\nuser's `cotal run start` against it is admitted: the auth callout issues the user's manager\nconnection, and the host binds each run to the owner who registered the manager. The host's own\nmanager refuses user-auth runs by name.\n[User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path.\n\nThe registry entry decides the broker URL `supervise` dials, so a mesh published over `wss://` is\ndialed as a websocket. The manager-authority registration it runs first also takes its TLS\nrequirement from that entry, so the prepare credential is not exchanged over a plaintext\nconnection the record did not describe. `cotal meshes add` records both.\n\nWhen the authority service, login, or renewal is unavailable, the remote manager degrades\nfail-closed: it refuses new agents, restarts, and credential replacement rather than pretending\nlocal authority exists. Existing agents remain live only while their independent credentials are\nvalid. A hosted composition must revoke the managed grant and finish its resumable release before it\nrequests terminal retirement. Deleting DM or delivery consumers is not retirement and must not reset\na resumable lifecycle's frontier or pending state. The alias remains held until the terminal barrier\nconfirms. Restore service and renew successfully before asking it to recover an agent. See\n[Identity & auth](identity-and-auth.md#remote-manager-authority) and the [CLI\nreference](cli.md#supervise).\n\n## Spawning agents\n\n```bash\ncotal spawn                        # foreground: your default agent, in this terminal\ncotal spawn reviewer --detach      # supervised: the manager runs it in a PTY\ncotal attach --name reviewer       # watch/type into a detached agent (Ctrl-] detaches)\ncotal ps                           # what the manager is running\ncotal stop --name reviewer         # stop one\n```\n\nHow a spawn resolves:\n\n- **Persona.** A bare `cotal spawn` uses `.cotal/agents/default.md`; a positional name\n  picks `.cotal/agents/<name>.md`; `--config` takes an explicit ref or path. Set\n  `COTAL_DEFAULT_PERSONA=<name-or-path>` to change the fallback. Fields and format:\n  [agent files](agent-files.md).\n- **Harness.** Resolution order is an explicit `--agent` or `cotal_spawn` `agent` argument,\n  then the persona file's `agent:` pin, then the invoking caller's `COTAL_DEFAULT_AGENT`,\n  then the manager's `COTAL_DEFAULT_AGENT`, then the product default (Claude). Compared in\n  [Connectors](connectors.md); per-connector guides:\n  [Claude](connect-claude.md) \xB7 [OpenCode](connect-opencode.md) \xB7\n  [Hermes](connect-hermes.md) \xB7 [pi](connect-pi.md).\n- **Model.** `--model` overrides the persona file's `model:` (Claude: `opus` / `sonnet` or\n  a full id; OpenCode: `provider/model`). Connectors that expose a catalog report it via\n  `cotal models --agent opencode`: model ids plus available variants; pick one with\n  `--model provider/model --variant high`.\n- **Tools.** A spawned Claude Code agent gets the cotal tools plus the MCP servers the cotal\n  config shares, which first-run `cotal setup` fills with your own; narrow them per spawn with\n  `--share-tools` ([config](config.md)).\n- **Launch options.** `--opt key=value` (repeatable) passes a native harness flag straight\n  through; a persona or manifest `launchOptions:` mapping does the same declaratively (a\n  `--opt` wins per key). It is a **raw passthrough**, with no allow/deny list: Claude renders\n  each as `--key value` (a bare `--key` for an empty value), OpenCode merges them into its\n  agent config, and Hermes has no option surface so it fails loud. The trust boundary is the\n  `spawn` capability itself, not the flag set, so granting `spawn` is host-launch authority\n  ([security](security.md)). A key must be a plain flag name; malformed or prototype-polluting\n  keys are refused.\n\nDetach from an attached PTY with **Ctrl-]** (the agent keeps running); rebind it with\n`COTAL_DETACH_KEY=ctrl-<char>` when it clashes with a keybinding inside the agent's TUI.\n\n**Runtimes.** The manager spawns into a **pty** by default. It spawns the PTY in-process on\nevery platform, so replacing the manager worker closes its seats and the pty runtime gives no hot\nupdate. Any manager stop, bare `cotal down` included, stops and deprovisions those seats. A stopping\nmanager refuses new spawns and first waits for the ones it already accepted, so their seats stop too. On Linux\nit can still adopt and reap seats that an earlier manager launched under a detached per-seat\ncustodian, so those seats drain under the new manager; it starts no new custodian. A custodian whose agent has exited exits a few seconds later on its own. `cotal seats`\nlists the custodians left on the machine, and `cotal seats --drain` retires the ones whose agent\nhas exited while keeping every seat whose agent still runs ([cli.md](cli.md#seats)). When a pty\nagent exits on its own, in-process or under a custodian, the manager logs a `seat reaped:` line\nwith the exit code and, for a signalled child, the signal number. The line ends with the last line\nthe child printed that starts with a connector's `[cotal-<name>]` or `[cotal-<name>/<part>]`\nprefix, cut to 240 characters, when it printed one. A custodian keeps the same record beside the\nseat's custody record, so a later reap of that seat, including one by a\nsuccessor manager, reports how the child ended. When the custodian cannot write that record, it\nsays why in the seat's `custodian.log`, and a later reap of a child that ended on its own reports\nthe record as missing or unreadable. Optional runtimes are installed\nthrough the extension surface, for example `cotal ext add @cotal-ai/orca`, then selected with\n`--runtime orca` (similarly `@cotal-ai/tmux`, `@cotal-ai/cmux`, and `@cotal-ai/herdr`). They put teammates in native\nterminal surfaces rather than manager-owned PTYs. Runtime names are open-ended and resolved from\nthe registry; a missing provider or app throws, never silently falls back\n([architecture](architecture.md)).\n\n## Mesh registry\n\n`cotal up` records each running mesh in a machine-local registry\n(`~/.cotal/meshes/space.<key>.json`, named by a case-safe hex encoding of the space: broker URL, the project root holding its creds and\npersonas, and its mode). So a bare `cotal spawn <persona>` from *any* directory joins the\nrunning mesh with the right credentials instead of mistaking the cwd for a space:\n\n- `cotal use <name>` sets the default from every directory, including inside another mesh's\n  project. `--space <name>` overrides it for one command.\n- When one broker has records for several spaces, `cotal up --space <name>` refreshes that named\n  space.\n- A refresh rewrites only what that command decided: the server, root and mode, the user-auth\n  endpoints, and an explicit `--host` or `--max-sessions`. Every other field, such as the TLS\n  requirement, is kept as the record stands when the refresh writes it, so a change another\n  command made during the refresh survives. If the record was removed during the refresh, `up`\n  fails instead of writing it back.\n- With no live selected default, a project with its own `.cotal/` resolves to that project's\n  mesh; otherwise one running mesh is used automatically and several are an error.\n- `cotal meshes` lists them (a `*` marks the default); `cotal down` removes the entry.\n\nThe registry stores a *path*, never a secret; trust material stays in each project's\n`.cotal/auth`. If the mesh is down or won't take your creds, spawn fails with one\nsentence, never a raw NATS trace.\n\n### Meshes you did not start here\n\nA mesh running on another machine has no `cotal up` on this one, so register it by hand:\n\n```bash\ncotal meshes add            # guided: asks for the broker, probes it, offers what it finds\ncotal meshes add optiplex --server nats://100.90.12.34:4222 --root ~/meshes/optiplex \\\n  --allow-unencrypted-overlay      # see below: an overlay address needs this\ncotal meshes rm optiplex\n```\n\nOn a terminal, a bare `cotal meshes add` walks you through it: it probes the broker you name and\nreports whether it is open or requires credentials, offers the spaces the folder already holds\ncredentials for, and shows the record before writing it. Scripts and agents keep the flag form -\nwithout a terminal nothing prompts.\n\n`--root` is the local folder holding that mesh's `.cotal/auth` and `.cotal/agents` (its personas);\nthe mode is inferred from what that folder holds.\n\n**Know what you are copying.** For an authenticated mesh that folder carries the space's account\n**signing seed**, which is the authority to mint any identity in the space. A machine holding it\nis a certificate authority for the mesh rather than a client of it: anyone who reads it can\nimpersonate any agent, read every retained channel and DM, change ACLs, and keep issuing\nthemselves credentials. There is no per-machine revocation; undoing it means rotating the signing\nkey and re-minting every credential in the space. Copy it only to machines you would trust with\nthe whole mesh. `cotal mint` on its own does not substitute here: registering an `auth` mesh needs\nsigning material that composes, which a minted user credential is not. The\nbroker is probed before the record is written, so a bad address or a credential that mesh will not\naccept fails at registration rather than at your first `spawn` (`--force` records it without verifying,\nuseful when the mesh is simply down right now).\n\n#### Which addresses you may register\n\nRegistering a mesh is how this machine starts sending agent credentials to a broker it does not\nrun. NATS announces itself in plaintext before anyone authenticates, so an attacker on the path\ncan pose as the broker and read the credential out of the connect unless the connection\n**requires TLS**, which is recorded on the entry and enforced on every dial through it.\n\nWhat the record will require decides what you may register:\n\n- **Without required TLS**, the address is the gate: **loopback** (`127.0.0.0/8`, `::1`), or\n  **your private overlay** (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) with\n  `--allow-unencrypted-overlay`. The tunnel provides the protection, and this command cannot check\n  its state. Hostnames are refused because the lookup would choose which machine receives your\n  credentials.\n- **With required TLS**, set `--tls` or use a `tls://` URL. The recorded scheme enforces the TLS\n  requirement. A **hostname or public address** is accepted because the certificate chain and\n  hostname check identify the peer. A registration whose broker cannot complete the handshake\n  fails unless you pass `--force`, which records the entry without verification.\n\nOrdinary private ranges like `10.x` and `192.168.x` are refused in **both** modes. A caf\xE9's wifi\nis private but does not belong to you, and no public CA issues certificates for those ranges. An\naddress spelling changes nothing: `[::ffff:192.168.1.10]`, `3232235786`, `0300.0250.01.012`, and\n`192.168.257` all resolve to private addresses and receive the same refusal as the dotted form.\n`--force` exists for a mesh that is down. It never permits an unsafe credential destination.\n\n#### Registering a hosted user-auth mesh\n\nA user-auth space's IdP pins are established where the mesh runs and are never guessed. Register\none from **supplied** trust: `--user-auth-file bundle.json` (exported on the mesh's machine), or\n`--from https://\u2026/.well-known/cotal-mesh`, which asks before it contacts the address at all,\nfetches the discovery document over HTTPS, shows you the pins, and asks again before adopting\nthem. Redirects are refused because a 302 can walk a pinned fetch down to\nplaintext or onto another host, and the pinned exchange must be an `https://` URL too. The one\nexception is an exchange on **this machine**, where nothing leaves the box: plain `http://` is\naccepted for a loopback *literal* (`127.0.0.1`, `::1`, and any spelling of them), but **not** for\n`localhost`, which a hosts entry or poisoned lookup could point elsewhere. Use the\nliteral. Registration checks that the pinned exchange\nanswers `/health` and `/jwks` as the pinned issuer. It also checks that the broker refuses a\nbare connect; that refusal is the pass. The bundle's sentinel credentials are written to a private (0600) file\nunder the entry's root; the registry itself never carries the secret.\n\n**Without required TLS**, an overlay address is **refused unless you accept the dependency\nexplicitly**, with `--allow-unencrypted-overlay`. The address is not the guarantee: it is protected\nwhile the tunnel is up, and if the tunnel is down that range is ordinary carrier-grade NAT and\nwhoever answers the dial receives your credentials. Only you can know which it is, so the command\nasks you to say so. Your acceptance is recorded on the mesh entry rather than printed and\nforgotten, and the guided form asks the same question instead of taking the flag.\n\n**With required TLS** (`--tls`, or a `tls://` URL) that consent is no longer asked for, and the\nflag is not needed: the handshake is what protects the connection, so the acceptance it stood in\nfor has been replaced by proof rather than promise. `cotal meshes add <space> --server\nnats://100.64.0.1 --tls` registers an overlay address with no prompt, no flag and no recorded\nacceptance. This is the \"the flag disappears once the broker can be served over TLS\" case, and it\nhas now arrived.\n\nThis gate is on **registration**. `cotal join --creds --server <url>` deliberately takes an\nexplicit connection at face value and does not consult the registry, so it is not covered. Join\nthat way only to an address you would have registered.\n\nThe connection is still probed first, with the same second try at the longer budget the registry\npreflight uses, so a slow link reads as a connect that did not finish within that budget and a\nrefused port reads as a broker that is not running.\n\nRecords added this way are removed only by something that names them. A failed liveness probe\ndoes not delete any record: an unreachable broker, local or registered by hand, is shown as\n`offline` in `cotal meshes`. A bare command does not count that offline record as running;\nname it with `--space` to restart it. `cotal down` / `cotal clean all` still drop an `up` record for the\nproject they are tearing down, and they leave a hand-registered one alone even when `--root`\npointed at that project. A `cotal up` for that space refuses outright unless it is that same\nendpoint: finding a broker already answering there is a refresh that starts nothing and leaves the\nrecord's provenance alone, while actually starting the broker for that space, server and root\nmakes this machine the one running it, so the record becomes an ordinary local one that\n`cotal down` clears. The refusal names `cotal supervise --space <s> --server <url>` (plus `cotal\ndeliver`) when the registered broker is on another host, and `cotal meshes rm` when it is local.\n`cotal meshes rm` drops it and re-registering with `--force` replaces it. `rm` only forgets a\nmesh. To stop one running here, use `cotal down`.\n\n## Watching\n\n`cotal console` is the terminal view (TUI on a real terminal, plain line stream when\npiped); `cotal web` is the browser dashboard. Both are read-only observers; the\nwalkthrough is [Watch a mesh](watch-a-mesh.md).\n\n## History\n\nRetained history is operator-owned. `cotal clean history --force` purges a space's\nretained channel history; `--dms` also purges DMs (`cotal history clear` is an alias).\nIt is deliberately **not** an agent tool: agents cannot wipe the record\n([identity & auth](identity-and-auth.md)). For a **stopped** mesh, `cotal clean store\n--force` deletes the on-disk JetStream store outright, and `cotal clean all --force`\nalso resets the space identity ([CLI reference](cli.md#clean)).\n\n## Offline backup\n\nFor a coherent durable cut, preserve the whole stack first, then create the artifact while it stays\ndown:\n\n```bash\ncotal down --preserve-state\ncotal backup create ./space-backup        # full by default\n# later: deliberately resume the unchanged source\ncotal up --detach\n# or, from another preserved cut, restore before the normal listener opens\ncotal up --restore ./space-backup --detach\n```\n\nA refused cut leaves the mesh running and unfenced: fix what the refusal names and run\n`cotal down --preserve-state` again.\n\nUse `--store-dir` on both preservation and backup for a custom JetStream store. A store cap set\nwith `cotal up --max-file-store <bytes>` travels with the preserved state, and the resume renders it\nagain. nats-server reads the cap once at start and refuses a config reload that changes it, so a new\ncap always needs a restart. The cut records the chat stream's frontier per retained seat, so a\nresumed seat catches up from there instead of replaying its channels. `registry` is the\nonly partial selection (`backup create ... --only registry`; `up --restore ... --restore-only\nregistry`). Backup never stops or restarts a mesh implicitly, never opens the original store, and\ndoes not contain credentials or trust secrets. Backup/restore in every auth mode, open included,\nuses isolated, operation-specific maintenance logins; normal agent credentials cannot enter that\nlistener. Full\nrestore requires the same space and exact current local trust continuity, recreates conservative\nconsumer checkpoints bound to their snapshot stream sequence state, and resumes retained agents under\ntheir original principals. The trust commitment includes the cryptographically validated full\noperator/system/data-account root chain as well as static/user authority state. A registry-only\nrestore completes canonical empty infrastructure but leaves retained agents stopped because their\nDM/DLV/TASK/ACL state is outside that selection. Authenticated restore validates the complete space\ntrust bundle before staging or changing the preserved store. Interrupted ordinary resume retries the\nsame durable attempt after its prior listener is stopped. Restore re-entry can recover a surviving normal listener\nonly when its attempt nonce, NATS server name, process owner, endpoint, and target-store identity all\nmatch the fsynced proof. A provably dead uncommitted owner is retired under lock and replaced with a\nfresh attempt-bound listener; an occupied foreign listener or ambiguous owner is never adopted. The\nmanager commit validates while retained cleanup is still suppressed; the CLI durably records its\nattempt-bound 64-hex token in `manager-committed` / `resume-committed` before `finalizeResume` can\nrelease suppression. A retry from either committed state goes straight to exact-token finalization;\nfailure preserves the committed gate and retained cleanup suppression. Missing commit evidence,\ninterrupted finalization, a live recorded endpoint despite missing pidfiles, or ambiguous proof fails closed. See the [CLI\nbackup and restore contract](cli.md#backups) for artifact, checkpoint, fallback,\ndisaster-consent, and degraded-recovery details.\n\n## Personas from the CLI\n\n`cotal personas` manages the local catalog offline: `list` (`--running` overlays live\nmarkers), `show <name>`, `edit <name>` (re-validates on save), `new <name>`, `rm <name>\n--force`. The runtime write is `cotal_persona`; the runtime read is `cotal_personas`\n(list / show), both over the wire with the manager's ownership checks. Fields: [agent files](agent-files.md).\n\n## Gate recovery\n\nA manager that dies mid-registration leaves its issuance gate *frozen* under that registration\nop. The freeze is correct: it stops two incarnations serving at once. The successor now completes\nthat dead op on boot, using the same guard as [`cotal reconcile-gate`](cli.md#reconcile-gate): it\nacts only when the freeze-holder is affirmatively gone under a complete CONNZ sweep (`gone` and\n`sweepComplete=true`). If the dead op's spec write committed, it finishes that same freeze\n(promote and reopen at the committed registration revision). If the spec did not advance, it\nabort-reopens the gate (generation+1, processEpoch unchanged) and continues the normal takeover.\nBoot heal and the following re-registration use separate one-shot executor windows, so a large\npredecessor family cannot spend the takeover's credential lifetime. If that later registration\nstill crosses a connection lifetime, it retries the same frozen operation with fresh authority\nand resumes verified-holder progress instead of freezing a new generation.\nA live holder, an incomplete sweep, or an unreachable delivery daemon still\nrefuses. Silence is never evidence of death, and there is no TTL. If holder verification is\ninterrupted, the frozen operation resumes from its durable, operation-and-gate-revision-bound\nprogress after liveness is checked again. A later freeze cannot reuse that progress: the cursor\nbinds the exact op, gate revision, and holder set. Use `cotal reconcile-gate` when the boot path cannot run\n(daemon down, a non-manager endpoint, or you want to lift the freeze without starting a manager). A spawn that hits the same frozen gate names that verb in the refusal\n(`blockedOp=registration`, the holding `opId`, `remedy=cotal reconcile-gate`) instead of a\nwait-timeout: the facts were always in the manager log; they now reach the spawn caller too.\n\nGive reconciliation a **quiet manager**. Suspend systemd restart policies, watchdogs, health-check\nrestart loops, and any other automation that can start or kill `cotal supervise` while boot healing or\n`cotal reconcile-gate` is running. Leave one recovery attempt in control until it finishes.\nRestarting the manager during the walk interrupts the current authority window. Durable progress makes\nthat interruption resumable, but a quiet manager is still the fastest and safest incident procedure.\n\n### Last-resort JetStream store replacement\n\nStore replacement is not normal gate recovery, is never automatic, and is destructive to mesh history.\nUse it only after the retained store cannot be reconciled and after deciding that losing its durable\ncontents is acceptable.\n\n1. Stop every actor touching the space: supervisor, watchdog, manager, delivery daemon, and broker.\n   Confirm that no Cotal or NATS process still has the store open.\n2. Preserve the stopped store before changing anything. Move `.cotal/nats` aside to a dated backup and\n   archive both `nats` and `auth`. Do not delete the only copy.\n3. Understand the loss: replacing the store removes JetStream message and control history and durable\n   consumer state. Agent session files stored outside JetStream remain, but the mesh history they\n   referenced does not.\n4. Start the broker against a new empty store, then start one manager. Wait until it reports\n   serving successfully.\n5. Repopulate the mesh only after that manager is healthy. Re-enable supervisors, watchdogs, and other\n   restart automation last.\n\nKeep the preserved store until the incident is reviewed and any required forensic or manual recovery is\ncomplete. Restoring it later restores the old durable state, including the fault that led to this last\nresort, so do not swap it back into a live mesh casually.\n\n## When something looks absent\n\nPermission denials are **loud, never silent**: an over-tight ACL rejects the endpoint call and\nalso shows up as a logged denial, instead of returning an empty or incomplete result that looks\nsuccessful. Check\n`.cotal/manager.<key>.log`, `.cotal/delivery.<key>.log` (one pair per space, keyed as\n[Config](config.md#project-files) describes), and `.cotal/nats.log`; `cotal status` shows\nwhat is actually running. Those files live under the **project** `.cotal/`, not `~/.cotal`,\nunless the mesh root is the home directory. `cotal up --detach` redirects delivery and manager\nstdio onto those files, so an operator-created systemd unit around that launcher does not put\nthe child logs in that unit's journal. `journalctl -u <unit>` can be empty while the crash\nreason is already in the project log. Manager log lines start with the UTC time they were\nwritten. The access rules are collected in\n[Channels & permissions](channels-and-permissions.md).\n"
     },
     {
       "slug": "security",
@@ -19790,7 +19804,7 @@ var DOCS_BUNDLE = {
       "title": "Upgrading a running deployment",
       "kind": "Guide (informative)",
       "summary": "Substrate stability tells you what the version numbers promise.",
-      "body": "# Upgrading a running deployment\n\n> **Guide** (informative) \xB7 **For:** operators upgrading a mesh that already exists \xB7 **See also:** [Substrate stability](stability.md), [Run a mesh](run-a-mesh.md), [Identity and auth](identity-and-auth.md)\n\n[Substrate stability](stability.md) tells you what the version numbers promise. This page is the\nother half: what to actually do when the deployment already exists, has credentials in it, and\ncannot simply be recreated. Every release that breaks a running deployment gets a section here,\nnaming what migrates on its own, what does not, and the order to move the pieces in.\n\n## The pre-1.0 upgrade contract\n\nThe packages are pre-1.0, so a minor bump may break an API or an on-disk expectation. Four\ncommitments make that survivable for someone with a fleet:\n\n- **Pin an exact version.** `0.N.P`, never `^0.N.P`. A range can pull a breaking minor in during an\n  unrelated reinstall.\n- **Every break that touches a running deployment gets a section on this page**, written in terms of\n  what an operator does, not in terms of which module changed.\n- **Read the section before you start, not halfway through.** A section names the work up front\n  precisely so the operation does not change shape once it is underway.\n- **A break that cannot be made automatic says so.** Where credentials or state must be recreated by\n  hand, the section says which ones and when, rather than leaving you to discover it at the moment\n  the first one stops working.\n- **A change to the shape of a credential, or to who may renew one, is breaking whatever the commit\n  marker says.** This rule is stated because the marker is a judgement made while writing the code\n  and the consequence is felt by someone running it a day later. A fleet that keeps authenticating\n  looks compatible and is not, if nothing in it can renew. Any automated check of this rule would\n  read commit markers, so a break recorded as a feature is the one case it could not see, which is\n  why the rule is written for people first. **The marker held for this release: the 0.49.0 change\n  that caused all of this, `36d177951 feat(core)!`, did carry its `!`.** The rule exists for the\n  next one that does not.\n\nWhat this page does not promise is a rolling upgrade. Nothing in the current line dual-serves two\nauthority versions, so where broker and manager run separately there is a window in which the mesh\nis down. The sections below give that window's shape so it can be scheduled rather than endured.\n\n## Workflow programs that bind `once` in 0.65.0\n\n`once` is now a scope of the workflow language, so it is a reserved name. A program that declares\nits own `once` binding (`const once = ...`, a parameter or a function named `once`) is refused at\nvalidation with L2002. Nothing else about a running mesh changes.\n\n### What stops working\n\nA run whose recorded program binds `once` cannot be resumed after the upgrade, because a resume\nvalidates the recorded program again. A new `cotal run start` of such a program is refused before\nanything is recorded.\n\n### Before the upgrade\n\nList the runs with `cotal run ps` and check each program that is still running or held for a\nbinding named `once`. Let those runs finish on the old version before you upgrade the manager, and\nrename the binding in the program before you start it again.\n\n## From 0.58.0 to 0.59.0\n\nEvery connector now publishes a failed run's `RUN_ERROR` on `events.<owner>.<actor>` with the fixed\nmessage `run failed` and no `code` or `rawEvent`. The error text and error kind a harness reports\ncan echo a prompt, a peer message or tool output, and that channel has a different read ACL. A\nreader that showed the message or branched on `code` gets neither after the upgrade. Where a\nconnector reports the error kind as the agent's presence condition, that is unchanged.\n\n### Settle pending event frames before the upgrade\n\nEach session's events are frozen in its event write-ahead log before they are published. A session\nrestarted on 0.59.0 whose log still holds an unacknowledged frame with an older `RUN_ERROR` does not\nrepublish it: its event emitter halts with `egress-run-error` and publishes nothing further for that\nsession. The broker may or may not already hold that frame, so the halt cannot settle it.\n\n1. Stop the seats cleanly on 0.58.0, with the broker still up.\n2. List the logs that still hold a pending frame. The logs live under the events state root\n   (`COTAL_WORKSPACE_ROOT`). Empty output means there is nothing to settle.\n\n   ```sh\n   find \"$COTAL_WORKSPACE_ROOT/.cotal/events\" -name wal.json \\\n     -exec jq -r 'select(.pending != null) | input_filename' {} +\n   ```\n\n3. For each session listed, start it again on 0.58.0 while the broker is reachable, let it recover,\n   stop it, and run step 2 again. Recovery publishes the frame as 0.58.0 would have, error text\n   included, so it only finishes what 0.58.0 had already started.\n\n   If that start halts with `cas-loss` instead, the agent's subject is no longer at the sequence this\n   log expects, and no restart settles that log, on 0.58.0 or later. A lost acknowledgement is one\n   cause: the broker stored the frame, so it and its error text are already on the channel, and every\n   retry halts the same way because the stream checks the frozen expectation before it deduplicates.\n   The halt message names the other causes, such as a second emitter for the same agent under a\n   different state root, a restored stream or frontier record, or a purged channel. With those the\n   pending frame may never have reached the broker, so a `cas-loss` does not tell you whether it\n   landed. Find and stop any second writer and rule out a restored state first. Clearing the halt\n   then means purging the agent's event channel and removing the agent's directory under the events\n   state root whole (see [Event plane](connect-claude.md#event-plane)). That abandons the pending\n   frame whether or not the broker has it, and the purge also drops the earlier frames of every\n   session of that agent.\n4. Upgrade once step 2 prints nothing.\n\nIf a session halts with `egress-run-error` after the upgrade, go back to step 3 for that session on\n0.58.0. Do not edit or delete `wal.json` on its own to get past either halt: clearing the pending\nframe abandons that epoch, an event the broker never received is lost, and removing part of the\ndirectory leaves a state the next start refuses.\n\n## Explicit actor grants in 0.59.0\n\n`cotal actor grant` no longer fills an omitted ACL flag with its wide default. A grant names\n`--scope`, `--allow-subscribe` and `--allow-publish`, or passes `--full` to give the ones it leaves\noff their wide defaults (`spawn,role:default`, `>` read, `>` post). Any other grant is refused. The\nbreak is in the CLI on the machine that holds the actor ledger, the one that ran\n`cotal up --user-auth --idp <url>`. No stored row, credential or wire message changes.\n\n### What keeps working\n\nExisting actor ledger rows keep the authority they were granted, and their users and agents connect\nas before. `actor revoke`, `actor list` and a `grant` that names all three ACL flags behave as they\ndid on 0.58.0. Nothing on disk is converted.\n\n### What stops working\n\nA grant that leaves off any of the three flags without `--full` exits 1 with\n`refusing to grant \"<actor>\" with --scope, --allow-subscribe, --allow-publish left off`, naming the\nflags it is missing, and then prints both accepted forms. It writes no row and does not retire the\nactor's current lifecycle. An existing row stays as it was, and an actor granted for the first time\nstays out until the grant is run again. This includes the bare grant printed on 0.58.0 by\n`cotal login`, `cotal status`, `actor list` and the not-granted refusal. Look for it in provisioning\nscripts, onboarding runbooks and anything that pastes those hints.\n\n### Upgrade order\n\nChange the scripts before the ledger machine is upgraded, and make each grant name all three flags.\n0.58.0 and 0.59.0 both accept that form. To keep a wide row, write its defaults out:\n\n```sh\ncotal actor grant <actor> --sub <IdP subject> \\\n  --scope spawn,role:default --allow-subscribe '>' --allow-publish '>'\n```\n\nSwitch to `--full` only once the ledger machine runs 0.59.0. 0.58.0 refuses it with\n`Unknown option '--full'` before it reads the ledger. Brokers, managers and participant machines\nneed nothing for this break, so their order is the one the section above gives.\n\n### The window\n\nThis break has no outage. No process restarts for it, and a refused grant changes nothing. The\nexposure is a grant script that runs against 0.59.0 before it was changed: it fails and grants\nnothing.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. On the ledger machine, save the output\nof `cotal actor list` to compare rows after the changed scripts run, and list the scripts that call\n`cotal actor grant`.\n\n### The upgrade end to end\n\n```sh\n# on the ledger machine, still on 0.58.0\ncotal actor list > actors-before.txt\ngrep -rn 'actor grant' <your provisioning scripts>\n# make every grant name --scope, --allow-subscribe and --allow-publish, run them, then upgrade\nnpm i -g cotal-ai@0.59.0\ncotal actor list | diff actors-before.txt -\n```\n\nBoth refusals quoted here were run on 0.58.0 and on the 0.59.0 code. That brokers, managers and stored\nrows need nothing is read from the change, which touches only the CLI and its hints, and was not run\non a live split deployment.\n\n## Repeated flags refused in 0.59.0\n\nA `cotal` flag given more than once is now a usage error unless the command declares it repeatable.\nOn 0.58.0 the last value won with no message, so `cotal down web --space a --space b` acted on `b`\nwhile a wrapper that checked the first `--space` verified `a`. The break is in the command-line\nparser on the machine that runs the command, including commands added with `cotal ext add`. No\nstored state, credential or wire message changes.\n\n### What keeps working\n\nA command line that gives each flag once parses as it did on 0.58.0, in any order and in the\n`--flag=value` form. Flags whose help says repeatable, such as `--opt` and `down --session-store`,\nstill collect every value. A flag-shaped word after `--` is still a positional. The daemons, units\nand agents that `cotal` starts for itself are given each flag once, so a fleet driven only by `cotal`\ncommands typed by hand needs no action.\n\n### What stops working\n\nA command line that repeats any other flag exits 1 before the command runs. It prints\n`Option '--space' cannot be repeated`, or `Option '-f, --file' cannot be repeated` for a flag with a\nshort form, followed by the command's help. `-f` and `--file` count as the same flag. Look for it in\nscripts, aliases and wrappers that append a flag to override one set earlier, such as a fixed\n`--space` followed by `\"$@\"`.\n\n### Upgrade order\n\nChange those scripts first so each flag is given once. 0.58.0 and 0.59.0 both accept that form.\nBrokers, managers and participant machines need nothing for this break, and each machine's CLI\napplies it when that machine is upgraded, so their order is the one the sections above give.\n\n### The window\n\nThis break has no outage. No process restarts for it, and a refused command does nothing. The\nexposure is a script that still repeats a flag when it runs on 0.59.0: it exits 1 instead of acting on\nthe last value.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. List the scripts, aliases and wrappers\nthat call `cotal` so each one can be checked.\n\n### The upgrade end to end\n\n```sh\n# still on 0.58.0\ngrep -rn 'cotal ' <your scripts and wrappers>\n# give each non-repeatable flag once, then upgrade\nnpm i -g cotal-ai@0.59.0\n# run each changed script; a repeat left behind exits 1 with the usage error and does nothing\n```\n\nThe refusal and its messages were run against the 0.59.0 parser and `cotal topology view`. That the\nargument lists `cotal` builds for its own processes give each flag once is read from the code, and\nwas not run on a live split deployment.\n\n## Detached spawns from a seat's shell in 0.62.0\n\nOn a static or open mesh, `cotal spawn --detach` run inside a managed seat's shell now launches as\nthat seat. On 0.61.0 it minted a one-shot operator instrument, so the manager recorded that\ninstrument as the spawner and the seat's own `cotal_despawn` of the child was refused with\n`not authorized: <seat> was not spawned by <caller> (admin tier required)`. The break is in the CLI\non the machine where the seats run. No stored state, credential or wire message changes.\n\n### What keeps working\n\n`cotal spawn --detach` from an operator terminal or from a script outside any seat launches as\nbefore, and so does any call with `--creds`, one aimed at a space other than the seat's own, or a raw\nopen target named with `--server` and an unregistered `--space`. A user-auth mesh is unchanged. A seat with\n`capabilities: [spawn]` still spawns from its shell, and can now stop that child with\n`cotal_despawn`. `--on <instance>` from a seat's shell still lands on that manager instance, now as\nthe seat.\n\n### What stops working\n\n- On a static mesh, a seat without `capabilities: [spawn]` can no longer spawn from its shell. Its\n  own credential holds no spawn subject, so the broker refuses the request and the command exits 1.\n- A child launched from a seat's shell is now that seat's child, so the manager stops it when the\n  seat exits, as it does for a `cotal_spawn` child. A child that has to outlive the seat that\n  started it now goes with the seat.\n- A seat launched without `COTAL_SPACE` is placed by its static credential. Every connector sets\n  that variable, so this only reaches a hand-built launch: from such a seat's shell, a spawn aimed at\n  a static space that holds no credential for the seat is refused instead of running as the operator.\n\n### Upgrade order\n\nOnly the CLI that seats run from their shell changes, which is the one installed on the host where\nthe seats run. Brokers and managers need nothing for this break, so their order is the one the\nsections above give.\n\n### The window\n\nThis break has no outage. No process restarts for it. A child already running when you upgrade\nkeeps the spawner the manager recorded at its launch.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. List the agent files whose seats run\n`cotal spawn --detach` from their shell, note which of them lack `capabilities: [spawn]`, and note\nwhich of their children must outlive the seat.\n\n### The upgrade end to end\n\n```sh\n# still on 0.61.0: find the seats that spawn from their shell\ngrep -rln 'cotal spawn' .cotal/agents\n# add `capabilities: [spawn]` to each of those agent files that lacks it, and launch any child\n# that must outlive its seat from an operator terminal instead\nnpm i -g cotal-ai@0.62.0\n```\n\nThe attribution, the despawn, the refusal of a seat without `spawn`, the stop on seat exit and a\nseat's `--on` spawn were run on a local static mesh, and the attribution and the despawn on a local\nopen mesh.\n\n## From 0.53.0 to 0.54.0\n\nManager calls now borrow an instance-bound `manager-caller` credential. Followed mutations require\n`manager.goal-result` on the selected manager, so a compatible issuer, manager and client must be\nloaded together. An older manager is refused before a followed mutation; upgrading an installed\nbinary alone does not replace code in a running manager, connector or embedded client.\n\n### Preserve state before changing processes\n\nSnapshot the broker's durable storage using its supported backup procedure, the host authority and\nactor ledgers, and each participant's manager identity, runtime custody records, credentials and\nsaved sessions. Include the embedding application's database and configuration under its supported\nbackup procedure. Record the loaded package versions and the CLI path used by bearer helpers.\nKeep these copies private. Do not change the IdP issuer, regenerate manager identities, rotate agent\ncredentials or recreate tenant storage to make the upgrade pass.\n\nNo ledger, goal-history or session conversion is required for this change. Existing ordinary\nmessaging credentials retain their normal expiry rules. New manager-caller credentials are obtained\non demand from the current grant; old manager-call credentials do not gain the new view automatically.\nExisting accepted goals remain durable and must not be submitted again merely because observation\nwas interrupted. Fresh remote registration publishes its service status at the current revision and\nepoch; do not seed that status manually.\n\n### Upgrade the split deployment\n\n1. Stage one pinned 0.54.0 package set for the host and participants, including the embedding SDKs.\n   Pause new manager mutations and let accepted work settle where possible before reloading processes.\n2. Upgrade the host issuer and embedding first. Keep the broker, its account identities and durable\n   storage in place. Then load the matching manager release on each participating machine.\n3. Preserve active seats through the runtime's supported update path. A Linux custodial runtime may\n   release and re-adopt seats within its 600-second unattended window; verify the actual runtime,\n   custody records and process identities before relying on it. A legacy PTY runtime without release\n   support cannot preserve active seats through a generic manager restart. Drain it at an approved\n   idle window instead of signalling the manager or replacing conversations.\n4. Reload the clients and connectors through their session-preserving host controls. Refresh any\n   bearer helper captured from an older immutable CLI path. A transport-only reconnect does not reload\n   JavaScript. Verify authenticated instance selection, a read-only manager command and canonical\n   result recovery before allowing new followed mutations.\n\nTreat the interval from issuer reload through compatible manager/client reload as a manager-control\noutage. Mixed versions can refuse discovery or commands; there is no promised rolling transition.\nOrdinary agent sessions survive only where their runtime and credentials permit it. If verification\nfails, keep mutations paused and repair forward from the preserved state rather than resetting it.\nThis release does not add host-backed enrollment or terminal release for stock participant detached\nagents; see [Remote supervised agents](run-a-mesh.md#remote-supervised-agents).\n\n## From 0.48.2 to 0.49.0\n\n0.49.0 changes how a credential's authority is recorded. A credential is no longer only a signed\nfile: it is an *issuance*, with a generation the issuer chose and durable evidence of the ceiling it\nwas granted under. The important consequence for a running deployment is not at connect time. It is\nat renewal time.\n\n### What keeps working without any action\n\n- **Existing agent credentials keep authenticating.** A credential minted under 0.48.2 is not\n  revoked and is not rejected at connect. Nothing needs to be re-issued to bring the fleet back up\n  after the upgrade.\n- **The channel registry survives.** Channels, their replay settings, descriptions, and usage text\n  are ordinary durable state and are not rewritten by the upgrade.\n- **`cotal deliver` is still a standalone command.** Running the delivery daemon as its own process\n  remains supported; it is not restricted to being a child of `cotal up`.\n- **`cotal join` keeps its flags.** In particular `--lifecycle-uid` is not new in 0.49.0. It has\n  been required alongside `--creds` since well before this release, and the pairing rule did not\n  change here. A scripted external join that worked under 0.48.2 works unchanged.\n\n### What does not migrate\n\n**A credential minted before 0.49.0 cannot be renewed.** Managed agent credentials carry a\n24-hour lifetime and the manager re-signs one once it passes **75%** of its life, ticking every\nquarter of the TTL so a tick always lands inside that window. When the manager reaches a credential\nthat carries no issuance, it refuses to renew it and logs the agent by name:\n\n```\n! managed cred renewal <agent>: renewManagedStaticCred: <agent> carries no issuance;\n  a static credential minted before SPEC 13.15 is not renewed under an unbound generation\n  - respawn the agent\n  - the agent dies loud at this cred's expiry unless it is reminted\n```\n\nSo the fleet comes up fine, runs normally, and then each agent stops at its own credential's\nexpiry, within roughly a day of the upgrade, one at a time rather than together. The refusal is\ndeliberate: the renewal would otherwise have to invent a generation nobody issued, which is the\nstate the release exists to remove.\n\n**Respawn the managed agents as the last step of the upgrade.** For this particular upgrade the\nrespawn is not optional: stopping a 0.48.2 manager ends its agent processes whichever CLI you use,\nfor the reason given under the outage window below. The respawn is how they come back, and it is\nalso what mints each credential as an issuance so it renews from then on. One planned pass over the\nfleet is the whole job. Skipping it leaves agents stopped and, for any credential that survived\ninto 0.49.0 unminted, brings the renewal cliff above a day later, one agent at a time.\n\n### Credentials you minted yourself\n\n**A credential you minted with `cotal mint` is a different case, and it very likely needs\nnothing.** The distinction that matters is not the word \"static\", which covers both. It is **what\nminted the credential and who owns its renewal**. A credential the **manager** minted for an agent\nit spawned carries a lifetime and is renewed by the manager, so it is the subject of everything\nabove. A credential **you** minted with `cotal mint` and handed to an external peer is issued with\n**no expiry at all**, and no manager renews it: it is not in the sweep, so there is no renewal to\nfail. It keeps working after the upgrade, and re-minting it would mean coordinating with a third\nparty for no gain.\n\nThe manager says which one it is holding. Where a credential has no expiry to reach, the sweep\nnames it and moves on rather than refusing:\n\n```\n! managed cred renewal <agent>: credential is unbounded - not renewed\n  (a pre-TTL credential stays as minted until respawn)\n```\n\nRe-mint an external peer's credential only if you want it to carry a lifetime, and at a time you\nchoose.\n\n### How to read the boot log\n\nA 0.49.0 manager starting over an existing space may print lines like:\n\n```\n  verified evicted: <holder-key> (3/12)\n  already verified (durable): <holder-key>\n\u2713 boot self-heal: manager/<id> registration gate reopened at generation <n>\n```\n\nThese are **not** a credential migration, and reading them as one is the most likely way to\nconclude the fleet is fine when it is not. They come from the manager repairing **one** endpoint\nregistration gate that a previous restart left frozen, and they enumerate that single gate's\ncredential-family holders as it verifies each one evicted. `already verified (durable)` on a later\nstart is the repair cursor resuming, not a credential that became durable. The repair is real and\nuseful (it is what previously needed `cotal reconcile-gate` by hand), but it says nothing about\nwhether your agent credentials carry issuances. The renewal refusal above is the signal that does.\n\n### Which side to upgrade first in a split topology\n\nMove the manager first.\n\nThe stores 0.49.0 introduces are created by the **manager** at its own boot, not by the broker.\nThey are create-or-verify and idempotent, so a 0.49.0 manager brings the space's authority stores\nup to the new shape itself, and it does so against whichever broker is answering.\n\nBeing honest about the evidence behind each direction, because they are not equally established:\n\n- **Broker-first was measured on a live 30-agent deployment** (issue #1578). Upgrading the broker\n  first locks the old manager out immediately: `cotal up` re-renders the broker's generated config\n  from the trust record, and after the restart the still-0.48.2 manager is refused on every\n  connection with an `authentication error` naming the Nkey, continuously. That text comes from the\n  broker process, not from a Cotal command, so match on its shape rather than on an exact string.\n  `cotal ps` reports zero agents while\n  the agent processes are still alive, because the manager has lost its view of them, not because\n  they died. Upgrading the manager clears it immediately.\n- **Manager-first is reasoned from where the new stores are provisioned**, not from a measured\n  fleet upgrade. It is the recommended order because the manager is the component that creates what\n  0.49.0 adds, but it has not been run end to end on a production split topology at the time of\n  writing. Treat it as the better-supported order rather than a guaranteed one, and keep the\n  rollback below ready either way.\n\nWhichever order you pick, **this is not a rolling upgrade**. Between the two steps the mesh is down\nand the manager cannot see its agents. Go straight through rather than pausing between them, and\nschedule it as an outage window.\n\n### What the window looks like\n\n- **The managed agent processes do not survive step 1, in either order.** This is the one place\n  where the obvious reordering does not rescue you, so it is worth understanding rather than\n  working around. Sparing agents on a bare manager stop is a **handshake**: a 0.49.0 manager\n  publishes a capability file proving it can release its agents, and a 0.49.0 `cotal down` refuses\n  the stop unless it finds one. **A 0.48.2 manager never publishes that file**, because the\n  mechanism ships in the release you are installing. So the old CLI against the old manager sends a\n  plain stop and takes every seat with it, and the new CLI against the old manager either refuses\n  (leaving `--with-agents`, which reaps deliberately) or falls to the legacy path, warns that it\n  cannot verify the manager can spare its agents, and signals it anyway.\n- **You can confirm which side you are on in one command, without stopping anything.** The flag that\n  marks the newer behaviour is absent from the older CLI, and its summary line makes the difference\n  plain:\n\n  ```\n  $ cotal down --help          # on 0.48.2\n  cotal down - stop the whole local stack, or name only the components to stop\n\n  $ cotal down --help          # on 0.49.0\n  cotal down - stop the whole local stack (managed agents stay running unless --with-agents), ...\n  ```\n\n  If your `cotal down --help` does not mention `--with-agents`, stopping the manager stops the\n  agents with it.\n- **Therefore the respawn in step 5 is mandatory recovery for this upgrade, not an optional pass.**\n  It is also the step that re-mints credentials as issuances, so it is the same action either way.\n  Plan the window to include it rather than treating it as cleanup.\n- The **manager's view** of them is lost while the two sides disagree, so `cotal ps` reports zero\n  and control commands do not reach seats.\n- **Messages are not delivered** while the mesh is down.\n- The window is as long as it takes to restart the second component, plus the manager's own start.\n  It is minutes, not hours, provided you do not stop between the steps.\n- **Nothing self-heals if you stop halfway.** The refusal is continuous until both sides match.\n\n### Snapshot this before you start\n\nTake these while the deployment is still on 0.48.2. The two `cotal` reads are live reads and must\nhappen before anything stops.\n\n- **A filesystem or volume snapshot of both containers**, if your platform offers one. This is the\n  only rollback that covers every case, and it is what the reporting deployment used.\n- **`cotal backup create <dir>`**, for the durable space state, **but read the next paragraph before\n  you rely on it**: on a split broker and manager topology it is very likely unavailable to you, and\n  the volume snapshot above is your actual rollback.\n- **The trust records and credential directory** under `.cotal/auth` on the manager host, including\n  the per-space material directory. These are what a re-mint would otherwise have to replace.\n- **A copy of the channel registry**, so you can verify it came back rather than assuming it did:\n  `cotal channels list` before and after.\n- **The output of `cotal ps`**, so you know how many seats you expect to see afterwards and can tell\n  a lost view from a lost agent.\n\n#### `cotal backup` on a split topology\n\n**`cotal backup create` cannot read a running stack.** It requires a completed cut, and only\n`cotal down --preserve-state` publishes one:\n\n```\n$ cotal backup create ./backup.0482\n\u2717 backup requires a completed cut; run `cotal down --preserve-state` first\n```\n\n**And `cotal down --preserve-state` requires a manager alive on the host you run it from.** It uses\nthat manager to attest that every retained child stopped, and the check is deliberately fail-closed:\na manager that is dead or merely uncertain refuses rather than preserving an unproven cut. The check\nreads a local pidfile, so a **remote** manager does not satisfy it. On a split topology the broker\nhost has no local manager, which means the documented durable-backup path is not available there.\n\n**Measured rather than assumed, at 0.48.2**: the backup refusal above is executed output. The\npreservation requirement is read from `down.ts` at the same tag, where the preserve path asks a\nmanager to prepare an inventory and then requires that manager to be locally alive before it\ncommits. The part not executed end to end is a genuine two-host split, which needs two real hosts.\n\n**What to do instead.** Use the filesystem or volume snapshot of both containers. That is the\nrollback the reporting deployment actually used, it covers the broker's durable state and the\nmanager's credential material together, and it does not depend on either component being able to\nattest for the other. If you want `cotal backup` as well, take it from a host that does have a live\nlocal manager, and understand it is a second copy rather than the primary rollback.\n\n**This looks like a product limitation rather than a documentation gap**, and it is written here as\none so an operator is not left thinking they mis-typed a command. The upgrade path for the exact\ntopology this page is addressed to cannot use the documented backup command.\n\n### The upgrade end to end\n\n```bash\n# 0. on 0.48.2, STILL RUNNING: record what you expect to see afterwards.\n#    These two are live reads, so they must happen before anything stops.\ncotal channels list > channels.before\ncotal ps > ps.before\n\n# 1. manager host. READ THE NOTE BELOW THE BLOCK FIRST: this step ends the\n#    managed agent processes whichever order you choose, and the respawn in\n#    step 5 is how they come back. It is recovery, not tidying.\n#\n#    STOP THE MANAGER WITH THE 0.48.2 CLI, BEFORE INSTALLING 0.49.0. The\n#    order matters and it is not recoverable once you install: a 0.49.0\n#    `down manager` REFUSES to stop a 0.48.2 manager whose pid record carries\n#    a start token, which is every manager on a platform that can read one\n#    (Linux can):\n#      refusing bare manager stop: ... does not prove this manager can detach\n#      its agents; use --with-agents or stop the agents explicitly\n#    The refusal names two remedies and NEITHER clears it for this case. The\n#    check reads a capability file that only a 0.49.0 manager writes; it never\n#    counts agents, so stopping them first changes nothing. And `--with-agents`\n#    is whole-stack only, so `down manager --with-agents` is refused by its own\n#    flag rule. See #1592.\ncotal down manager                        # the 0.48.2 CLI, still installed.\n                                          # 0.48.2 has no --with-agents; this\n                                          # is the whole route. On a host that\n                                          # runs the whole stack, the 0.49.0\n                                          # `cotal down --with-agents` after\n                                          # installing is the alternative.\nnpm install -g cotal-ai@0.49.0            # ONLY after the stop above\n#    `supervise` RUNS IN THE FOREGROUND and holds the terminal until you stop\n#    it. There is no --detach on this command. Start it under whatever keeps\n#    your manager alive normally (systemd unit, container entrypoint, or a\n#    second terminal), and run the remaining steps from another shell.\ncotal supervise --space <space> --server nats://<broker>:4222\n\n# 2. broker host: stop the stack.\n#    NOT `--preserve-state` on a split topology: it needs a manager alive on\n#    THIS host to attest its children stopped, and yours is on the other one.\n#    Your rollback is the volume snapshot from \"Snapshot this before you\n#    start\", not `cotal backup`.\n#    See \"cotal backup on a split topology\" above.\ncotal down\n\n# 3. broker host: install 0.49.0 and start it again\nnpm install -g cotal-ai@0.49.0\n#    Record the manager log's size BEFORE starting, so step 3a can tell THIS\n#    boot's output from every earlier one. It must be captured here, ahead of\n#    the start: taken afterwards it sits past the new line and the wait hangs.\n#    `<spaceKey>` is NOT the space name. It is lowercase hex of the name's\n#    UTF-8 bytes, so space `prod` is `manager.70726f64.log`. Do not guess it:\n#    `cotal up` prints the real path on its launch line. Substituting the\n#    plain name points at a file that does not exist, and the wait below then\n#    burns its full timeout before telling you.\nLOG=.cotal/manager.<spaceKey>.log\nOFF=$( [ -f \"$LOG\" ] && wc -c < \"$LOG\" || echo 0 )\ncotal up --detach --host 0.0.0.0 --space <space> --no-manager\n\n# 3a. SPLIT TOPOLOGY ONLY: `--no-manager` above boots the broker (and the\n#     delivery daemon) with NO local manager on the broker host, so there is\n#     no wait-and-stop step on a current cotal-ai. The rest of this step is\n#     the OLDER-host recipe, kept because the flag is refused there and that\n#     refusal is your signal you are on it: without the flag the `up` also\n#     starts a local manager, and you must wait for the log to show it is up,\n#     then stop it, or you finish the upgrade with two managers and the one\n#     you did not intend is the one nobody is watching.\n#     A bare `grep -q` does NOT wait: it reads once and exits 1 immediately\n#     if the line has not been written yet. Bound the wait instead, so a\n#     manager that never comes up fails loudly rather than reading as ready.\n#     The log is opened APPEND-ONLY, so on any host that has run a manager\n#     before, this file ALREADY carries a `manager up` line from an earlier\n#     boot. Grepping the whole file therefore matches instantly and waits for\n#     nothing. Read only what THIS boot appended, using the $OFF captured in\n#     step 3 above (before the start, which is the only point it is correct):\ntimeout 60 bash -c \\\n  \"until tail -c +$((OFF+1)) \\\"$LOG\\\" | grep -q '. manager up'; do sleep 1; done\"\n#     exit 0 = THIS boot logged it; exit 124 = it never did, so STOP and look.\n#     This manager is 0.49.0 and publishes its own spare-capability file, so\n#     the bare stop below is NOT the refusal case from step 1.\ncotal down manager                                      # broker + delivery remain\n#     On a current cotal-ai the two commands above are unnecessary (nothing\n#     to wait for, nothing to stop) and `cotal down manager` simply reports\n#     no manager to stop.\n\n# 4. verify the mesh is whole again before touching the fleet.\n#    Do NOT compare `cotal ps` against ps.before yet: step 1 ended the agent\n#    processes, so at this point it is EXPECTED to be empty, and an empty\n#    `ps` is also the signature of the broker/manager mismatch described\n#    above. The two are indistinguishable here, so compare what the mesh\n#    itself should have carried across instead:\ncotal channels list # compare against channels.before: this SHOULD match now\ncotal ps            # expect it to be EMPTY here; ps.before is the target for\n                    # step 5, not for this step\n\n# 5. the step that is easy to skip: respawn the managed agents so their\n#    credentials are re-minted as issuances and can renew. Persona is a\n#    POSITIONAL argument here, unlike `cotal stop`, which requires --name.\n#    One call per agent:\ncotal spawn <persona> --detach --name <n> --space <space>\n#    then the comparison step 4 could not make:\ncotal ps            # NOW compare against ps.before: seat count should match\n```\n\nThe mesh is down from step 2 until step 3 finishes. That is the window. On a split topology there is\nno cut and no backup inside it, so the window is the stop, the install and the restart, nothing more.\n\n## Adding a section for a future release\n\n**Every changeset marked breaking adds a section to this page.** A release that changes what an\noperator must do, in what order, or what stops working, is not finished until the section exists.\n`scripts/upgrade-section-gate.mjs` grades a commit range for this: run it as\n`pnpm upgrade-section-gate --base <ref>` and it reds when the range carries a breaking change and\nadds no new release section. CI runs its self-test and, as a step of the `attribution` job, grades\neach pull request's own range as `HEAD^1..HEAD` over the merge snapshot it checked out. That job is\nthe only context in the branch protection rule set, so a red gate FAILS A REQUIRED CHECK AND BLOCKS\nTHE MERGE. The section is not optional and a reviewer cannot wave it through without an\nadministrator overriding branch protection. Be precise about what the check proves either\nway, because one trusted past its evidence is worse than none. It proves a section for a release\n**was written here**. It cannot prove the section is **correct**, or that it describes the break\nthat actually landed, and it cannot see a breaking change that carries no marker at all. Reviewing\nthe words remains a person's job.\n\n**Mark the break, or the gate cannot see it.** Any one of these is enough, and they are the only\nthings it reads:\n\n- a `!` before the colon in the commit subject, as in `feat(core)!: bind hosted runs to the caller`\n- a `BREAKING CHANGE:` footer in the commit body\n- a changeset in `.changeset/` declaring a `major` bump for any package\n\nThe marker must survive the squash. A `!` that lives only in a commit you squash away is not in the\nrange the gate grades, so put it in the subject that lands on `main`.\n\n**The heading is a `##` and names the release**, like `## From 0.48.2 to 0.49.0`. Both matter, and\nneither is a style preference. Coverage is claimed by a heading, so a heading that names\nno release claims every release and distinguishes none: `## Notes` with a sentence under it would\notherwise satisfy the rule. Naming the release also makes the section the one an operator upgrading\nthat release will search for. Use `###` freely for detail inside a section. Subsections belong to\ntheir release rather than counting as separate coverage.\n\nA section is written for the operator, not for the reviewer. It answers, in this order:\n\n1. What keeps working with no action at all.\n2. What does **not** migrate, and when that becomes visible. Name the log line if there is one.\n3. The order to move components in for a split topology, and why that order.\n4. What the outage window looks like, including what survives it.\n5. What to snapshot before starting.\n6. The commands, end to end.\n\n**Where an answer was not measured, say so in the document rather than guessing.** An operator who\nknows which half of a recommendation is reasoned and which is measured can plan around it; one who\nfinds out afterwards cannot.\n"
+      "body": "# Upgrading a running deployment\n\n> **Guide** (informative) \xB7 **For:** operators upgrading a mesh that already exists \xB7 **See also:** [Substrate stability](stability.md), [Run a mesh](run-a-mesh.md), [Identity and auth](identity-and-auth.md)\n\n[Substrate stability](stability.md) tells you what the version numbers promise. This page is the\nother half: what to actually do when the deployment already exists, has credentials in it, and\ncannot simply be recreated. Every release that breaks a running deployment gets a section here,\nnaming what migrates on its own, what does not, and the order to move the pieces in.\n\n## The pre-1.0 upgrade contract\n\nThe packages are pre-1.0, so a minor bump may break an API or an on-disk expectation. Four\ncommitments make that survivable for someone with a fleet:\n\n- **Pin an exact version.** `0.N.P`, never `^0.N.P`. A range can pull a breaking minor in during an\n  unrelated reinstall.\n- **Every break that touches a running deployment gets a section on this page**, written in terms of\n  what an operator does, not in terms of which module changed.\n- **Read the section before you start, not halfway through.** A section names the work up front\n  precisely so the operation does not change shape once it is underway.\n- **A break that cannot be made automatic says so.** Where credentials or state must be recreated by\n  hand, the section says which ones and when, rather than leaving you to discover it at the moment\n  the first one stops working.\n- **A change to the shape of a credential, or to who may renew one, is breaking whatever the commit\n  marker says.** This rule is stated because the marker is a judgement made while writing the code\n  and the consequence is felt by someone running it a day later. A fleet that keeps authenticating\n  looks compatible and is not, if nothing in it can renew. Any automated check of this rule would\n  read commit markers, so a break recorded as a feature is the one case it could not see, which is\n  why the rule is written for people first. **The marker held for this release: the 0.49.0 change\n  that caused all of this, `36d177951 feat(core)!`, did carry its `!`.** The rule exists for the\n  next one that does not.\n\nWhat this page does not promise is a rolling upgrade. Nothing in the current line dual-serves two\nauthority versions, so where broker and manager run separately there is a window in which the mesh\nis down. The sections below give that window's shape so it can be scheduled rather than endured.\n\n## Lifecycle-blocked refusals in 0.66.0\n\nA refusal that carries `ai.cotal.ep.lifecycle-blocked` now reports only the lifecycle state it\nread. Nothing about a running mesh changes. A client that branches on the detail must read the new\nfield.\n\n### What stops working\n\nA refusal raised at the issuance gate used to carry `headState` without reading the head:\n`retiring` for a frozen gate and `retired` for a retired one. It now carries `gateState`\n(`frozen` or `retired`) and no `headState`. A client that treats `headState: \"retired\"` as a\nburned uid, or `headState: \"retiring\"` as a retirement in flight, no longer matches those\nrefusals, and the `[lifecycle ...]` suffix on the error string changes the same way. A custom\nissuance barrier whose `observe` returns a frozen gate without a valid `op` (a string `opId` and\none of the four op kinds) is now refused as `internal` by `registerServiceInstance`.\n\n### Before the upgrade\n\nUpdate such a client to read `gateState` for a gate refusal and `blockedOp` for the operation that\nholds the gate. `headState` is present only when the refusal read the head, for example an\nactivation refused because the head is still retiring.\n\n## Workflow programs that bind `once` in 0.65.0\n\n`once` is now a scope of the workflow language, so it is a reserved name. A program that declares\nits own `once` binding (`const once = ...`, a parameter or a function named `once`) is refused at\nvalidation with L2002. Nothing else about a running mesh changes.\n\n### What stops working\n\nA run whose recorded program binds `once` cannot be resumed after the upgrade, because a resume\nvalidates the recorded program again. A new `cotal run start` of such a program is refused before\nanything is recorded.\n\n### Before the upgrade\n\nList the runs with `cotal run ps` and check each program that is still running or held for a\nbinding named `once`. Let those runs finish on the old version before you upgrade the manager, and\nrename the binding in the program before you start it again.\n\n## From 0.58.0 to 0.59.0\n\nEvery connector now publishes a failed run's `RUN_ERROR` on `events.<owner>.<actor>` with the fixed\nmessage `run failed` and no `code` or `rawEvent`. The error text and error kind a harness reports\ncan echo a prompt, a peer message or tool output, and that channel has a different read ACL. A\nreader that showed the message or branched on `code` gets neither after the upgrade. Where a\nconnector reports the error kind as the agent's presence condition, that is unchanged.\n\n### Settle pending event frames before the upgrade\n\nEach session's events are frozen in its event write-ahead log before they are published. A session\nrestarted on 0.59.0 whose log still holds an unacknowledged frame with an older `RUN_ERROR` does not\nrepublish it: its event emitter halts with `egress-run-error` and publishes nothing further for that\nsession. The broker may or may not already hold that frame, so the halt cannot settle it.\n\n1. Stop the seats cleanly on 0.58.0, with the broker still up.\n2. List the logs that still hold a pending frame. The logs live under the events state root\n   (`COTAL_WORKSPACE_ROOT`). Empty output means there is nothing to settle.\n\n   ```sh\n   find \"$COTAL_WORKSPACE_ROOT/.cotal/events\" -name wal.json \\\n     -exec jq -r 'select(.pending != null) | input_filename' {} +\n   ```\n\n3. For each session listed, start it again on 0.58.0 while the broker is reachable, let it recover,\n   stop it, and run step 2 again. Recovery publishes the frame as 0.58.0 would have, error text\n   included, so it only finishes what 0.58.0 had already started.\n\n   If that start halts with `cas-loss` instead, the agent's subject is no longer at the sequence this\n   log expects, and no restart settles that log, on 0.58.0 or later. A lost acknowledgement is one\n   cause: the broker stored the frame, so it and its error text are already on the channel, and every\n   retry halts the same way because the stream checks the frozen expectation before it deduplicates.\n   The halt message names the other causes, such as a second emitter for the same agent under a\n   different state root, a restored stream or frontier record, or a purged channel. With those the\n   pending frame may never have reached the broker, so a `cas-loss` does not tell you whether it\n   landed. Find and stop any second writer and rule out a restored state first. Clearing the halt\n   then means purging the agent's event channel and removing the agent's directory under the events\n   state root whole (see [Event plane](connect-claude.md#event-plane)). That abandons the pending\n   frame whether or not the broker has it, and the purge also drops the earlier frames of every\n   session of that agent.\n4. Upgrade once step 2 prints nothing.\n\nIf a session halts with `egress-run-error` after the upgrade, go back to step 3 for that session on\n0.58.0. Do not edit or delete `wal.json` on its own to get past either halt: clearing the pending\nframe abandons that epoch, an event the broker never received is lost, and removing part of the\ndirectory leaves a state the next start refuses.\n\n## Explicit actor grants in 0.59.0\n\n`cotal actor grant` no longer fills an omitted ACL flag with its wide default. A grant names\n`--scope`, `--allow-subscribe` and `--allow-publish`, or passes `--full` to give the ones it leaves\noff their wide defaults (`spawn,role:default`, `>` read, `>` post). Any other grant is refused. The\nbreak is in the CLI on the machine that holds the actor ledger, the one that ran\n`cotal up --user-auth --idp <url>`. No stored row, credential or wire message changes.\n\n### What keeps working\n\nExisting actor ledger rows keep the authority they were granted, and their users and agents connect\nas before. `actor revoke`, `actor list` and a `grant` that names all three ACL flags behave as they\ndid on 0.58.0. Nothing on disk is converted.\n\n### What stops working\n\nA grant that leaves off any of the three flags without `--full` exits 1 with\n`refusing to grant \"<actor>\" with --scope, --allow-subscribe, --allow-publish left off`, naming the\nflags it is missing, and then prints both accepted forms. It writes no row and does not retire the\nactor's current lifecycle. An existing row stays as it was, and an actor granted for the first time\nstays out until the grant is run again. This includes the bare grant printed on 0.58.0 by\n`cotal login`, `cotal status`, `actor list` and the not-granted refusal. Look for it in provisioning\nscripts, onboarding runbooks and anything that pastes those hints.\n\n### Upgrade order\n\nChange the scripts before the ledger machine is upgraded, and make each grant name all three flags.\n0.58.0 and 0.59.0 both accept that form. To keep a wide row, write its defaults out:\n\n```sh\ncotal actor grant <actor> --sub <IdP subject> \\\n  --scope spawn,role:default --allow-subscribe '>' --allow-publish '>'\n```\n\nSwitch to `--full` only once the ledger machine runs 0.59.0. 0.58.0 refuses it with\n`Unknown option '--full'` before it reads the ledger. Brokers, managers and participant machines\nneed nothing for this break, so their order is the one the section above gives.\n\n### The window\n\nThis break has no outage. No process restarts for it, and a refused grant changes nothing. The\nexposure is a grant script that runs against 0.59.0 before it was changed: it fails and grants\nnothing.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. On the ledger machine, save the output\nof `cotal actor list` to compare rows after the changed scripts run, and list the scripts that call\n`cotal actor grant`.\n\n### The upgrade end to end\n\n```sh\n# on the ledger machine, still on 0.58.0\ncotal actor list > actors-before.txt\ngrep -rn 'actor grant' <your provisioning scripts>\n# make every grant name --scope, --allow-subscribe and --allow-publish, run them, then upgrade\nnpm i -g cotal-ai@0.59.0\ncotal actor list | diff actors-before.txt -\n```\n\nBoth refusals quoted here were run on 0.58.0 and on the 0.59.0 code. That brokers, managers and stored\nrows need nothing is read from the change, which touches only the CLI and its hints, and was not run\non a live split deployment.\n\n## Repeated flags refused in 0.59.0\n\nA `cotal` flag given more than once is now a usage error unless the command declares it repeatable.\nOn 0.58.0 the last value won with no message, so `cotal down web --space a --space b` acted on `b`\nwhile a wrapper that checked the first `--space` verified `a`. The break is in the command-line\nparser on the machine that runs the command, including commands added with `cotal ext add`. No\nstored state, credential or wire message changes.\n\n### What keeps working\n\nA command line that gives each flag once parses as it did on 0.58.0, in any order and in the\n`--flag=value` form. Flags whose help says repeatable, such as `--opt` and `down --session-store`,\nstill collect every value. A flag-shaped word after `--` is still a positional. The daemons, units\nand agents that `cotal` starts for itself are given each flag once, so a fleet driven only by `cotal`\ncommands typed by hand needs no action.\n\n### What stops working\n\nA command line that repeats any other flag exits 1 before the command runs. It prints\n`Option '--space' cannot be repeated`, or `Option '-f, --file' cannot be repeated` for a flag with a\nshort form, followed by the command's help. `-f` and `--file` count as the same flag. Look for it in\nscripts, aliases and wrappers that append a flag to override one set earlier, such as a fixed\n`--space` followed by `\"$@\"`.\n\n### Upgrade order\n\nChange those scripts first so each flag is given once. 0.58.0 and 0.59.0 both accept that form.\nBrokers, managers and participant machines need nothing for this break, and each machine's CLI\napplies it when that machine is upgraded, so their order is the one the sections above give.\n\n### The window\n\nThis break has no outage. No process restarts for it, and a refused command does nothing. The\nexposure is a script that still repeats a flag when it runs on 0.59.0: it exits 1 instead of acting on\nthe last value.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. List the scripts, aliases and wrappers\nthat call `cotal` so each one can be checked.\n\n### The upgrade end to end\n\n```sh\n# still on 0.58.0\ngrep -rn 'cotal ' <your scripts and wrappers>\n# give each non-repeatable flag once, then upgrade\nnpm i -g cotal-ai@0.59.0\n# run each changed script; a repeat left behind exits 1 with the usage error and does nothing\n```\n\nThe refusal and its messages were run against the 0.59.0 parser and `cotal topology view`. That the\nargument lists `cotal` builds for its own processes give each flag once is read from the code, and\nwas not run on a live split deployment.\n\n## Detached spawns from a seat's shell in 0.62.0\n\nOn a static or open mesh, `cotal spawn --detach` run inside a managed seat's shell now launches as\nthat seat. On 0.61.0 it minted a one-shot operator instrument, so the manager recorded that\ninstrument as the spawner and the seat's own `cotal_despawn` of the child was refused with\n`not authorized: <seat> was not spawned by <caller> (admin tier required)`. The break is in the CLI\non the machine where the seats run. No stored state, credential or wire message changes.\n\n### What keeps working\n\n`cotal spawn --detach` from an operator terminal or from a script outside any seat launches as\nbefore, and so does any call with `--creds`, one aimed at a space other than the seat's own, or a raw\nopen target named with `--server` and an unregistered `--space`. A user-auth mesh is unchanged. A seat with\n`capabilities: [spawn]` still spawns from its shell, and can now stop that child with\n`cotal_despawn`. `--on <instance>` from a seat's shell still lands on that manager instance, now as\nthe seat.\n\n### What stops working\n\n- On a static mesh, a seat without `capabilities: [spawn]` can no longer spawn from its shell. Its\n  own credential holds no spawn subject, so the broker refuses the request and the command exits 1.\n- A child launched from a seat's shell is now that seat's child, so the manager stops it when the\n  seat exits, as it does for a `cotal_spawn` child. A child that has to outlive the seat that\n  started it now goes with the seat.\n- A seat launched without `COTAL_SPACE` is placed by its static credential. Every connector sets\n  that variable, so this only reaches a hand-built launch: from such a seat's shell, a spawn aimed at\n  a static space that holds no credential for the seat is refused instead of running as the operator.\n\n### Upgrade order\n\nOnly the CLI that seats run from their shell changes, which is the one installed on the host where\nthe seats run. Brokers and managers need nothing for this break, so their order is the one the\nsections above give.\n\n### The window\n\nThis break has no outage. No process restarts for it. A child already running when you upgrade\nkeeps the spawner the manager recorded at its launch.\n\n### Snapshot this first\n\nNothing is rewritten, so this break has no state to back up. List the agent files whose seats run\n`cotal spawn --detach` from their shell, note which of them lack `capabilities: [spawn]`, and note\nwhich of their children must outlive the seat.\n\n### The upgrade end to end\n\n```sh\n# still on 0.61.0: find the seats that spawn from their shell\ngrep -rln 'cotal spawn' .cotal/agents\n# add `capabilities: [spawn]` to each of those agent files that lacks it, and launch any child\n# that must outlive its seat from an operator terminal instead\nnpm i -g cotal-ai@0.62.0\n```\n\nThe attribution, the despawn, the refusal of a seat without `spawn`, the stop on seat exit and a\nseat's `--on` spawn were run on a local static mesh, and the attribution and the despawn on a local\nopen mesh.\n\n## From 0.53.0 to 0.54.0\n\nManager calls now borrow an instance-bound `manager-caller` credential. Followed mutations require\n`manager.goal-result` on the selected manager, so a compatible issuer, manager and client must be\nloaded together. An older manager is refused before a followed mutation; upgrading an installed\nbinary alone does not replace code in a running manager, connector or embedded client.\n\n### Preserve state before changing processes\n\nSnapshot the broker's durable storage using its supported backup procedure, the host authority and\nactor ledgers, and each participant's manager identity, runtime custody records, credentials and\nsaved sessions. Include the embedding application's database and configuration under its supported\nbackup procedure. Record the loaded package versions and the CLI path used by bearer helpers.\nKeep these copies private. Do not change the IdP issuer, regenerate manager identities, rotate agent\ncredentials or recreate tenant storage to make the upgrade pass.\n\nNo ledger, goal-history or session conversion is required for this change. Existing ordinary\nmessaging credentials retain their normal expiry rules. New manager-caller credentials are obtained\non demand from the current grant; old manager-call credentials do not gain the new view automatically.\nExisting accepted goals remain durable and must not be submitted again merely because observation\nwas interrupted. Fresh remote registration publishes its service status at the current revision and\nepoch; do not seed that status manually.\n\n### Upgrade the split deployment\n\n1. Stage one pinned 0.54.0 package set for the host and participants, including the embedding SDKs.\n   Pause new manager mutations and let accepted work settle where possible before reloading processes.\n2. Upgrade the host issuer and embedding first. Keep the broker, its account identities and durable\n   storage in place. Then load the matching manager release on each participating machine.\n3. Preserve active seats through the runtime's supported update path. A Linux custodial runtime may\n   release and re-adopt seats within its 600-second unattended window; verify the actual runtime,\n   custody records and process identities before relying on it. A legacy PTY runtime without release\n   support cannot preserve active seats through a generic manager restart. Drain it at an approved\n   idle window instead of signalling the manager or replacing conversations.\n4. Reload the clients and connectors through their session-preserving host controls. Refresh any\n   bearer helper captured from an older immutable CLI path. A transport-only reconnect does not reload\n   JavaScript. Verify authenticated instance selection, a read-only manager command and canonical\n   result recovery before allowing new followed mutations.\n\nTreat the interval from issuer reload through compatible manager/client reload as a manager-control\noutage. Mixed versions can refuse discovery or commands; there is no promised rolling transition.\nOrdinary agent sessions survive only where their runtime and credentials permit it. If verification\nfails, keep mutations paused and repair forward from the preserved state rather than resetting it.\nThis release does not add host-backed enrollment or terminal release for stock participant detached\nagents; see [Remote supervised agents](run-a-mesh.md#remote-supervised-agents).\n\n## From 0.48.2 to 0.49.0\n\n0.49.0 changes how a credential's authority is recorded. A credential is no longer only a signed\nfile: it is an *issuance*, with a generation the issuer chose and durable evidence of the ceiling it\nwas granted under. The important consequence for a running deployment is not at connect time. It is\nat renewal time.\n\n### What keeps working without any action\n\n- **Existing agent credentials keep authenticating.** A credential minted under 0.48.2 is not\n  revoked and is not rejected at connect. Nothing needs to be re-issued to bring the fleet back up\n  after the upgrade.\n- **The channel registry survives.** Channels, their replay settings, descriptions, and usage text\n  are ordinary durable state and are not rewritten by the upgrade.\n- **`cotal deliver` is still a standalone command.** Running the delivery daemon as its own process\n  remains supported; it is not restricted to being a child of `cotal up`.\n- **`cotal join` keeps its flags.** In particular `--lifecycle-uid` is not new in 0.49.0. It has\n  been required alongside `--creds` since well before this release, and the pairing rule did not\n  change here. A scripted external join that worked under 0.48.2 works unchanged.\n\n### What does not migrate\n\n**A credential minted before 0.49.0 cannot be renewed.** Managed agent credentials carry a\n24-hour lifetime and the manager re-signs one once it passes **75%** of its life, ticking every\nquarter of the TTL so a tick always lands inside that window. When the manager reaches a credential\nthat carries no issuance, it refuses to renew it and logs the agent by name:\n\n```\n! managed cred renewal <agent>: renewManagedStaticCred: <agent> carries no issuance;\n  a static credential minted before SPEC 13.15 is not renewed under an unbound generation\n  - respawn the agent\n  - the agent dies loud at this cred's expiry unless it is reminted\n```\n\nSo the fleet comes up fine, runs normally, and then each agent stops at its own credential's\nexpiry, within roughly a day of the upgrade, one at a time rather than together. The refusal is\ndeliberate: the renewal would otherwise have to invent a generation nobody issued, which is the\nstate the release exists to remove.\n\n**Respawn the managed agents as the last step of the upgrade.** For this particular upgrade the\nrespawn is not optional: stopping a 0.48.2 manager ends its agent processes whichever CLI you use,\nfor the reason given under the outage window below. The respawn is how they come back, and it is\nalso what mints each credential as an issuance so it renews from then on. One planned pass over the\nfleet is the whole job. Skipping it leaves agents stopped and, for any credential that survived\ninto 0.49.0 unminted, brings the renewal cliff above a day later, one agent at a time.\n\n### Credentials you minted yourself\n\n**A credential you minted with `cotal mint` is a different case, and it very likely needs\nnothing.** The distinction that matters is not the word \"static\", which covers both. It is **what\nminted the credential and who owns its renewal**. A credential the **manager** minted for an agent\nit spawned carries a lifetime and is renewed by the manager, so it is the subject of everything\nabove. A credential **you** minted with `cotal mint` and handed to an external peer is issued with\n**no expiry at all**, and no manager renews it: it is not in the sweep, so there is no renewal to\nfail. It keeps working after the upgrade, and re-minting it would mean coordinating with a third\nparty for no gain.\n\nThe manager says which one it is holding. Where a credential has no expiry to reach, the sweep\nnames it and moves on rather than refusing:\n\n```\n! managed cred renewal <agent>: credential is unbounded - not renewed\n  (a pre-TTL credential stays as minted until respawn)\n```\n\nRe-mint an external peer's credential only if you want it to carry a lifetime, and at a time you\nchoose.\n\n### How to read the boot log\n\nA 0.49.0 manager starting over an existing space may print lines like:\n\n```\n  verified evicted: <holder-key> (3/12)\n  already verified (durable): <holder-key>\n\u2713 boot self-heal: manager/<id> registration gate reopened at generation <n>\n```\n\nThese are **not** a credential migration, and reading them as one is the most likely way to\nconclude the fleet is fine when it is not. They come from the manager repairing **one** endpoint\nregistration gate that a previous restart left frozen, and they enumerate that single gate's\ncredential-family holders as it verifies each one evicted. `already verified (durable)` on a later\nstart is the repair cursor resuming, not a credential that became durable. The repair is real and\nuseful (it is what previously needed `cotal reconcile-gate` by hand), but it says nothing about\nwhether your agent credentials carry issuances. The renewal refusal above is the signal that does.\n\n### Which side to upgrade first in a split topology\n\nMove the manager first.\n\nThe stores 0.49.0 introduces are created by the **manager** at its own boot, not by the broker.\nThey are create-or-verify and idempotent, so a 0.49.0 manager brings the space's authority stores\nup to the new shape itself, and it does so against whichever broker is answering.\n\nBeing honest about the evidence behind each direction, because they are not equally established:\n\n- **Broker-first was measured on a live 30-agent deployment** (issue #1578). Upgrading the broker\n  first locks the old manager out immediately: `cotal up` re-renders the broker's generated config\n  from the trust record, and after the restart the still-0.48.2 manager is refused on every\n  connection with an `authentication error` naming the Nkey, continuously. That text comes from the\n  broker process, not from a Cotal command, so match on its shape rather than on an exact string.\n  `cotal ps` reports zero agents while\n  the agent processes are still alive, because the manager has lost its view of them, not because\n  they died. Upgrading the manager clears it immediately.\n- **Manager-first is reasoned from where the new stores are provisioned**, not from a measured\n  fleet upgrade. It is the recommended order because the manager is the component that creates what\n  0.49.0 adds, but it has not been run end to end on a production split topology at the time of\n  writing. Treat it as the better-supported order rather than a guaranteed one, and keep the\n  rollback below ready either way.\n\nWhichever order you pick, **this is not a rolling upgrade**. Between the two steps the mesh is down\nand the manager cannot see its agents. Go straight through rather than pausing between them, and\nschedule it as an outage window.\n\n### What the window looks like\n\n- **The managed agent processes do not survive step 1, in either order.** This is the one place\n  where the obvious reordering does not rescue you, so it is worth understanding rather than\n  working around. Sparing agents on a bare manager stop is a **handshake**: a 0.49.0 manager\n  publishes a capability file proving it can release its agents, and a 0.49.0 `cotal down` refuses\n  the stop unless it finds one. **A 0.48.2 manager never publishes that file**, because the\n  mechanism ships in the release you are installing. So the old CLI against the old manager sends a\n  plain stop and takes every seat with it, and the new CLI against the old manager either refuses\n  (leaving `--with-agents`, which reaps deliberately) or falls to the legacy path, warns that it\n  cannot verify the manager can spare its agents, and signals it anyway.\n- **You can confirm which side you are on in one command, without stopping anything.** The flag that\n  marks the newer behaviour is absent from the older CLI, and its summary line makes the difference\n  plain:\n\n  ```\n  $ cotal down --help          # on 0.48.2\n  cotal down - stop the whole local stack, or name only the components to stop\n\n  $ cotal down --help          # on 0.49.0\n  cotal down - stop the whole local stack (managed agents stay running unless --with-agents), ...\n  ```\n\n  If your `cotal down --help` does not mention `--with-agents`, stopping the manager stops the\n  agents with it.\n- **Therefore the respawn in step 5 is mandatory recovery for this upgrade, not an optional pass.**\n  It is also the step that re-mints credentials as issuances, so it is the same action either way.\n  Plan the window to include it rather than treating it as cleanup.\n- The **manager's view** of them is lost while the two sides disagree, so `cotal ps` reports zero\n  and control commands do not reach seats.\n- **Messages are not delivered** while the mesh is down.\n- The window is as long as it takes to restart the second component, plus the manager's own start.\n  It is minutes, not hours, provided you do not stop between the steps.\n- **Nothing self-heals if you stop halfway.** The refusal is continuous until both sides match.\n\n### Snapshot this before you start\n\nTake these while the deployment is still on 0.48.2. The two `cotal` reads are live reads and must\nhappen before anything stops.\n\n- **A filesystem or volume snapshot of both containers**, if your platform offers one. This is the\n  only rollback that covers every case, and it is what the reporting deployment used.\n- **`cotal backup create <dir>`**, for the durable space state, **but read the next paragraph before\n  you rely on it**: on a split broker and manager topology it is very likely unavailable to you, and\n  the volume snapshot above is your actual rollback.\n- **The trust records and credential directory** under `.cotal/auth` on the manager host, including\n  the per-space material directory. These are what a re-mint would otherwise have to replace.\n- **A copy of the channel registry**, so you can verify it came back rather than assuming it did:\n  `cotal channels list` before and after.\n- **The output of `cotal ps`**, so you know how many seats you expect to see afterwards and can tell\n  a lost view from a lost agent.\n\n#### `cotal backup` on a split topology\n\n**`cotal backup create` cannot read a running stack.** It requires a completed cut, and only\n`cotal down --preserve-state` publishes one:\n\n```\n$ cotal backup create ./backup.0482\n\u2717 backup requires a completed cut; run `cotal down --preserve-state` first\n```\n\n**And `cotal down --preserve-state` requires a manager alive on the host you run it from.** It uses\nthat manager to attest that every retained child stopped, and the check is deliberately fail-closed:\na manager that is dead or merely uncertain refuses rather than preserving an unproven cut. The check\nreads a local pidfile, so a **remote** manager does not satisfy it. On a split topology the broker\nhost has no local manager, which means the documented durable-backup path is not available there.\n\n**Measured rather than assumed, at 0.48.2**: the backup refusal above is executed output. The\npreservation requirement is read from `down.ts` at the same tag, where the preserve path asks a\nmanager to prepare an inventory and then requires that manager to be locally alive before it\ncommits. The part not executed end to end is a genuine two-host split, which needs two real hosts.\n\n**What to do instead.** Use the filesystem or volume snapshot of both containers. That is the\nrollback the reporting deployment actually used, it covers the broker's durable state and the\nmanager's credential material together, and it does not depend on either component being able to\nattest for the other. If you want `cotal backup` as well, take it from a host that does have a live\nlocal manager, and understand it is a second copy rather than the primary rollback.\n\n**This looks like a product limitation rather than a documentation gap**, and it is written here as\none so an operator is not left thinking they mis-typed a command. The upgrade path for the exact\ntopology this page is addressed to cannot use the documented backup command.\n\n### The upgrade end to end\n\n```bash\n# 0. on 0.48.2, STILL RUNNING: record what you expect to see afterwards.\n#    These two are live reads, so they must happen before anything stops.\ncotal channels list > channels.before\ncotal ps > ps.before\n\n# 1. manager host. READ THE NOTE BELOW THE BLOCK FIRST: this step ends the\n#    managed agent processes whichever order you choose, and the respawn in\n#    step 5 is how they come back. It is recovery, not tidying.\n#\n#    STOP THE MANAGER WITH THE 0.48.2 CLI, BEFORE INSTALLING 0.49.0. The\n#    order matters and it is not recoverable once you install: a 0.49.0\n#    `down manager` REFUSES to stop a 0.48.2 manager whose pid record carries\n#    a start token, which is every manager on a platform that can read one\n#    (Linux can):\n#      refusing bare manager stop: ... does not prove this manager can detach\n#      its agents; use --with-agents or stop the agents explicitly\n#    The refusal names two remedies and NEITHER clears it for this case. The\n#    check reads a capability file that only a 0.49.0 manager writes; it never\n#    counts agents, so stopping them first changes nothing. And `--with-agents`\n#    is whole-stack only, so `down manager --with-agents` is refused by its own\n#    flag rule. See #1592.\ncotal down manager                        # the 0.48.2 CLI, still installed.\n                                          # 0.48.2 has no --with-agents; this\n                                          # is the whole route. On a host that\n                                          # runs the whole stack, the 0.49.0\n                                          # `cotal down --with-agents` after\n                                          # installing is the alternative.\nnpm install -g cotal-ai@0.49.0            # ONLY after the stop above\n#    `supervise` RUNS IN THE FOREGROUND and holds the terminal until you stop\n#    it. There is no --detach on this command. Start it under whatever keeps\n#    your manager alive normally (systemd unit, container entrypoint, or a\n#    second terminal), and run the remaining steps from another shell.\ncotal supervise --space <space> --server nats://<broker>:4222\n\n# 2. broker host: stop the stack.\n#    NOT `--preserve-state` on a split topology: it needs a manager alive on\n#    THIS host to attest its children stopped, and yours is on the other one.\n#    Your rollback is the volume snapshot from \"Snapshot this before you\n#    start\", not `cotal backup`.\n#    See \"cotal backup on a split topology\" above.\ncotal down\n\n# 3. broker host: install 0.49.0 and start it again\nnpm install -g cotal-ai@0.49.0\n#    Record the manager log's size BEFORE starting, so step 3a can tell THIS\n#    boot's output from every earlier one. It must be captured here, ahead of\n#    the start: taken afterwards it sits past the new line and the wait hangs.\n#    `<spaceKey>` is NOT the space name. It is lowercase hex of the name's\n#    UTF-8 bytes, so space `prod` is `manager.70726f64.log`. Do not guess it:\n#    `cotal up` prints the real path on its launch line. Substituting the\n#    plain name points at a file that does not exist, and the wait below then\n#    burns its full timeout before telling you.\nLOG=.cotal/manager.<spaceKey>.log\nOFF=$( [ -f \"$LOG\" ] && wc -c < \"$LOG\" || echo 0 )\ncotal up --detach --host 0.0.0.0 --space <space> --no-manager\n\n# 3a. SPLIT TOPOLOGY ONLY: `--no-manager` above boots the broker (and the\n#     delivery daemon) with NO local manager on the broker host, so there is\n#     no wait-and-stop step on a current cotal-ai. The rest of this step is\n#     the OLDER-host recipe, kept because the flag is refused there and that\n#     refusal is your signal you are on it: without the flag the `up` also\n#     starts a local manager, and you must wait for the log to show it is up,\n#     then stop it, or you finish the upgrade with two managers and the one\n#     you did not intend is the one nobody is watching.\n#     A bare `grep -q` does NOT wait: it reads once and exits 1 immediately\n#     if the line has not been written yet. Bound the wait instead, so a\n#     manager that never comes up fails loudly rather than reading as ready.\n#     The log is opened APPEND-ONLY, so on any host that has run a manager\n#     before, this file ALREADY carries a `manager up` line from an earlier\n#     boot. Grepping the whole file therefore matches instantly and waits for\n#     nothing. Read only what THIS boot appended, using the $OFF captured in\n#     step 3 above (before the start, which is the only point it is correct):\ntimeout 60 bash -c \\\n  \"until tail -c +$((OFF+1)) \\\"$LOG\\\" | grep -q '. manager up'; do sleep 1; done\"\n#     exit 0 = THIS boot logged it; exit 124 = it never did, so STOP and look.\n#     This manager is 0.49.0 and publishes its own spare-capability file, so\n#     the bare stop below is NOT the refusal case from step 1.\ncotal down manager                                      # broker + delivery remain\n#     On a current cotal-ai the two commands above are unnecessary (nothing\n#     to wait for, nothing to stop) and `cotal down manager` simply reports\n#     no manager to stop.\n\n# 4. verify the mesh is whole again before touching the fleet.\n#    Do NOT compare `cotal ps` against ps.before yet: step 1 ended the agent\n#    processes, so at this point it is EXPECTED to be empty, and an empty\n#    `ps` is also the signature of the broker/manager mismatch described\n#    above. The two are indistinguishable here, so compare what the mesh\n#    itself should have carried across instead:\ncotal channels list # compare against channels.before: this SHOULD match now\ncotal ps            # expect it to be EMPTY here; ps.before is the target for\n                    # step 5, not for this step\n\n# 5. the step that is easy to skip: respawn the managed agents so their\n#    credentials are re-minted as issuances and can renew. Persona is a\n#    POSITIONAL argument here, unlike `cotal stop`, which requires --name.\n#    One call per agent:\ncotal spawn <persona> --detach --name <n> --space <space>\n#    then the comparison step 4 could not make:\ncotal ps            # NOW compare against ps.before: seat count should match\n```\n\nThe mesh is down from step 2 until step 3 finishes. That is the window. On a split topology there is\nno cut and no backup inside it, so the window is the stop, the install and the restart, nothing more.\n\n## Adding a section for a future release\n\n**Every changeset marked breaking adds a section to this page.** A release that changes what an\noperator must do, in what order, or what stops working, is not finished until the section exists.\n`scripts/upgrade-section-gate.mjs` grades a commit range for this: run it as\n`pnpm upgrade-section-gate --base <ref>` and it reds when the range carries a breaking change and\nadds no new release section. CI runs its self-test and, as a step of the `attribution` job, grades\neach pull request's own range as `HEAD^1..HEAD` over the merge snapshot it checked out. That job is\nthe only context in the branch protection rule set, so a red gate FAILS A REQUIRED CHECK AND BLOCKS\nTHE MERGE. The section is not optional and a reviewer cannot wave it through without an\nadministrator overriding branch protection. Be precise about what the check proves either\nway, because one trusted past its evidence is worse than none. It proves a section for a release\n**was written here**. It cannot prove the section is **correct**, or that it describes the break\nthat actually landed, and it cannot see a breaking change that carries no marker at all. Reviewing\nthe words remains a person's job.\n\n**Mark the break, or the gate cannot see it.** Any one of these is enough, and they are the only\nthings it reads:\n\n- a `!` before the colon in the commit subject, as in `feat(core)!: bind hosted runs to the caller`\n- a `BREAKING CHANGE:` footer in the commit body\n- a changeset in `.changeset/` declaring a `major` bump for any package\n\nThe marker must survive the squash. A `!` that lives only in a commit you squash away is not in the\nrange the gate grades, so put it in the subject that lands on `main`.\n\n**The heading is a `##` and names the release**, like `## From 0.48.2 to 0.49.0`. Both matter, and\nneither is a style preference. Coverage is claimed by a heading, so a heading that names\nno release claims every release and distinguishes none: `## Notes` with a sentence under it would\notherwise satisfy the rule. Naming the release also makes the section the one an operator upgrading\nthat release will search for. Use `###` freely for detail inside a section. Subsections belong to\ntheir release rather than counting as separate coverage.\n\nA section is written for the operator, not for the reviewer. It answers, in this order:\n\n1. What keeps working with no action at all.\n2. What does **not** migrate, and when that becomes visible. Name the log line if there is one.\n3. The order to move components in for a split topology, and why that order.\n4. What the outage window looks like, including what survives it.\n5. What to snapshot before starting.\n6. The commands, end to end.\n\n**Where an answer was not measured, say so in the document rather than guessing.** An operator who\nknows which half of a recommendation is reasoned and which is measured can plan around it; one who\nfinds out afterwards cannot.\n"
     },
     {
       "slug": "watch-a-mesh",
@@ -19804,12 +19818,12 @@ 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 failure the program itself caused\n  inside the scope settles the entry under its own catalog code (`fanOut` without a stable key is\n  `L3021`, kind `runtime`), so a resume reads the same code the live run threw; a plain failure\n  from the handler records the generic `L4000` `scope-fault`. 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. Behind the\n  worker bridge the simulator delivers its next wake only after the thread reports it has reacted\n  to the last one, so a bridged simulation settles a race the same way, also when the dry run's\n  recorder wraps the simulator.\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\nA failed journal entry replays its error, while a pending entry lets the handler recover the\nexternal work it bound before the interruption.\n\nA step that writes to a far side that honors no idempotency key (posting a comment, sending a mail)\nbelongs in `once`. A resume that finds a step inside `once` begun and never settled does not\ndispatch it again: it opens a hold, a checkpoint under a token derived from the step's recorded\nrequest id, whose prompt names that id. Answer it with\n`cotal run answer <run> <step-key> --value <json>`, and the value becomes the step's result. An\nexpired hold fails the step with the catchable L4027. Only `ask` runs inside `once`, so wrap just\nthe step that writes: a host restart while it is in flight costs a settle.\n\n```js\nconst publisher = await spawn(\"publisher\")\nconst res = await once(async () => {\n  return await ask(publisher, { name: \"publish\", schema: { commentId: \"number\" } })\n}, { name: \"publish-360\" })\n```\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\na caller with issued authority. Static authentication issues it to its credentials, and user\nauthentication issues it to the connection a signed-in user's `cotal run` opens. Open meshes can expose\nthe tool but refuse hosted runs. On a user-auth mesh the host's own manager refuses the family by\nname, and a participant manager started with `cotal supervise` hosts the runs of its registered\nowner. A legacy credential without issued authority must be replaced through the current issuance\npath 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`journal` prints an open pause's question under its step. Once a checkpoint or `ask` settles with an\naccepted answer, it instead prints the answer value as JSON, who answered, the artifact when one was\ncited, the recorded time, and the accepted answer id. Expired pauses and ordinary steps print no\nanswer line.\n\nA settled step is never answered twice, so a participant who changes their mind uses `amend`. It\nfiles a new answer beside the accepted one, naming the answer it supersedes, and `journal` prints\neach amendment under the step as an `amended` line, in the order the store committed them. The last\nline is the current position, whatever clock each amender's `at` came from. The pause stays settled\nand the run keeps the answer it acted on. A step that is still open, or that settled with no answer,\nrefuses an amend. The manager records the amender from the credential, as for an answer, and a\nspawned seat may amend only an answer recorded under its own name.\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\"'\ncotal run amend run-3f2a90c41b7e0d5a6c884e19b02df4a1 \"/checkpoint:approve#0\" --value '\"no\"'   # record a changed position\ncotal run migrate run-3f2a90c41b7e0d5a6c884e19b02df4a1 --local --file build-v2.cotal.js   # check an edited program against the journal\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. `cotal run migrate <runId> --local --file <program>` is that check: it\nreplays the run's journal and walks the edited program over it, prints whether the migration is\nadmissible, how many journal rows the walk accounted for, every orphaned step with its verdict and\ncode, and exits 0 on admissible and non-zero on not. It reads only, under the same credential\n`journal` reads on, and the commit side is not reachable yet: the report itself says what a commit\nwould file and that this invocation filed nothing. An answer is recorded under the answerer the\nmanager knows from the caller's credential: a managed agent by its name, anyone else by their\nprincipal. 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 registered remote user-auth manager can host a\nrun through its issuing host. The host resolves a versioned caller against live issuance,\nadmits the run, and signs only the run's fixed driver, mediator and one-shot operator credentials\nfor manager-held nkeys. Renewal checks the activated attempt; the manager holds no signer.\nLocal user-auth runs remain unavailable because 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 logged-in user starts runs on that remote manager with `cotal run start`. The auth callout issues\nthe user's manager connection against the user's actor-ledger row, the CLI reads the generation\nback from the connection's accepted row, and every `run` verb rides the versioned rail. The issuing\nhost admits a run only for the owner who registered the manager, and on every resume and answer it\nchecks that owner and that the caller's issuance is still live. It also watches the resume and\nanswer requests on the broker itself, and issues for one the manager forwards only if it saw that\nrequest, once, and only for the run, endpoint and amendment that request named. A request bound to another manager instance or epoch gets nothing, and so does one whose class or pinned contract is not the one the manager registered. Another user's start, answer or resume is refused, and so is a revoked actor's. [User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path.\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`, hosted or `--local`, reads the marker beside each run record and prints `revoked` for a\nrun that carries one, whatever state the record itself holds, with the revoker and the reason\nunder the table. 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` rows carry the marker as `revoked` (`by` and\n`reason`) or a failed read as `revocationUnreadable`, beside the record's own `state`.\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\nThe driver writes `journalHigh` at activation and again after each journal append, before the\nprogram acts on the entry. A successor whose replay ends below it refuses the run with\n`RunJournalTailTruncated`. That holds for records appended since the last activation too.\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. A drive handles that refusal as a takeover does: the\nreads behind its steps, and the diagnostic for a journal with no run record, replay up to three\ntimes before the refusal is raised. An operator read runs under a takeover minted for that read and\nreports the refusal on its first read.\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`). The migrate check is reachable as\n`cotal run migrate <runId> --local --file <program>`; committing a migration it judged admissible\nis not reachable from any surface yet. 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. A seat belongs to the run\nthat spawned it: when the run completes, it despawns every seat it spawned, including a race\nwinner's and one whose spawn failed while its process stayed up. A spawn marked `onFork: \"adopt\"`\nis the exception: a fork can share that seat and no run can see whether another still uses it, so\nthe seat stays up until you stop it with `cotal stop` once every run sharing it is done. A seat a\nmigration handed to a later spawn follows that spawn's policy, and it stays up if any spawn that held\nit was marked `onFork: \"adopt\"`, because a fork taken before the migration may still share it. In a\nspace with several managers, a despawn counts a seat as already gone only when the manager that\nallocated it says so. A run that\nfails or is released keeps its seats until a resume completes it or you stop them with\n`cotal stop`. Start a seat with `cotal spawn` when it should outlive any run. `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. `events: false` is the workflow form of\n`cotal spawn --no-events`: the seat starts without its AG-UI event plane. A connector that\npublishes none, such as Hermes, needs it, because an omitted `events` arms the plane and the\nmanager refuses that connector at the spawn. A value that is not a boolean is refused at the\nspawn. `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 hosted command that answers it. When that\nliteral command is run inside the managed seat, the CLI reuses the seat's lifecycle credential and\nissued caller identity rather than minting an operator instrument. The command\ndoes not take `--by`: the manager records the authenticated caller as the answerer. A spawned seat's\nbaseline credential carries only the self-targeted `run-answer` row, and the manager accepts it only\nfor the open ask or escalation relayed to that exact incarnation. It cannot answer another seat's\nask, an unrelayed checkpoint, another run, or start and resume commands. 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. The entry also records its deadline and\nthe `onExpiry` the attempt was armed with, which `run journal --json` reports; what an expiry does\nis still decided from the program's source. After a checkpoint or `ask` accepts an\nanswer, the journal prints that accepted answer's recorded value and attribution under the settled\nstep. A checkpoint's comes from its frozen result, and the journal never substitutes another filed\nanswer or invents fields that result does not hold. An `ask`'s result is the value alone, so its line\nis read from the answer record its last attempt's settle named, even when that value is a record with\nfields named like a checkpoint's. Amendments print on their own lines after it.\nAn `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 superseded incarnation is down at once. A\nlapsed one is down only after its presence row has stayed gone for 30 seconds, because a seat whose\nconnector stalls past the row's 6-second TTL, under host load or across a reconnect, renews it under\nthe same incarnation and is still working. The 30 seconds count only across presence reads that\neach end within 6 seconds of the previous one starting, so a slow read or a run of failed reads, which\ncould hide a renewal, starts the count over. A wait that begins after the death resolves once that\nholds, 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, with the\nsame 30-second confirmation for a lapsed row, and is the catchable L4002, and a death the manager\nmarked 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, yield, and caller-bound answer 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. When the spawn also names `cwd`, that manager resolves the\nexisting absolute directory to its canonical host path before accepting the spawn. A missing,\nrelative or non-directory path refuses with no seat and never falls back to the manager workspace.\nOne hosted run may name one placement instance; a program naming several is refused instead of\nwidening one run credential across hosts. Placement is accepted only from an object-literal spawn\noption bag whose `endpoint` and `instanceId` are string literals. A computed option bag, a computed\nplacement field, or a spread in either object refuses at `run-start`. The option argument may be\nabsent, and an object-literal bag without placement is accepted.\nA 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 failure the program itself caused\n  inside the scope settles the entry under its own catalog code (`fanOut` without a stable key is\n  `L3021`, kind `runtime`), so a resume reads the same code the live run threw; a plain failure\n  from the handler records the generic `L4000` `scope-fault`. 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. Behind the\n  worker bridge the simulator delivers its next wake only after the thread reports it has reacted\n  to the last one, so a bridged simulation settles a race the same way, also when the dry run's\n  recorder wraps the simulator.\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\nA failed journal entry replays its error, while a pending entry lets the handler recover the\nexternal work it bound before the interruption.\n\nA step that writes to a far side that honors no idempotency key (posting a comment, sending a mail)\nbelongs in `once`. A resume that finds a step inside `once` begun and never settled does not\ndispatch it again: it opens a hold, a checkpoint under a token derived from the step's recorded\nrequest id, whose prompt names that id. Answer it with\n`cotal run answer <run> <step-key> --value <json>`, and the value becomes the step's result. An\nexpired hold fails the step with the catchable L4027. Only `ask` runs inside `once`, so wrap just\nthe step that writes: a host restart while it is in flight costs a settle.\n\n```js\nconst publisher = await spawn(\"publisher\")\nconst res = await once(async () => {\n  return await ask(publisher, { name: \"publish\", schema: { commentId: \"number\" } })\n}, { name: \"publish-360\" })\n```\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\na caller with issued authority. Static authentication issues it to its credentials, and user\nauthentication issues it to the connection a signed-in user's `cotal run` opens. Open meshes can expose\nthe tool but refuse hosted runs. On a user-auth mesh the host's own manager refuses the family by\nname, and a participant manager started with `cotal supervise` hosts the runs of its registered\nowner. A legacy credential without issued authority must be replaced through the current issuance\npath 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`journal` prints an open pause's question under its step. Once a checkpoint or `ask` settles with an\naccepted answer, it instead prints the answer value as JSON, who answered, the artifact when one was\ncited, the recorded time, and the accepted answer id. Expired pauses and ordinary steps print no\nanswer line.\n\nA settled step is never answered twice, so a participant who changes their mind uses `amend`. It\nfiles a new answer beside the accepted one, naming the answer it supersedes, and `journal` prints\neach amendment under the step as an `amended` line, in the order the store committed them. The last\nline is the current position, whatever clock each amender's `at` came from. The pause stays settled\nand the run keeps the answer it acted on. A step that is still open, or that settled with no answer,\nrefuses an amend. The manager records the amender from the credential, as for an answer, and a\nspawned seat may amend only an answer recorded under its own name.\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\"'\ncotal run amend run-3f2a90c41b7e0d5a6c884e19b02df4a1 \"/checkpoint:approve#0\" --value '\"no\"'   # record a changed position\ncotal run migrate run-3f2a90c41b7e0d5a6c884e19b02df4a1 --local --file build-v2.cotal.js   # check an edited program against the journal\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. `cotal run migrate <runId> --local --file <program>` is that check: it\nreplays the run's journal and walks the edited program over it, prints whether the migration is\nadmissible, how many journal rows the walk accounted for, every orphaned step with its verdict and\ncode, and exits 0 on admissible and non-zero on not. It reads only, under the same credential\n`journal` reads on, and the commit side is not reachable yet: the report itself says what a commit\nwould file and that this invocation filed nothing. An answer is recorded under the answerer the\nmanager knows from the caller's credential: a managed agent by its name, anyone else by their\nprincipal. 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 registered remote user-auth manager can host a\nrun through its issuing host. The host resolves a versioned caller against live issuance,\nadmits the run, and signs only the run's fixed driver, mediator and one-shot operator credentials\nfor manager-held nkeys. Renewal checks the activated attempt; the manager holds no signer.\nLocal user-auth runs remain unavailable because 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 logged-in user starts runs on that remote manager with `cotal run start`. The auth callout issues\nthe user's manager connection against the user's actor-ledger row, the CLI reads the generation\nback from the connection's accepted row, and every `run` verb rides the versioned rail. The issuing\nhost admits a run only for the owner who registered the manager, and on every resume and answer it\nchecks that owner and that the caller's issuance is still live. It also watches the resume and\nanswer requests on the broker itself, and issues for one the manager forwards only if it saw that\nrequest, once, and only for the run, endpoint and amendment that request named. A request bound to another manager instance or epoch gets nothing, and so does one whose class or pinned contract is not the one the manager registered. Another user's start, answer or resume is refused, and so is a revoked actor's. [User-auth run start](https://github.com/Cotal-AI/Cotal/blob/main/docs/design/user-auth-run-start.md)\nrecords the path.\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`, hosted or `--local`, reads the marker beside each run record and prints `revoked` for a\nrun that carries one, whatever state the record itself holds, with the revoker and the reason\nunder the table. 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` rows carry the marker as `revoked` (`by` and\n`reason`) or a failed read as `revocationUnreadable`, beside the record's own `state`.\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\nThe driver writes `journalHigh` at activation and again after each journal append, before the\nprogram acts on the entry. A successor whose replay ends below it refuses the run with\n`RunJournalTailTruncated`. That holds for records appended since the last activation too.\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. A drive handles that refusal as a takeover does: the\nreads behind its steps, and the diagnostic for a journal with no run record, replay up to three\ntimes before the refusal is raised. An operator read runs under a takeover minted for that read and\nreports the refusal on its first read.\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`). The migrate check is reachable as\n`cotal run migrate <runId> --local --file <program>`; committing a migration it judged admissible\nis not reachable from any surface yet. 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. A seat belongs to the run\nthat spawned it: when the run completes, it despawns every seat it spawned, including a race\nwinner's and one whose spawn failed while its process stayed up. A spawn marked `onFork: \"adopt\"`\nis the exception: a fork can share that seat and no run can see whether another still uses it, so\nthe seat stays up until you stop it with `cotal stop` once every run sharing it is done. A seat a\nmigration handed to a later spawn follows that spawn's policy, and it stays up if any spawn that held\nit was marked `onFork: \"adopt\"`, because a fork taken before the migration may still share it. In a\nspace with several managers, a despawn counts a seat as already gone only when the manager that\nallocated it says so. A run that\nfails or is released keeps its seats until a resume completes it or you stop them with\n`cotal stop`. Start a seat with `cotal spawn` when it should outlive any run. `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. `events: false` is the workflow form of\n`cotal spawn --no-events`: the seat starts without its AG-UI event plane. A connector that\npublishes none, such as Hermes, needs it, because an omitted `events` arms the plane and the\nmanager refuses that connector at the spawn. A value that is not a boolean is refused at the\nspawn. `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 hosted command that answers it. When that\nliteral command is run inside the managed seat, the CLI reuses the seat's lifecycle credential and\nissued caller identity rather than minting an operator instrument. The command\ndoes not take `--by`: the manager records the authenticated caller as the answerer. A spawned seat's\nbaseline credential carries only the self-targeted `run-answer` row, and the manager accepts it only\nfor the open ask or escalation relayed to that exact incarnation. It cannot answer another seat's\nask, an unrelayed checkpoint, another run, or start and resume commands. 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. The entry also records its deadline and\nthe `onExpiry` the attempt was armed with, which `run journal --json` reports; what an expiry does\nis still decided from the program's source. After a checkpoint or `ask` accepts an\nanswer, the journal prints that accepted answer's recorded value and attribution under the settled\nstep. A checkpoint's comes from its frozen result, and the journal never substitutes another filed\nanswer or invents fields that result does not hold. An `ask`'s result is the value alone, so its line\nis read from the answer record its last attempt's settle named, even when that value is a record with\nfields named like a checkpoint's. Amendments print on their own lines after it.\nAn `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 superseded incarnation is down at once. A\nlapsed one is down only after its presence row has stayed gone for 30 seconds, because a seat whose\nconnector stalls past the row's 6-second TTL, under host load or across a reconnect, renews it under\nthe same incarnation and is still working. The 30 seconds count only across presence reads that\neach end within 6 seconds of the previous one starting, so a slow read or a run of failed reads, which\ncould hide a renewal, starts the count over. A wait that begins after the death resolves once that\nholds, 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, with the\nsame 30-second confirmation for a lapsed row, and is the catchable L4002, and a death the manager\nmarked 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, yield, and caller-bound answer 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. When the spawn also names `cwd`, that manager resolves the\nexisting absolute directory to its canonical host path before accepting the spawn. A missing,\nrelative or non-directory path refuses with no seat and never falls back to the manager workspace.\nOne hosted run may name one placement instance; a program naming several is refused instead of\nwidening one run credential across hosts. Placement is accepted only from an object-literal spawn\noption bag whose `endpoint` and `instanceId` are string literals. A computed option bag, a computed\nplacement field, or a spread in either object refuses at `run-start`. The option argument may be\nabsent, and an object-literal bag without placement is accepted.\nA 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. On either\nengine the driver bounds an effect's `ok` result at the broker's `max_payload` less 4096 bytes: a\nlarger result is refused ahead of the settling append (**L5006**), the step stays pending, and the\nrun is released. The driver serves a declared set of versions, and a record whose version it does\nnot serve is refused by name (**L5023**) with the run left untouched, instead of being replayed by\nwhichever engine happens to be present. Records do not cross between versions in either\ndirection; the repair is to resume 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": {
     "title": "Cotal Wire Specification",
-    "body": "# Cotal Wire Specification\n\n> **Status:** Draft, v0.5 (pre-1.0). This document is the normative wire contract. Libraries\n> (including the reference TypeScript implementation) are thin clients over it; where a\n> client disagrees with this document, this document wins.\n>\n> **Layered authority.** Message *shapes* are defined by the machine-readable schema,\n> [`spec/cotal.schema.json`](spec/cotal.schema.json) (\xA75); this document's prose defines\n> *semantics*: routing, delivery guarantees, presence, authorization, and conformance. For\n> the reference implementation's operator surfaces (the CLI, the `cotal_*` tools), see the\n> [Reference docs](docs/README.md#reference); those describe the TypeScript implementation,\n> not this contract.\n>\n> **Editors:** Cotal maintainers. **Last updated:** 2026-09-22. Changes are tracked in\n> [Appendix D](#appendix-d-change-log); versioning rules are \xA711.\n>\n> **v0.5 binding revision: workflow runs.** A deployment MAY host **durable workflow runs**: programs\n> in the Cotal workflow language ([`spec/cotal-lang.md`](spec/cotal-lang.md), normative and\n> incorporated by reference) whose every effect is recorded in a per-run **step journal** so a run\n> resumes on any host by re-execution against its journal (\xA714). The revision adds one per-space\n> stream (`WFJ_<space>`, one subject per run, an append-only journal fenced by the run's own subject\n> sequence), four core record kinds (`run`, `answer`, `notice`, `migration`), a per-run driver grant\n> family, and the language reference; it changes no existing kind, subject, grant row or shipped\n> datum, so it is **additive** under \xA711: a v0.4 participant that ignores \xA714 conforms to v0.4\n> unchanged, and the advertised `protocolVersion` targets `0.5` once the v0.4 migration completes and\n> the \xA714 plane is served. Language semantics carry their own version (`languageVersion`, pinned on\n> every run record) and move independently of the wire version.\n>\n> **v0.3 binding revision: owner+actor identity.** An instance's wire identity moves from a single\n> id (the connection nkey, used as the sender token everywhere) to a two-token **principal**\n> `(owner, actor)` (\xA72): the human/account owner and the agent actor become distinct routing tokens,\n> so every subject carries the sender as `<owner>.<actor>` (\xA73), and grants, durables, presence, and\n> `from.id` re-key onto the principal (\xA76, \xA78, \xA79). The connection nkey survives only as the transport\n> credential, keying the per-connection reply inbox `_INBOX_<connId>` (\xA72, \xA710); the wire identity and\n> the connection credential are now distinct. Cross-owner **and** same-owner cross-actor forge/read\n> isolation is a normative confinement property (\xA79). `parseSubject` splits the tokens; a well-formed\n> split is necessary but not sufficient: a reader additionally rejects a non-principal owner token\n> (e.g. an old-shape alias carrying a raw nkey) at the surfacing boundary (\xA73, \xA79). The owner-token\n> *format* (`u_` + 26 base32-lower) is normative; its *derivation* from an owner's identity (login \u2192\n> auth callout, or another identity adapter) is a pluggable edge, not fixed by this contract. This\n> supersedes the v0.2/early-v0.3 single-id grammar. As with the live-delivery revision, the advertised\n> wire `protocolVersion` (\xA76, \xA711) is the migration's normative target, not a claim that every surface\n> has cut over.\n>\n> **v0.4 binding revision: endpoint control surface.** Structured command traffic moves from the v0\n> `ctl` control rail to one standardized, typed, discoverable endpoint surface (\xA713): class +\n> instance + scatter rails with per-command broker enforcement, a versioned envelope, three\n> delivery contracts (ephemeral / record / journal), normative composites (action, checkpoint,\n> guard, capability handle, session), content-addressed contracts with governed traits, and\n> lifecycle identity (\xA713.1) extending \xA72/\xA76/\xA78. This is an intentional **hard cut** (\xA711,\n> \xA713.11): the v0 control grammar, envelope, and authority tiers are deleted, not dual-served.\n> The advertised `protocolVersion` targets `0.4` at the completion of this revision's migration;\n> `1.0` remains reserved as a later stability declaration, not part of this revision.\n>\n> **v0.3 binding revision: channel live delivery.** Channel *live* delivery moves from a single\n> mediated JetStream live-tail durable (`chat_<id>`) to native core-NATS subscriptions bounded by\n> `sub.allow`, with durability provided by an explicit per-channel `live`/`durable` delivery class\n> (\xA74, \xA77, \xA78). Join/leave becomes a direct subscribe/unsubscribe with no privileged mediation,\n> and channel membership moves off consumer topology to a privileged-written registry (\xA77). This\n> supersedes the v0.2 single-durable live-tail. The reference implementation migrates additively\n> (the legacy durable and the new core-sub path coexist behind `id` dedup until the legacy path is\n> removed), but that migration path is not itself normative. The advertised wire `protocolVersion`\n> (\xA76, \xA711) stays `0.2` until the core-sub behaviour ships; this revision is the normative target the\n> migration converges to, and the additive `deliveryClass` field is backward-compatible meanwhile.\n\nThe key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, MAY, and OPTIONAL in\nthis document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)\nand [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174).\n\nSections 3 to 7 define the transport-agnostic Cotal contract. Sections 8 to 10 define\nthe NATS + JetStream binding (v0). A conformant deployment implements one binding; the\nNATS binding is the only one defined today. External specifications this document relies on\nare listed in Appendix C.\n\n---\n\n## 1. Scope and terminology\n\nCotal is a wire interface for software, especially AI agents, to coordinate in real time\nas lateral peers in a shared pub/sub space, not as nodes in an orchestrator tree.\n\n- **Space**: an isolated coordination context. One space is one tenant boundary; messages\n  in one space are not visible in another. NATS binding: one space = one account.\n- **Instance**: a connected participant, identified by a stable **instance id**. Also called\n  an endpoint.\n- **Agent node**: an instance whose `kind` is `agent`, versus a plain `endpoint` such as an\n  observer, logger, or dashboard.\n- **Peer**: any other instance in the same space.\n- **Channel**: a named multicast topic within a space, dotted and hierarchical.\n- **Service**: an anycast role reached by name (`svc`, \xA74).\n- **Endpoint (control surface)**: a daemon that registers a service identity, publishes\n  typed contracts, and serves commands on the endpoint rails (\xA713).\n- **Broker**: the message router for a space. v0 assumes a single trusted broker.\n- **Delivery message**: a multicast, unicast, or anycast `CotalMessage`.\n- **Endpoint request**: a typed request/reply command addressed to an endpoint class or\n  instance on the `ep` rails (\xA713). The v0 `ctl` control rail is deleted (\xA713.11).\n\n---\n\n## 2. Identity\n\nAn instance's wire identity is a **principal** = a pair of routing tokens `(owner, actor)`:\n\n- **`owner`**: the account that owns the instance: the human (or organization) an agent acts on\n  behalf of. In an authenticated deployment it is a derived **owner token** (`u_` followed by 26\n  base32-lower characters), a namespaced, nkey-disjoint token deterministically derived from the\n  owner's stable identity (e.g. an IdP subject) by the deployment's identity adapter; the wire\n  contract fixes the token *format*, not the derivation mechanism, which is a pluggable edge. In open\n  dev mode the owner is the literal `local`.\n- **`actor`**: the instance's own handle within that owner (its agent id). Distinct actors under one\n  owner are distinct principals and are confined from one another (\xA79), so one human's two agents\n  cannot forge or read as each other.\n\nEach token is sanitized to `[A-Za-z0-9_]` (see \xA73) with `-` additionally reserved as the form\nseparator, so a principal has two unambiguous serializations: the **dot-form** `<owner>.<actor>` and\nthe **dash-form** `<owner>-<actor>`. The same principal MUST appear identically as: the\n`AgentCard.id` (\xA76, dot-form), the sender tokens in subjects (\xA73), the message `from.id` (\xA75,\ndot-form), the presence key (\xA76, dot-form), and the per-instance durable names (\xA78, dash-form).\n\n**The principal is distinct from the connection credential.** In the authenticated NATS binding the\nconnecting user is still an Ed25519 nkey (base32, 56 chars, prefix `U`, e.g. `UAQG...`), stable for\nthe lifetime of the connection, but it is **not** the wire identity. The nkey authenticates the\ntransport and scopes only the per-connection reply inbox `_INBOX_<connId>.>` (\xA710); the principal\nthat keys every subject, grant, and durable is carried by the minted grant, not by the nkey. This\nseparation is what lets a login (\xA79) mint a fresh connection whose nkey the client never sees while\nthe principal stays stable across reconnects.\n\n- A client that authenticates with a static credential MUST adopt the principal that credential's\n  grant names; if a principal is also set explicitly (via the card) it MUST match, else the client\n  MUST fail before publish.\n- A client that authenticates through the auth callout (user mode, \xA79) cannot know its connection\n  nkey before connecting, so it chooses its own reply-inbox nonce (`connId`) and derives its\n  principal from its bearer; the broker's minted grant, not the client's self-read, is the\n  boundary.\n- Open dev mode MAY use `local` as the owner and an opaque stable actor, but open mode is outside\n  the security claims in \xA79 and is not a conformant authenticated deployment.\n\nFuture binding, not v0: portable `did:key` identity plus signed envelopes so authenticity\nsurvives an untrusted relay. See the threat model in [docs/security.md](docs/security.md).\n\n---\n\n## 3. Subject layout\n\nEvery wire subject is rooted at `cotal.<space>`. `<space>` and every routing token are\nsanitized: any character outside `[A-Za-z0-9_-]` maps to `_`. Sanitization is lossy; tokens\nMUST NOT be decoded back into display names.\n\nThe **sender** of every delivery is a principal (\xA72), carried as **two adjacent tokens**\n`<owner>.<actor>`. Routed kinds (`inst`) also carry the recipient principal as two tokens.\n\n| Purpose | Subject | Sender tokens | Delivery |\n| --- | --- | --- | --- |\n| Multicast | `cotal.<space>.chat.<owner>.<actor>.<channel...>` | 3\u20134 | \xA74 multicast |\n| Unicast | `cotal.<space>.inst.<recipOwner>.<recipActor>.<sndOwner>.<sndActor>` | 5\u20136 | \xA74 unicast |\n| Anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` | 4\u20135 | \xA74 anycast |\n| Endpoint rails | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026`, `cotal.<space>.ep<c\\|e\\|f\\|j\\|r\\|t\\|w\\|s>.\u2026` | see \xA713.2 | \xA713 control surface |\n| Plane liveness | `cotal.<space>.live.<plane>.<owner>.<actor>` | 4-5 | \xA76.1 request/reply |\n| Trace | `cotal.<space>.trace.<instance>` | n/a | reserved |\n\nToken indexing is zero-based on `subject.split(\".\")`: `cotal` = 0, `<space>` = 1,\n`<kind>` = 2. The sender principal is recovered as the dot-form `<owner>.<actor>` (= the message\n`from.id`, \xA75), so a guard comparing `from.id` to the subject sender uses one value.\n\n**Two-token sender, and its asymmetry.** A reader MUST locate the sender by kind:\n\n- `chat`: sender owner at token 3, actor at token 4; the channel is everything after, tokens 5+,\n  so it may be hierarchical (`team.backend`).\n- `svc`: route target at token 3; sender owner at token 4, actor at token 5.\n- `ep`: per-mode arities with the caller as the trailing identity tokens; \xA713.2 defines them.\n- `inst`: recipient owner+actor at tokens 3\u20134; sender owner+actor at tokens 5\u20136.\n\nThe two-token sender is what lets a native publish grant **forge-lock** the sender suffix (e.g.\n`inst.*.*.<myOwner>.<myActor>` permits a DM to anyone but only *as me*), so the broker enforces\nsender authenticity and a receiver need not re-verify a payload claim. A subject that does not match\none of these shapes (wrong prefix or wrong per-kind arity) MUST be treated as having no sender and\nMUST NOT be read as a delivery. `parseSubject` **splits only**: it recovers the tokens but does not\nvalidate that `<owner>` is a well-formed owner token; trust comes from the broker's forge-locked\ngrant, and a reader that surfaces content additionally rejects a non-principal owner token at the\nsurfacing boundary (\xA79). Reference implementation: `parseSubject` in\n`packages/core/src/subjects.ts`.\n\n**Channel tokens.** A channel is dotted; each segment is sanitized. The literal wildcards\n`*` and `>` are preserved only as whole segments for subscription and allow-list patterns;\n`>` is valid only as the final segment. A publish target MUST be concrete, with no `*` or\n`>`; a subscription MAY be wildcard. A channel is at most 4096 characters in total\n(`MAX_CHANNEL_LENGTH`): every grant line a channel mints rides the minted credential's\nCONNECT line (\xA713.9), so an unbounded channel is an unbounded connect.\n\n**Reserved prefixes.** Application messages MUST NOT use subjects beginning with `$JS.`,\n`$KV.`, `$SYS.`, `$O.`, or `_INBOX.`. (`$O.` is the Object Store data/meta subject prefix\nper ADR-20, `$O.<bucket>.C.>` / `$O.<bucket>.M.>`; `OBJ_<bucket>` is a stream NAME, not a\nsubject prefix.)\n\n---\n\n## 4. Delivery modes\n\n| Mode | Routing field | Semantics |\n| --- | --- | --- |\n| multicast | `channel` | delivered to every subscriber of the channel |\n| unicast | `to` | delivered to the named instance's inbox |\n| anycast | `toService` | delivered to one consumer of the named role |\n\nExactly one of `channel`, `to`, or `toService` MUST be set on a `CotalMessage` (\xA75).\n\n**Authenticated delivery kind.** A receiver MUST derive \"how was this addressed to me\"\nfrom the delivering subject kind (`chat` -> `channel`, `inst` -> `dm`, `svc` ->\n`anycast`), not from payload routing fields, which are advisory. (\"Delivery kind\", the\naddressing axis, is distinct from a channel's `live`/`durable` **delivery class**, \xA77.) A peer can put your id in\npayload `to`, but cannot publish on your private unicast subject. Reference:\n`MessageMeta.kind`.\n\n**Delivery guarantee: `live` and `durable` classes.** Channel delivery has two classes, fixed\nper channel and wire-observable (\xA77); the guarantee is defined here, its NATS realization is the\nbinding in \xA78. A receiver MUST derive its effective class from channel config (\xA77), not from\nper-message metadata (`MessageMeta` need not carry it); it MUST NOT assume one class.\n\n- **`live`** is native broker-subscription delivery and is **at-most-once**: a message reaches\n  only the instances subscribed to the channel at publish time. An instance that is disconnected,\n  busy, or not yet joined does not receive that message live and has no claim to the live copy\n  later. There is no per-subscriber redelivery of the live copy.\n- **`durable`** is `live` plus a per-subscriber durable backstop and is **at-least-once for\n  current members within retention**: the message is also retained for each member and delivered on\n  that member's next connection or turn, remaining pending until acked. A crash or `ack_wait` expiry\n  redelivers the durable copy. At-least-once is bounded by the channel's retention / `replayWindow`\n  (\xA77): a message evicted by retention before ack may be lost; the guarantee is not unbounded.\n\nUnicast (`to`) and anycast (`toService`) are at-least-once via their own DM/TASK consumers (\xA78);\nthey have no channel membership and are not subject to the per-channel delivery-class mechanism. An\n`@mention` (\xA75) on a `live` channel additionally writes a durable copy to each mentioned target\n**authorized to read that channel** (its `allowSubscribe` covers the channel), so an authorized but\noffline target still receives it; an `@mention` MUST NOT deliver channel content to a target outside\nits read ACL. Durable mention routing resolves each lowercased name to a unique current instance id\nfrom presence at publish time; an ambiguous (multiple live matches) or unresolvable name yields no\ndurable copy, and authorization is checked against the resolved id's current `allowSubscribe`. A\ntarget authorized for a channel is **mention-reachable** there whether or not it is currently joined; this is intentional (an `@mention` can pull an authorized peer in) and is distinct\nfrom membership; a client SHOULD distinguish \"joined\" (actively subscribed) from \"readable /\nmention-reachable\" (in `allowSubscribe`) so an unjoined channel is not treated as \"cannot reach me\nhere.\"\n\nA message delivered both live and durable is **one logical delivery**: receivers MUST deduplicate\nby `id` across classes (\xA78); the durable copy owns ack/commit; and a previously seen `id` MUST NOT\nbe treated as authorization for a later durable copy (for example one that arrives after a leave).\nReceiver deduplication MUST NOT use the empty string as a key. Two received messages MUST NOT be\ntreated as one logical delivery solely because both carry `id: \"\"`; each otherwise-deliverable\nmessage remains independently deliverable. Because live, backfill, and durable copies with\n`id: \"\"` cannot be correlated by wire identity, an at-least-once path may surface the same logical\nmessage more than once. The existing \xA75 obligation for publishers to supply a unique string id is\nunchanged. An absent or non-string id remains a malformed envelope.\nReceivers MUST tolerate the `live` gap and rely on the `durable` backstop for catch-up on\n`durable` channels. Malformed JSON, spoofed sender payloads, and unparseable delivery subjects are\npermanent anomalies and MUST be terminated, not retried.\n\n**Ordering.** Cotal does not define global ordering across modes, channels, or consumers.\nImplementations MUST NOT depend on cross-subject ordering. Per-consumer delivery is ordered\nby the backing stream except where redelivery or explicit backfill interleaves older\nmessages.\n\n---\n\n## 5. Envelopes\n\nDelivery messages are UTF-8 JSON objects with this shape (`CotalMessage`):\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `id` | string | MUST | unique message id; NATS binding also uses it as `Nats-Msg-Id` |\n| `ts` | number | MUST | epoch ms |\n| `space` | string | MUST | space name |\n| `from` | `EndpointRef` | MUST | `{ id, name, role? }` |\n| `channel` | string | one-of | multicast target |\n| `to` | string | one-of | unicast target instance id |\n| `toService` | string | one-of | anycast target role |\n| `mentions` | string[] | MAY | lowercased peer names; wakes the mentioned peer. On a `live` channel it also routes a durable copy to each mentioned target authorized to read that channel (\xA74); it never delivers content outside the target's read ACL and is not a routing substitute for `channel`/`to` |\n| `parts` | `Part[]` | MUST | content |\n| `replyTo` | string | MAY | id of the message replied to |\n| `contextId` | string | MAY | thread/conversation correlation id |\n\n`Part` is one of the three core shapes, or an extension object whose `kind` is namespaced\nas described in \xA711:\n\n- `{ \"kind\": \"text\", \"text\": string }`\n- `{ \"kind\": \"data\", \"data\": <any JSON value> }`\n- `{ \"kind\": \"artifact\", \"name\": string, \"mediaType\": string, \"digest\": string, \"size\": number }`\n- `{ \"kind\": \"<reverse-DNS extension kind>\", ... }`\n\nA `data` part's `data` MUST be a JSON value at every depth; a publisher MUST refuse the part\nrather than serialize a value JSON cannot represent, naming the offending member's path (a\ntop-level `undefined` serializes to a keyless `{\"kind\":\"data\"}` object, and `NaN`, a `Date`,\nor a class instance would be silently rewritten rather than refused).\n\nAn `artifact` part REFERENCES bytes held outside the message. `digest` MUST be\n`sha256:<lowercase hex>` over the raw bytes and is the artifact's identity; the part carries no\nlocation, so resolution is the receiver's. `name`, `mediaType`, and `size` are the publisher's\nclaims: a receiver MUST NOT allocate from `size`, and MUST verify fetched bytes against `digest`\nbefore use.\n\n`EndpointRef` is `{ \"id\": string, \"name\": string, \"role\"?: string }`.\n\nOn receive, a client MUST verify `from.id` equals the subject sender (\xA73). On mismatch, a\nmissing `from`, or an unparseable delivery subject, the message MUST be rejected and never\nredelivered.\n\nEndpoint requests and replies (the control surface) use the versioned typed envelope of\n\xA713.3 (`EndpointRequest`/`EndpointReply`); they are not Cotal delivery messages. The v0\n`ControlRequest`/`ControlReply` shapes are deleted (\xA713.11).\n\nReceivers MUST ignore unknown object fields. Unknown conformant extension `Part.kind` values\nMUST be ignored unless the receiver explicitly supports that extension. Bare unrecognized\ncore-kind values are not conformant. Messages MUST fit the broker's configured maximum payload;\nbytes that do not fit move out of the message and are referenced by an `artifact` part (above).\nThe transport that serves those bytes is not defined by this document.\n\n**Schema.** The JSON Schema (draft-07) at\n[`spec/cotal.schema.json`](spec/cotal.schema.json) is **authoritative for message shapes**:\na conformant delivery message MUST validate against it, and where this document's field\ntables and the schema diverge on a shape, the schema wins. Delivery *semantics* (routing,\nguarantees, rejection) are defined by this document's prose. The schema is generated from\nthe reference source, [`packages/core/src/types.ts`](packages/core/src/types.ts)\n(`pnpm gen:schema`), and committed; the published copy lives at\n`https://docs.cotal.ai/cotal.schema.json`.\n\n**Rejection reasons.** The three permanent anomalies in \xA74 are terminated, never redelivered.\nThese reason tokens are advisory (for logs and error surfaces); the action is uniform:\n\n| Reason | Trigger |\n| --- | --- |\n| `malformed-subject` | the delivery subject does not parse (\xA73) |\n| `sender-mismatch` | `from` is missing, or `from.id` does not equal the subject sender (\xA75) |\n| `malformed-json` | the payload is not valid UTF-8 JSON |\n\n---\n\n## 6. Presence and discovery\n\nPresence is a per-space directory keyed by instance id. NATS binding: JetStream KV bucket\n`cotal_presence_<space>` (\xA78).\n\n`Presence`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `card` | `AgentCard` | MUST | identity record |\n| `status` | `PresenceStatus` | MUST | `idle`, `waiting`, `working`, or `offline` |\n| `condition` | `PresenceCondition` | MAY | harness-reported structured condition. Missing means nothing was reported. A connector relays the harness signal and MUST NOT infer a condition itself |\n| `environment` | string | MAY | opaque reference whose meaning belongs to the provider that issued it. Core MUST NOT parse it |\n| `activity` | string | MAY | freeform current activity |\n| `statusSince` | number | MAY | epoch ms when the instance entered its current `status` and `activity`. A change to either moves it; a heartbeat or a repeated report does not, so `ts` dates liveness and `statusSince` dates the report. An offline record MUST NOT carry it: an observer that derives `offline` from a stale `ts` does not know when the peer left |\n| `activitySince` | number | MAY | epoch ms when the current `activity` was set. A status change or a heartbeat does not move it, so an activity left behind while the status flips every turn still reads as old |\n| `activeAt` | number | MAY | epoch ms of the last work progress the harness reported, such as a token or a tool call. Missing means the connector reports none. `ts` is the heartbeat, so a live instance whose turn stopped advancing keeps a fresh `ts` and an old `activeAt`. A connector relays the harness's events and carries the value on its next heartbeat |\n| `attention` | `AttentionMode` | MAY | global attention mode: `open` \\| `dnd` \\| `focus`. Advisory observability; `open`/absent \u21D2 receives everything. Reset: `open` published on `SessionStart`, removed on the offline sweep |\n| `lifecycleUid` | string | MUST in auth mode from v0.4 | the current managed-lifecycle UID (\xA713.1); distinguishes a live instance from a same-name successor. Advisory for display; authority checks use the trusted lifecycle mapping, not presence |\n| `channelModes` | `Record<string, ChannelMode>` | MAY | per-channel attention overrides (`ChannelMode` = `quiet` \\| `muted`), keyed by concrete channel name. Advisory, **not** access control (the broker still authorises and delivers); a receive-side preference, reset on restart |\n| `ts` | number | MUST | epoch ms of last heartbeat |\n\n`AgentCard`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `id` | string | MUST | instance id (\xA72) |\n| `name` | string | MUST | display name; at most 128 characters (`MAX_NAME_LENGTH`, refused at the shared validator; an unbounded name rides the CONNECT line until the broker drops it silently, \xA713.9) |\n| `kind` | `agent` or `endpoint` | MUST | participation class |\n| `role` | string | MAY | service role |\n| `description` | string | MAY | one-line summary |\n| `tags` | string[] | MAY | capability tags |\n| `skills` | `AgentSkill[]` | MAY | `{ id, name, description? }` |\n| `meta` | object | MAY | free-form display metadata. Reserved flat string keys are `connector` (host harness name), `model` (pinned model), `provider` (effective provider serving the model, connector-reported), `host` (self-reported machine), `cwd`, `repo`, `branch`, `head`, `sessionKind`, and `sessionId`. All are advisory only |\n| `protocolVersion` | string | MUST from v0.4 | wire version spoken (\xA711); `\"0.4\"` for this revision. Advertisement is the marker at the v0.4 reachability boundary (\xA713.11): a participant that omits it is pre-0.4 (omission means the pre-0.4 line, where the field was optional) and MUST NOT be addressed on the `ep` rails. A change signal, not negotiation |\n\nAn instance MUST refresh its own presence entry on the heartbeat interval, default 2000 ms.\nThe liveness window defaults to 6000 ms. A peer whose `ts` is older than the liveness window\nis considered `offline`.\n\nLive clients MUST NOT heartbeat as `offline`. A graceful disconnect MAY publish one final\n`offline` presence record. Observers MUST also derive `offline` from stale timestamps and\nfrom KV delete/purge events. Offline peers MAY remain in local rosters for observability.\nAn instance MUST write only its own presence key, and the key MUST equal `card.id`.\nReaders MUST drop a record whose `card.id` differs from its KV key, whose `card.name` or\n`status` does not have the type given above, or whose `ts` is not a finite number, and SHOULD\nreport the rejection on their recoverable diagnostic path. A reader that kept a record whose\n`ts` is missing or text such as `\"nope\"` could not age it past the liveness window, so it would\nshow its peer live after the key expired.\n\n`PresenceCondition`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `code` | `PresenceConditionCode` | MUST | `rate_limit` \\| `overloaded` \\| `auth` \\| `billing` \\| `budget` \\| `context` \\| `model` \\| `request` \\| `server` \\| `retrying` \\| `approval` \\| `input` \\| `failed` |\n| `source` | string | MAY | harness-native value, relayed verbatim |\n| `message` | string | MAY | free text from the harness |\n| `since` | number | MAY | epoch ms when the condition began |\n\n### 6.1 Plane liveness\n\nA credentialed peer MAY ask whether the manager plane or the delivery plane has a bound\nresponder in its space. The question is presence only. It does not read either lease bucket,\nand the peer does not need to own the plane it asks about.\n\n**Planes.** The set of planes is closed: `manager` and `delivery`. A client MUST refuse any\nother plane before it publishes anything.\n\n**Subjects.**\n\n| Purpose | Subject |\n| --- | --- |\n| Request | `cotal.<space>.live.<plane>.<owner>.<actor>` |\n| Reply | `cotal.<space>.live.<plane>.<owner>.<actor>.reply.<nonce>` |\n| Responder serve filter | `cotal.<space>.live.<plane>.*.*`, queue group `live.<plane>` |\n| Responder reply grant | `cotal.<space>.live.<plane>.*.*.reply.>` |\n\n`<owner>.<actor>` is the asking principal (\xA72). The plane rides the subject so a credential can\nbe scoped to one plane by the broker. A `live` subject is not a delivery: `parseSubject`\nrecovers no sender from it, and a reader MUST NOT treat it as one.\n\n**Request.** The body is empty. The caller names a reply subject under its own request subject,\n`<request>.reply.<nonce>`, with a fresh nonce per probe. A responder MUST drop, without\nanswering, any request whose reply target is absent or is not under `<request subject>.reply.`.\nIt SHOULD report that drop on its recoverable diagnostic path. It MUST NOT report it on a\nchannel that can end the process, and it keeps serving.\n\n**Reply.** `LivenessAnswer`, JSON:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `plane` | `manager` \\| `delivery` | MUST | the plane asked about; a caller MUST reject a reply whose `plane` differs from the plane it asked |\n| `responder` | `ResponderState` | MUST | `bound` \\| `unbound` \\| `stale` \\| `unknown` |\n| `instance` | string | MAY | an opaque token naming the responder that answered. Non-empty when present |\n\nA responder MUST put nothing else in the reply. In particular it carries no lease holder, pid,\nworkspace path, instance id, runtime or roster.\n\n`instance` is minted fresh each time a responder binds and is derived from nothing. It is not\nthe endpoint's principal, the lease row's `instanceId`, a pid, a host or a path. It lets a\ncaller that probes more than once tell two responders apart from one responder whose state\nchanged. The queue group hands one probe to one member, so a single answer samples one\nresponder and cannot report a split across instances.\n\n**Responder verdicts.** A responder grades only itself:\n\n- manager: `bound` while its v0.4 service endpoint (\xA713) is serving, otherwise `unbound`. A\n  closed service connection is not serving, including while the manager re-dials it. A\n  disconnected one is not serving either, including while the client reconnects it.\n- delivery: from its own shard lease row. Absent or not ready is `unbound`. A ready row held by\n  a different instance than the responder is `stale`. A ready row it holds is `bound`.\n- A responder that cannot determine its state answers `unknown`.\n\n**Rebinding.** A responder MUST bind its serve filter again on every broker connection that\nreplaces the one it bound on. A filter left on a closed connection gets the broker's\nno-responders answer, which a caller grades `unbound` for a plane that is still served. Each\nnew bind mints a new `instance`.\n\n**Caller grading.** The caller grades the outcome of asking:\n\n| Outcome | `responder` | `instance` |\n| --- | --- | --- |\n| a reply that parses as above | the reply's `responder` | the reply's `instance`, if any |\n| the broker's no-responders status (503) | `unbound` | absent |\n| timeout, permission refusal, transport failure | `unknown` | absent |\n| a reply that does not parse | `unknown` | absent |\n\nOnly the broker's no-responders answer yields `unbound` without a reply. Every other failure\nto get a readable reply is `unknown`. A caller MUST NOT report `unknown` as either health\nstate. A caller using the NATS binding MUST request without the muxed inbox, so a\nno-responders status reaches it rather than surfacing as a timeout.\n\n**Grants.** An agent may publish the request subject for each plane under its own principal\nand subscribe `<request subject>.>` for its replies. It holds neither serve filter, so it\ncannot answer for a plane. The `delivery` profile holds the delivery plane's serve filter and\nreply grant. The `supervisor` profile holds the manager plane's pair, and the remote-manager\nprofile holds them only for its supervisor actor (`manager_<instanceId>`). No responder can\npublish a request subject, because its reply grant stops at the `.reply.` leaf. Appendix B\nlists the agent rows.\n\nReference implementation: `livenessSubject`, `livenessServeFilter` and `livenessReplyGrant`\nin `packages/core/src/subjects.ts`; `LivenessAnswer`, `parseLivenessAnswer` and\n`responderFromProbe` in `packages/core/src/liveness.ts`; `CotalEndpoint.serveLiveness`,\n`serveDeliveryLiveness` and `probeLiveness` in `packages/core/src/endpoint.ts`.\n\n---\n\n## 7. Channels\n\nA channel is addressable as soon as it is published to. Channel config is optional and lives\nin the per-space registry bucket `cotal_channels_<space>`, keyed by the concrete channel\ntoken.\n\n`ChannelConfig`:\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `replay` | boolean | history replay-on-join; overrides the space default |\n| `replayWindow` | string | backfill horizon matching `^\\d+(s\\|m\\|h\\|d)$`, e.g. `\"24h\"` |\n| `deliveryClass` | `live` \\| `durable` | per-channel delivery class (\xA74); overrides the space default |\n| `description` | string | one-line purpose; max 200 chars |\n| `instructions` | string | advisory usage text; max 2000 chars |\n\nSpace-wide defaults (`ChannelDefaults`: `replay?`, `replayWindow?`, `deliveryClass?`) live under\nthe reserved key `=defaults`. Effective replay is `channel.replay ?? defaults.replay ?? true`.\nEffective delivery class is `channel.deliveryClass ?? defaults.deliveryClass ?? \"durable\"`.\n`defaults.deliveryClass` MUST be written at space creation from the deployment profile\n(local/self-hosted \u21D2 `durable`, persistence on by default; public/web-scale \u21D2 `live`, durability\nopt-in per channel), so the effective default is always discoverable on the wire, never inferred\nfrom out-of-band context. The same effective config MUST be the single source of truth for live\njoin, durable fan-out, history read, and membership surfacing; an implementation MUST NOT resolve\nthe class differently in different paths.\n\nJoin subscribes the instance to the channel; leave unsubscribes it. A join target MUST be within\nthe instance's read ACL (`allowSubscribe`, \xA79); a join outside it MUST be refused by the broker on\nsubscribe. A client MUST NOT publish to wildcard channels, but a wildcard read ACL (`team.>`)\nauthorizes subscribing to any one concrete channel under it **without enumerating channels in\nadvance**. In the NATS binding, join is a native `sub.allow`-bounded core subscription to the\nchannel subject and leave is the corresponding unsubscribe; **no privileged mediation is\nrequired**: the broker enforces every subscribe against `sub.allow`, so an instance whose ACL\npermits a channel joins and leaves it on its own, with no manager present. Open mode behaves the\nsame (the client subscribes directly). Leaving the last channel is permitted: under the core-sub\nbinding an empty subscription set subscribes to nothing (the v0.2 \"empty filter subscribes to all\"\nhazard and its last-channel-leave refusal were artifacts of the multi-filter durable and no longer\napply). On a `durable` channel, join additionally establishes durable membership, a separate\n**privileged** step: the instance requests durable membership from the server-side delivery daemon (a\ndurable-join command on the `delivery` endpoint, \xA713, carrying the channel and its captured join\ncursor) and the daemon writes the membership record. This is decoupled from the live subscribe, so a self-serve live join never depends\non it: a `durable` channel still delivers live with no privileged writer present, and only its\ndurable backstop requires one. A locally created subscription that the\nbroker later refuses (the permission violation is asynchronous in the NATS binding) is NOT a\nsuccessful join: an instance MUST treat a join as effective only once the broker has accepted the\nsubscribe, and MUST drop the channel from its joined set on a late refusal (\xA712). Leave removes the\nmembership (see membership below).\n\nReplay / catch-up on join:\n\n1. Record the channel join watermark (the CHAT frontier) before the subscription is active, so\n   live tail and backfill do not double-deliver.\n2. Subscribe to the channel subject (`sub.allow`-bounded; \xA78). The live copy now flows.\n3. If effective replay is on, read retained messages for that channel up to the watermark,\n   through a single-channel history read bounded by the current read ACL (`allowSubscribe`, \xA78),\n   optionally limited by `replayWindow`. History is ACL-bounded, not membership-gated: an ACL-holder\n   may read a channel's retained content whether or not it is a current member (it could self-join\n   and read regardless), so the confidentiality boundary here is the ACL, consistent with the live\n   read.\n4. Surface backfilled messages with `MessageMeta.historical = true`.\n5. Deduplicate by `id` across the live tail, the backfill, and (on `durable` channels) the durable\n   backstop, so a message surfaces once. Receiver deduplication MUST NOT coalesce copies solely\n   because `id` is the empty string (\xA74).\n\n   Informative: an implementation preserving an incarnation across a local restart may start step\n   3's read from the sequence that incarnation had reached, rather than from the retained window's\n   start; a fresh joiner reads the window.\n\n`replay=false` is noise control, not confidentiality. CHAT history is readable only within an\ninstance's read ACL (`allowSubscribe`, \xA79); confidential content MUST use DM or anycast.\n\nChannel membership governs **durable-delivery inclusion** (who receives fan-out copies into their\nper-subscriber backstop) and is broker-known, not self-reported. It is NOT a confidentiality\nboundary tighter than the read ACL: `allowSubscribe` bounds what content an instance may read (live\nand history, \xA79), and an ACL-holder can self-join, so membership adds delivery semantics, not read\nconfinement. In the NATS binding, membership is a privileged-written record in the space registry\nplane under a key the agent's profile cannot write (NOT the agent's presence key), carrying per-member\njoin/leave cursors so a publish concurrent with a join or leave orders deterministically; it is NOT\nderived from consumer topology, and an agent MUST NOT self-assert its own membership. It is written by\nthe server-side delivery daemon in response to a durable-join command on the `delivery` endpoint\n(\xA78, \xA713, Appendix B), distinct from and not required by the self-serve live subscribe. The implementation MUST re-authorize every\n**durable-backstop** read of `(instance, channel, message)` against the instance's current read ACL\nand membership before surfacing content, so a channel dropped from the ACL or **left** is no longer\nsurfaced from the backstop: **leave is a hard read boundary for the durable backstop** (it does not\nrevoke the ACL: an instance may still re-subscribe live, or read ACL-bounded history, within\n`allowSubscribe`). Membership remains observability data for liveness/roster purposes and MUST NOT be\nused as a send authorization gate.\n\nOn a `durable` channel, membership carries the member's **join cursor** (the CHAT frontier captured\nat join, the same watermark used to deconflict the live tail and the backfill) and, on leave, a\n**leave cursor/tombstone**. The durable backstop is at-least-once (within retention)\nfor messages whose stream sequence is **> the member's join cursor and \u2264 its leave cursor**, where each\ncursor is the CHAT frontier (the last sequence) captured at that transition; messages published before a\njoin or after a leave are not redelivered as durable and are reachable only via an ACL-bounded history\nread (within `allowSubscribe`). A rejoin takes a new join cursor, so messages published during the gap are not durably\nredelivered. A `durable` join is atomic across its two effects: the instance is durable-joined only\nonce BOTH the broker-confirmed live subscribe AND the membership write have succeeded, and on a late\nsubscribe refusal the membership record MUST be removed. If the live subscribe succeeds but durable\nmembership cannot be established (for example no privileged writer is present), the instance is\n**`joined live` with the durable backstop unestablished**: it MUST NOT be reported as `joined durable`,\nthe live subscription remains active, and the durable shortfall MUST be surfaced as an exceptional\ndelivery state (e.g. `durable backstop unavailable`), never silently.\n\n---\n\n## 8. NATS + JetStream binding\n\nBacking streams are created once at space setup. `STREAM.CREATE` is denied to agents in auth\nmode.\n\n| Stream | Captures | Retention | Required config |\n| --- | --- | --- | --- |\n| `CHAT_<space>` | `cotal.<space>.chat.>` | Limits | file storage, `max_msgs_per_subject=1000`, `discard=Old`, `allow_direct=true` |\n| `DM_<space>` | `cotal.<space>.inst.>` | Limits | file storage, no Direct Get |\n| `TASK_<space>` | `cotal.<space>.svc.>` | WorkQueue | file storage, no Direct Get |\n\nChannel **live** delivery is a native core-NATS subscription to `cotal.<space>.chat.*.*.<channel>`\n(wildcard sender owner+actor) bounded by `sub.allow` (\xA79), not a durable consumer; join/leave is the\nsubscribe/unsubscribe and needs no privileged mediation. The legacy v0.2 `chat_<owner>-<actor>`\nlive-tail durable is removed from this binding (it MAY coexist transiently during migration behind\n`id` dedup, but is not part of the contract).\n\nDurable consumers. Per-instance durables are keyed on the principal's **dash-form** `<owner>-<actor>`\n(a `.` is illegal in a durable name; see \xA72), so a durable name-scopes to exactly one principal:\n\n| Durable | Stream | Filter | Policy |\n| --- | --- | --- | --- |\n| `chathist_<owner>-<actor>-<uid>` | CHAT | one `cotal.<space>.chat.*.*.<channel>` per read | transient single-filter consumer for history reads (join-backfill / focus-recall); created per read scoped to one channel in `allowSubscribe`, then deleted; `AckNone`. History is ACL-bounded by the pinned filter, not membership-gated (\xA77, \xA79) |\n| `dm_<owner>-<actor>-<uid>` | DM | `cotal.<space>.inst.<owner>.<actor>.>` | provisioner-created in auth mode at lifecycle activation; bind only; `DeliverPolicy.ByStartSequence` with `OptStartSeq = activationFrontier + 1`, where the **activation frontier** is the DM-stream's last sequence captured at activation (`0` on an empty stream, so the start is `1`): `ByStartSequence` is inclusive and the lifecycle interval is half-open, so the consumer starts strictly AFTER the frontier, never `All`, which would replay a recycled alias's history and the inactive-gap backlog; `AckExplicit`; `ack_wait=60000ms` |\n| `svc_<role>` | TASK | `cotal.<space>.svc.<role>.>` | provisioner-created in auth mode; bind only; `AckExplicit`; `ack_wait=60000ms`. **Intentionally role-shared, not lifecycle-scoped**: anycast work belongs to the role, and successive holders draining one pool is the contract |\n\nFrom v0.4, each lifecycle's durable state lives in the **half-open interval**\n`(activationFrontier, retirementFrontier]` per stream: consumers start strictly after the\nactivation frontier (`OptStartSeq = frontier + 1`, table above; the frontier is captured\nAFTER any inactive alias gap), and terminal retirement records the\nretirement frontier before the alias is freed, so a successor lifecycle never receives the\npredecessor's pending backlog nor messages published while no lifecycle was active (\xA713.1).\n\nPer-instance durable names use the principal's dash-form `<owner>-<actor>` (both tokens\nfail-loud-validated, not lossily sanitized), so a durable name-scopes to exactly one principal (\xA72).\nThe authenticated wire identity is the principal, not the connection nkey. From v0.4, in auth mode,\nper-instance durable state is additionally **lifecycle-scoped** (\xA713.1): durable consumer names,\npending delivery cursors, membership rows, and ACL/ledger rows key on\n`(principal, lifecycleUid)` (dash-form `<owner>-<actor>-<lifecycleUid>`), terminal retirement\nrecords per-stream sequence cutoffs before an alias is reused, and a same-name successor\ninherits none of its predecessor's pending state: its consumers start after its OWN\nactivation frontier (which is \u2265 the predecessor's retirement cutoff), the cutoffs bound the\npredecessor's interval, they are never the successor's start.\n\n**Durable backstop (\xA74).** The per-subscriber durable copy is a delivery contract, not a pinned\nlayout: each member has a private durable store, written on publish for a `durable` channel's current\nmembers and, for an `@mention` on a `live` channel, for each mentioned target authorized to read that\nchannel (its `allowSubscribe` covers it), so an authorized but offline target still receives it. The\nagent holds **no content-bearing read** on this mixed store. A **trusted reader** (the server-side\ndelivery daemon) pulls each pending entry, re-authorizes `(instance, channel, message)` against the\nmember's **current read ACL** and, for `durable`-channel fan-out entries, its **membership interval**\n(the message's CHAT sequence is `> joinCursor` and `\u2264 leaveCursor`; \xA77), not a current-member boolean,\nso a pre-leave entry stays deliverable and a post-`leaveCursor` one does not,\nand delivers each authorized copy to the member over an **at-least-once** handoff (its own\n`dlv_<owner>-<actor>-<uid>` DELIVER consumer, carrying the same ack semantics, not a fire-and-forget publish). The trusted reader MUST NOT ack or\ndelete the backstop entry until the member has confirmed the copy was surfaced or handled (or it has\nbeen transferred to an equivalent per-member at-least-once mechanism with the same ack semantics); on a\ndownstream nak, timeout, or crash before that confirmation, the entry remains pending and redelivers, so\na crash between the `dlv` handoff and the member surfacing the message cannot lose it, and `durable`\nstays at-least-once end-to-end, not maybe-once. Content\nfor a channel dropped from the ACL, or (for a durable channel) left, is never surfaced (at-least-once for\nthe member within retention; **leave is a hard read boundary for the backstop**); a `live`-channel\n`@mention` copy is delivered and `id`-deduped the same way. The read MUST run in this trusted component\nthe agent cannot bypass, because a self-bound consumer has no server-side per-message ACL/membership\nfilter. The store's stream/subject layout, the fan-out writer, the trusted reader, and the membership\nregistry are reference-implementation, not normative; a conformant deployment MAY realize the backstop\ndifferently as long as the \xA74 guarantee and the \xA79 checks hold.\n\nThe absence of a usable receiver dedup key does not relax acknowledgement ownership: a\nJetStream-consumed copy with `id: \"\"` that is surfaced or handled MUST be acknowledged\nindependently. The reference fan-out and transfer publishes carry no `Nats-Msg-Id` for an\n`id: \"\"` message, so id-less messages are not publish-deduplicated on the durable plane.\n\nPublishers MUST publish channel, unicast, and anycast delivery messages through JetStream and set\nthe JetStream message id to `CotalMessage.id` (`Nats-Msg-Id` on the wire). A JetStream publish is\nan ordinary subject publish that the stream also captures, so the same message reaches core\nsubscribers live (\xA74 `live`) and is retained for history and the durable backstop in one publish;\nthe publish path is unchanged from v0.2; only the live *read* moves to a core subscription.\nAck/nak/term semantics apply to JetStream-consumed copies (history, DM, anycast, and the durable\nbackstop): receivers MUST ack only after a message has actually been surfaced or handled, MAY nak\ntransient failures, and MUST term permanently invalid messages. The at-most-once `live` copy is not\nacked.\n\nHistory on join uses the pinned single-filter `chathist_<owner>-<actor>-<uid>` consumer create above, bounded to\n`allowSubscribe`; agents are not granted unfiltered Direct Get. DM and TASK MUST NOT enable Direct Get\nbecause it would bypass the consumer-create deny that is part of the confidentiality boundary.\n\nKV buckets are also streams and are pre-created:\n\n| Bucket | Holds | TTL |\n| --- | --- | --- |\n| `cotal_presence_<space>` | presence (\xA76) | 6000 ms |\n| `cotal_channels_<space>` | channel registry (\xA77) | none |\n| `cotal_membership_<space>` | derived channel-membership feed (below) | none |\n\n**Derived channel-membership feed (observability).** `cotal_membership_<space>` is a per-agent\n(key = `card.id`) derived view of who is subscribed to each channel: the **union** of an agent's\n`live` core-subscriptions (read by a privileged daemon from the broker's connection view) and its\n`durable` memberships (the members registry), each value `{ live: string[], durable: string[],\nobservedAt }` with `live` keeping subscription patterns (wildcards) the consumer expands at read time.\nIt exists so an observer can show silent readers and `live`-channel membership without a broker-admin\ncredential in the dashboard tier; it is written by a scoped privileged daemon and read by the\nadmin/observer profile only. It is **DISPLAY-ONLY and broker-derived**: it MUST NOT be an input to any\ndelivery, ACL, or authorization decision (authority for those stays the broker's `sub.allow` and the\nmembers registry), and it is not part of the normative wire contract a client must implement.\n\n---\n\n## 9. NATS + JetStream security and authorization\n\n**On by default.** A space is provisioned with decentralized JWT auth. Open unauthenticated\ndev mode is available but out of scope for the security claims here. *(Informative\noperator-facing views of this section: [docs/identity-and-auth.md](docs/identity-and-auth.md),\n[docs/channels-and-permissions.md](docs/channels-and-permissions.md); the threat model is\n[docs/security.md](docs/security.md).)*\n\n- **Account = space, user = agent.** A space is one NATS account. The **broker's** operator signs\n  the account; an account signing key mints per-agent user JWTs. A broker (one nats-server trust\n  root: one operator, one system account) MAY host several spaces \u2014 one account per space, every\n  account signed by that one operator. Broker trust is therefore per-broker, never per-space: a\n  space owns only its own account and references the broker's operator, and rotating or replacing\n  broker trust is intrinsically broker-wide - it affects every tenant on the broker at once and\n  cannot be scoped to a single space.\n- **Profiles are default-deny allow-lists.** Subject, stream, durable, and KV names are built\n  from the same builders as \xA73 and \xA78. Exact profile shapes are in Appendix B.\n- **An agent's channel scope is three concepts**, each a list of channel names or wildcard\n  subtrees (`team.>`): `subscribe`, the active read set, the channels it subscribes to at boot\n  (now native core subscriptions; mutable at runtime by direct subscribe/unsubscribe with no\n  mediation); it MUST be a subset of `allowSubscribe`. `allowSubscribe`, the read **ACL**, the\n  channels it MAY read (default = `subscribe`), minted as native `sub.allow` subscribe grants over\n  `cotal.<space>.chat.*.*.<channel>` (wildcards preserved, so an open ACL needs no enumeration) and\n  as the matching per-channel history-consumer create grants. `allowPublish`, the post **ACL**,\n  the channels it may publish to; **default-deny** (a chat publish grant is minted only for a\n  declared channel).\n\nEvery grant below is keyed on the agent's **principal** `<owner>.<actor>` (\xA72), except the reply\ninbox, which is keyed on the **connection** `<connId>`: the connection nkey (static mode) or the\nclient-chosen nonce (user mode, \xA79). This is the one place the wire identity and the connection\ncredential diverge (\xA72): the principal keys subjects/durables/presence; the connId keys the inbox.\n\n| Profile | Application publish | Read surface | Notes |\n| --- | --- | --- | --- |\n| `agent` | own `chat.<owner>.<actor>.<ch>` for each `allowPublish` channel (post ACL, default-deny), `inst.*.*.<owner>.<actor>`, `svc.*.<owner>.<actor>`; endpoint request forms per minted capability (`ep.one`/`ep.all`/`ep.inst` with the capability's authz-mode/target pattern, caller triple `<owner>.<actor>.<uid>` pinned; `describe` by default; `epj` submissions for journaled capabilities; \xA713.9); own presence key | own `_INBOX_<connId>.>` + own endpoint reply rail (`ep.reply.*.*.*.<owner>.<actor>.<uid>.*`, exact arity); channel live tail via native `sub.allow` subscriptions to `chat.*.*.<channel>` per `allowSubscribe` (wildcards preserved); `STREAM.INFO` (stream-level state only, no body read) on `CHAT` and the world-readable KVs, plus `TASK` when the credential carries a `role`; presence and channel-registry KV watches, including create/info/delete of their client-managed ordered consumers on those two streams only; CHAT history via single-filter `chathist_<owner>-<actor>-<uid>` creates, one per `allowSubscribe` channel (ACL-bounded); own lifecycle-scoped `dm_\u2026`/`svc_\u2026` bind-only; durable backstop via own bind-only lifecycle-scoped `dlv_\u2026` DELIVER consumer, **no** grant on the mixed pre-auth fan-out stream; granted record-key/event-topic read subtrees per capability | read bounded by `allowSubscribe`; ordered-consumer cleanup cannot delete KV records or streams; durable copies re-authorized (current ACL + membership + lifecycle) by the trusted reader before the `dlv` handoff; no Direct Get; DM/TASK/DLV create denied. The `manager-caller` view narrows this endpoint control set to `ep.inst.manager.<managerInstanceId>.<command>` only, plus the exact instance `describe`, contract reads, own reply/progress rows, and own inbox. It carries no agent messaging, delivery, class, or scatter rows. |\n| `observer` | none | chat, CHAT history, presence, channel registry | DMs invisible |\n| `admin` | none | whole space live tap plus DM history | plaintext god-view, opt-in |\n| scoped host profiles | least-privilege per function | least-privilege per function | The former allow-all `manager` is **deleted**; its host duties split into scoped, single-function creds (`supervisor`, `provisioner`, `delivery`, `membership-rw`, `operator`, `purger`, `teardown`, `channel-writer`, \u2026). No allow-all credential exists. Appendix B summarizes them; the concrete grant lists are **generated from the \xA713.9 ownership matrix** into `provision.ts` (the matrix is the single oracle; `provision.ts` is its artifact, Appendix B its summary). |\n\nDM and TASK confidentiality, and the CHAT read boundary, close the leak paths:\n\n1. Replies and pull responses ride a per-connection inbox prefix, `_INBOX_<connId>.>`, which\n   `sub.allow` permits alongside the agent's channel read grants (next item) and nothing else. In user\n   mode the client picks `<connId>` (a nonce) and the callout scopes the inbox to it, so a\n   wildcard-inbox subscribe that would sniff peers' DM deliveries is refused. Re-authorized durable\n   copies do NOT ride the inbox; they ride the agent's own lifecycle-scoped `dlv_<owner>-<actor>-<uid>` DELIVER consumer\n   (item 5, \xA78).\n2. **Channel live reads are bounded by `sub.allow`.** `allowSubscribe` is minted as native subscribe\n   grants over `cotal.<space>.chat.*.*.<channel>` (wildcards preserved); the broker refuses, per\n   subscribe, any channel subject outside the ACL. There is no per-channel consumer name to confine,\n   so an open ACL (`team.>`, `>`) grants selective single-channel join with no enumeration and no\n   read-breakout. A `>` grant is read-all chat in the space by design (credential compromise reads\n   all chat), so it suits trusted/local deployments, not least privilege.\n3. A consumer create on the bare/multi-filter subject is not ACL-constrainable, so the provisioner\n   pre-creates `dm_<owner>-<actor>-<uid>`, `svc_<role>`, and the per-member `dlv_<owner>-<actor>-<uid>` handoff\n   durables. Agents bind their own `dm_\u2026-<uid>`/`svc_<role>`/`dlv_\u2026-<uid>` only (never\n   create); the mixed pre-auth fan-out store is read by a trusted reader, not the agent (\xA78, item 5).\n   Those bare/multi-filter create forms are not granted to agents (default-deny), with explicit\n   create-denies on `DM_<space>`, `TASK_<space>`, and the `DLV` stream; on `CHAT_<space>` the only\n   consumer-create an agent holds is the pinned single-filter history create (next item), so a broad\n   CHAT create-deny is intentionally absent: it would also deny that pinned create.\n4. CHAT history reads are bounded to `allowSubscribe`: a consumer create on the extended subject\n   `$JS.API.CONSUMER.CREATE.<stream>.<name>.<filter>` carries a single filter the server pins to the\n   request body, so an agent is granted exactly one such create-subject per `allowSubscribe` channel\n   and can read history of no other channel. The unfiltered Direct Get grant is not given to agents.\n5. **The durable backstop is read by a trusted reader, not the agent.** The agent holds no\n   content-bearing read on the mixed pre-auth fan-out store; a trusted reader (the server-side delivery\n   daemon) MUST re-authorize `(instance, channel, message)` against the member's current read ACL and,\n   for `durable`-channel fan-out entries, its current membership, before handing the authorized\n   copy off to the member's own lifecycle-scoped `dlv_<owner>-<actor>-<uid>` DELIVER consumer:\n   broker ownership of an inbox (\"this is agent A's\") is not authorization, since the store can hold\n   messages for channels A has since dropped from its ACL or left, and a self-bound consumer cannot\n   filter per-message on membership. Fan-out-on-write is routing, not an authorization check; for a\n   durable channel a `leave` is a hard read boundary on the backstop. History/backfill reads are instead\n   self-served and bounded by the current read ACL (the pinned single-filter create above), consistent\n   with the live read. An `@mention` durable copy is written only to a target authorized to read the\n   channel, so `mentions` cannot carry content outside a target's read ACL.\n6. **\"Current read ACL\" is the effective broker-accepted credential.** An ACL narrowing takes effect\n   when the credential/permissions are updated and enforced by the broker (re-mint / reconnect /\n   revocation), not as an instantaneous global value; until then an existing broad credential remains\n   broad. Both the broker `sub.allow` checks and the trusted-reader re-checks are evaluated against that\n   effective credential.\n\nThis binding provides containment and authenticity under a single trusted broker: an agent\ncan emit only as itself and only to its declared `allowPublish` channels, and read only its own\nDMs and chat *content* within `allowSubscribe` (and, for `durable` content, its current\nmembership), enforced by the server. It does not provide\nnon-repudiation, does not survive an untrusted relay, and DMs are plaintext to the broker and\nto `admin`. The read bound is on **content**, not metadata: agents hold `STREAM.INFO` on CHAT\n(for the join watermark, the recall drop-marker, and channel-list counts), so a `subjects_filter`\nquery leaks chat subject *metadata* (channel names, sender ids, and per-subject counts) for\nchannels outside `allowSubscribe` (channel names are already public via the registry). A\ncredential minted with a `role` also holds it on TASK, under the same gate as that role's\n`svc_<role>` bind grants, so a `subjects_filter` there leaks anycast subject metadata\n(`svc.<role>.<owner>.<actor>`, who anycast which role) to an operator-chosen role profile. DM,\nDLV, and EPC carry **no** agent `STREAM.INFO` grant: `subjects_filter` is a request-body field no\nACL can narrow to counts alone, so INFO there would enumerate who DMed whom, and no agent-side\nreader needs it (\xA713.1 reaches DM and DLV by durable name, EPC by subject-scoped `DIRECT.GET`).\nHiding the remaining metadata is deferred strict-containment work.\nSee [docs/security.md](docs/security.md).\n\n**Consumer-delivery confused deputy on the read grants.** A JetStream consumer delivers stored\nbytes to a **caller-chosen destination the broker does NOT confine to the requester's\n`pub.allow`**: a push consumer's `deliver_subject`, and a pull `MSG.NEXT`/`DIRECT.GET`\nrequest's reply subject, are set in the request body and the server's internal client publishes\nthere regardless of the requester's publish permissions. The v0.3 read grants above,\nCHAT-history `CONSUMER.CREATE`, the bind-only DM/DLV/TASK `MSG.NEXT`, and the KV watch creates\n(Appendix B); therefore let an agent redirect content it may legitimately READ onto a subject\nit may NOT publish to: e.g. replay a stored CHAT message whose `from.id` is another sender onto\n`inst.<victim>.<thatSender>`, where the recipient derives the DM sender from the subject and\nsurfaces it as a genuine DM from a principal who never sent it. The \xA713.9 \"Mediated reads\" rule\napplies here: **no untrusted agent holds a raw consumer `CREATE`/`MSG.NEXT` or `DIRECT.GET` on\n`CHAT`/`DM`/`TASK`/`DLV` or the KV buckets**; those reads are served by the trusted\nreader/mediator (\xA78) onto the agent's own confined rail. Which of these read paths require\nmediation and which are provably safe depends on whether a redelivered message retains its\noriginal captured subject and how the receiver's subject-derived kind check (\xA712) then\nclassifies it; the reference implementation determines this by test and pins the exact grants.\nOn the v0.3 rails without this mediation, read containment holds only against a *conforming*\nclient; the broker does not enforce it.\nSee [docs/security.md](docs/security.md).\n\n---\n\n## 10. Connection and onboarding\n\nJoin link grammar:\n\n```text\ncotal://[token@]host[:port]/space[?channel=a,b]      plaintext\ncotals://[token@]host[:port]/space[?channel=a,b]     TLS required\ncotal://user:pass@host/space                         user/password auth\n```\n\n- Default port is `4222`.\n- `channel` and `channels` query parameters are equivalent comma-separated channel lists.\n- Credentials in `userinfo` are parsed out and passed to the NATS client as connect options;\n  they are not left inside the server URL.\n- Bare `userinfo` with no `:` is a token. `user:pass` is username/password.\n- `cotals://` means `nats://host:port` plus TLS-required connect options.\n- Credentials (`creds`) are mutually exclusive with token and username/password auth.\n- A client MUST set `inboxPrefix` to `_INBOX_<connId>` before any request, pull consumer, or KV\n  watch operation, where `<connId>` is the connection identifier (the connection nkey in static\n  mode; the client-chosen nonce in user mode, \xA72/\xA79), NOT the owner+actor principal, which the\n  client may not know pre-connect.\n\nAuthenticated onboarding has two bindings. **Out-of-band credential minting** provisions a per-agent\ncredential ahead of connect (the static path). **Auth-callout onboarding** validates a user bearer at\nconnect time and mints the scoped data-account JWT then (user mode, \xA72/\xA710): the client presents a\ndeny-all sentinel credential plus its bearer, the callout derives the owner+actor principal and grants,\nand re-binds the connection into the data account. The owner-token *derivation* (how a bearer maps to\nan owner token) is a pluggable identity adapter (any OIDC/IdP via a thin bridge), not fixed by this\ncontract; the callout *mechanism* and the resulting grants are. From v0.4 every minted connection also carries its **lifecycle UID** (\xA713.1): the manager\nmints it for managed agents at provision, and the callout/exchange attaches it as a claim at\nconnect for user-mode connections, so the caller-UID token in every endpoint-rail grant is\nauthority-assigned, never client-chosen. Every bearer additionally carries its incarnation's\n**root credential id** (`act.credentialId`, \xA713.1). The exchange ensures the ACTIVE\n`cred.<lifecycleUid>.<credentialId>` ledger row exists BEFORE the bearer bytes are released\n(the row durable first, the issuance-gate finalize CAS, the lifecycle head's current-root CAS\nlast), and the connect authority proves the presented id against the LIVE row, leader-served\nfrom the shape-proved primary auth store: the row MUST be `active`, unexpired, and bound to the\nconnecting principal and lifecycle, and a root-issued credential MUST additionally equal the\nlifecycle head's current root credential. A claimless bearer, a revoked, expired, or absent row,\nand an unreadable authority store all DENY the connect. The root credential is\n**incarnation-wide**: ONE `cred.<lifecycleUid>.<credentialId>` row per incarnation, re-stamped\n(the same id) on every exchange for the incarnation's lifetime, never a fresh id per exchange.\nRevoking that one row is the per-credential revocation lever and denies EVERY bearer of the\nincarnation at the next connect (deny-new; evicting an already-live connection is the lifecycle\nbarriers' job, \xA713.1). Because the id is incarnation-stable, a crash after the head's current-root\nCAS re-exports the SAME id on the next exchange (that id IS the incarnation's live root, so there\nis nothing unobserved to revoke); the only pre-release crash window is a durable active-but-\nunstamped row, which the head-equality check denies. Rotating an incarnation's root credential is\nexclusively a lifecycle barrier's job, never a bare re-mint. A bearer MAY carry a server-authored\n**view** claim, selected only by the exchange and re-authorized against the live grant ledger at\nevery connect. The callout then mints the connection as that closed profile instead of `agent`.\nElevated views such as `admin`, `purger`, `channel-writer`, and `deployer` remain human-only. The\nnarrowing `manager-caller` view MAY be minted by either the human or managed-agent exchange and is\nserved on both exchange faces. It adds no capability. Its required `act.managerInstanceId` binds\nevery manager request to one exact live registered instance and is valid with no other view. The\nexchange selects from read-only observations of manager issuance gates and service registrations.\nIt refuses zero or ambiguous candidates and refuses an unavailable owner-specific remote manager\nrather than falling through to a co-located manager. An explicit selector must name a live candidate.\nThe `session-caller` view carries a required `act.session` claim `{endpoint, sessionId, epoch, exp}`\n(exp in unix seconds) and is valid with no other view; `act.session` is valid only with it. It needs no\nledger scope: the redeemed \xA713.6 session grant is the authority. The human exchange accepts it only\ntogether with a `sessionGrant` body (each without the other is a 400), and the trusted auth path MUST\nleader-read the `session.<sessionId>` row from the dedicated sessions store before it signs. It MUST\nrefuse unless the row is `active`, `row.grantSig` equals the presented grant's signature, the row's\nholder principal and lifecycle are the bearer's owner, actor and `lifecycleUid`, the endpoint and\nserving epoch equal the presented ones, `row.exp` is in the future, and the serving manager's issuance\ngate is a candidate for this owner with a process epoch equal to the row's. The stamped `exp` is the\nrow's, and the bearer TTL is bounded by it. The callout MUST re-run the same check, without the\nsignature comparison, against a fresh read at connect. It mints the `session-caller` profile for that\none session and binds the minted connection's expiry to the grant's, which is the static arm's\nexpiry, rather than the bearer's. The auth service's host-issuer connection performs both reads and\nholds only `STREAM.INFO` and the leader-served `STREAM.MSG.GET` on `KV_cotal_sessions_<space>`: no\nDirect Get and no write on that store.\nOn a public exchange face, `channel-writer`, `channel-purger`, `manager-caller`, and `session-caller`\nMAY be issued. `admin`, `purger`, `deployer`, and `manager-service` MUST remain loopback-only. A\nmanaged-agent secret exchange MUST refuse every view other than `manager-caller`.\n\n---\n\n## 11. Versioning and extensibility\n\n- Wire contract version is v0.2 as advertised today. `AgentCard.protocolVersion` (\xA76) carries\n  this string. The two v0.3 binding revisions (channel live delivery and owner+actor identity,\n  see the header) and the **v0.4 endpoint control surface** (\xA713) are the normative targets the\n  reference implementation is converging to. The control surface is an intentional **hard\n  cut on the pre-1.0 line** (\xA713.11): the v0.3 control grammar and envelope are removed from\n  this contract, not dual-served, a breaking revision, permitted pre-1.0, shipping under an\n  explicit new version marker per this section's rule; the marker is the disjoint endpoint\n  subject grammar and versioned envelope. The advertised `protocolVersion` bumps to `0.4` when\n  the control-surface migration completes (one campaign, one merge); a version string is not a\n  per-surface cutover claim. **`1.0` is deliberately deferred**: it is a stability declaration\n  to outside implementers, made separately once the contract has settled (further pre-1.0\n  arcs (presence/addressing, multi-space, federation) may still break the wire). **The wire `protocolVersion`\n  is the compatibility signal**; dated document snapshots (below) are navigation artifacts, not\n  negotiation; an implementation MUST NOT treat a document date as an interop key.\n- **v0.5 (workflow runs, \xA714) is an additive revision.** It adds a per-space stream, four core\n  record kinds, a per-run grant family and a normative language reference, and changes no existing\n  kind, subject, grant row or shipped datum; a participant that ignores \xA714 conforms to v0.4\n  unchanged. Two versions ride it and they are deliberately distinct: the wire `protocolVersion`,\n  which targets `0.5` when the plane is served, and the language's own `languageVersion` (\xA714.2),\n  which is bumped when a program's MEANING changes and is pinned per run, so a language revision\n  never forces a wire revision and a wire revision never invalidates an open run.\n- v0 has no in-band capability negotiation. Deployments MUST agree on the binding and\n  version out of band. A participant advertises the version it speaks via\n  `AgentCard.protocolVersion` (\xA76) as a one-way change signal, optional before the v0.4\n  marker, MUST from v0.4 (\xA76, \xA713.11); v0 defines no behavior on a mismatch beyond rejecting\n  messages it cannot parse.\n- **A non-additive discovery change is an out-of-band deployment cutover, and it rolls out\n  CALLER-FIRST.** A discovery change is non-additive when an unamended client that ignores it per\n  the unknown-field rule below would then behave in a way the change exists to prevent \u2014 for such\n  a change, ignoring is not a safe default and no default value repairs it. Every caller in a\n  deployment MUST implement the new version's rules BEFORE any responder in that deployment\n  registers or describes at that version. The two halves SHOULD therefore ship in **separate**\n  releases \u2014 the caller side first and adopted across the deployment, the responder's emission only\n  after \u2014 and shipping them in one release does not make a deployment safe, because **a release is\n  not a deployment**: an already-running caller is unchanged by whatever a new artifact contains,\n  so the order of two source edits says nothing about the processes on the wire. This rule exists\n  because the preceding one leaves a responder no way to detect the hazard itself: with no in-band\n  negotiation and no caller version on the wire, a responder cannot tell an amended caller from an\n  unamended one, so the obligation rests on the deployment rather than on either participant. The\n  observable marker is the discovery protocol's `protocol.v` on the registered service record\n  (\xA713.7) \u2014 \"has any responder cut over\" is a checkable registry property, while \"has every caller\n  adopted\" is exactly the out-of-band agreement this section already requires. **The residual is\n  real**: a deployment that cuts a responder over early exposes its unamended callers to whatever\n  the new version exists to prevent, and within v0 nothing in band detects it. Closing that needs\n  negotiation v0 does not have, and the v1 marker below is where it belongs.\n- New message families, subjects, and routing kinds are added in the core contract,\n  generalized for all deployments, not in one example.\n- Receivers MUST ignore unknown object fields and MUST NOT treat an unknown field as an\n  error.\n- A future v1 MUST either keep v0 subjects backward-compatible or use an explicit new\n  version marker in subjects, credentials, or deployment config.\n\n**Document snapshots.** Published revisions of this document are dated snapshots\n(`YYYY-MM-DD`, the **Last updated** date above): the current revision is canonical, and a\nsuperseded one stays retrievable from the repository history (the git history and tagged\nreleases of `SPEC.md`), so a client built against it can still be audited. The snapshot\ndate advances on any normative change; the wire `protocolVersion` moves only per the\nchange process below.\n\n**Change process.** This document is the change-control point: a change lands here first,\ngeneralized into `core`, and the reference implementation follows. Additive changes (a new\noptional field, a new namespaced `Part.kind`, a new subject) are backward-compatible and ship as\na minor bump, since receivers ignore what they do not recognize. Changing the meaning of an\nexisting field or subject, or removing or renaming one, is breaking. **Pre-1.0**, a breaking\nchange ships as a minor bump of the v0.x line under an explicit new version marker in\nsubjects, credentials, or deployment config (the v0.4 endpoint grammar is such a marker);\n**post-1.0**, it ships as a major bump. `1.0` itself is a stability declaration, made\ndeliberately and separately from any wire change.\n\n**Extension namespacing.** Core `Part.kind` values, `meta` keys, and `tags` are bare and reserved\nto this spec (`text`, `data`, `artifact`, and future core additions). A non-core extension MUST namespace its\ncustom `Part.kind` values and `meta` keys reverse-DNS, under a domain its author controls, e.g.\n`{ \"kind\": \"com.acme.snapshot\" }` or `meta[\"com.acme.region\"]`; Cotal's own non-core extensions\nuse `ai.cotal.*`. This keeps third-party names from colliding with each other or with future core\nnames, with no central registry.\n\nReserved future work: signed envelopes, `did:key` identity, auth-callout bootstrap tokens,\nmanager profile scoping, and federated/untrusted relay bindings. (Revocation/TTL for minted credentials is no longer future work on the control\nsurface: v0.4 defines it normatively via the credential ledger and the lifecycle barriers,\n\xA713.1.)\n\n---\n\n## 12. Conformance\n\n*(An informative build-order walkthrough of this checklist is\n[docs/build-a-client.md](docs/build-a-client.md).)*\n\nA conformant authenticated NATS client MUST:\n\n1. Use one stable principal `<owner>.<actor>` as its wire identity everywhere: subject sender\n   tokens (\xA73), `from.id` (\xA75), presence key (\xA76), durable names (dash-form, \xA78); and treat the\n   connection credential (nkey) as distinct, keying only its reply inbox (\xA72).\n2. Publish only on subjects whose sender tokens are its own principal `<owner>.<actor>` (\xA73).\n3. Publish delivery messages as UTF-8 JSON through JetStream with `msgID = id` (\xA78).\n4. Set exactly one routing field on each delivery message (\xA75).\n5. Reject any received delivery message whose `from.id` does not match the subject sender, and whose\n   subject `<owner>` is not a well-formed principal owner token: a subject that split-parses but\n   carries a non-owner in the owner slot (e.g. a raw nkey, an old-shape alias) MUST NOT be surfaced\n   as a delivery (\xA73, \xA75).\n6. Derive delivery kind (channel/dm/anycast) from the subject, not payload routing fields (\xA74).\n7. Ack only surfaced/handled messages and terminate permanent anomalies (\xA74, \xA78).\n8. Write only its own presence key on the heartbeat interval (\xA76).\n9. Set the per-instance inbox prefix before transport operations (\xA710).\n10. Treat unknown fields as ignorable (\xA711).\n11. Resolve a channel's effective delivery class (`live`/`durable`) from channel config, not from a\n    deployment assumption, and use one resolution across live join, durable fan-out, history read,\n    and membership surfacing (\xA74, \xA77).\n12. On a `durable` channel, tolerate the at-most-once `live` gap and catch up via the durable\n    backstop; deduplicate by `id` across the live, backfill, and durable copies (\xA74, \xA78). Receiver\n    deduplication MUST NOT coalesce copies solely because `id` is the empty string (\xA74).\n13. Join and leave a channel's **live** subscription by subscribing/unsubscribing under `sub.allow`\n    with no privileged mediation; treat a live join as effective only once the broker accepts the\n    subscribe, and drop it on a late permission refusal. On a `durable` channel, additionally establish\n    durable membership via the privileged provisioner; if it cannot be established, report `joined live`\n    with the durable backstop unestablished, never `joined durable` (\xA77, \xA79).\n14. Bound history/backfill reads by the current read ACL, and re-authorize every durable-backstop read\n    against the current read ACL (and, for `durable`-channel entries, membership) before surfacing\n    content, treating a leave as a hard read boundary on the backstop (\xA77, \xA79).\n\nTest vectors use these sample principals (`<owner>.<actor>`); `<ownerA>` = `u_aaaaaaaaaaaaaaaaaaaaaaaaaa`,\n`<ownerB>` = `u_bbbbbbbbbbbbbbbbbbbbbbbbbb` (owner tokens are `u_` + 26 base32-lower, \xA72):\n\n- Alice: `<ownerA>.alice`\n- Bob: `<ownerB>.bob`\n- Reviewer role: `reviewer`\n\nSubject parsing. `parseSubject` **splits only** (\xA73): it recovers tokens by prefix and per-kind arity\nbut does NOT validate the owner token: a well-formed *split* is necessary, not sufficient, for a\nsubject to be surfaced as a delivery. The last row shows an old-shape alias that split-parses yet MUST\nbe dropped at the surfacing boundary (\xA79):\n\n| Subject | Result |\n| --- | --- |\n| `cotal.main.chat.<ownerA>.alice.team.backend` | `kind=chat`, `sender=<ownerA>.alice`, `rest=team.backend` |\n| `cotal.main.inst.<ownerB>.bob.<ownerA>.alice` | `kind=inst`, `sender=<ownerA>.alice`, `rest=<ownerB>.bob` (recipient) |\n| `cotal.main.svc.reviewer.<ownerA>.alice` | `kind=svc`, `sender=<ownerA>.alice`, `rest=reviewer` |\n| `cotal.main.ctl.manager.<ownerA>.alice` | no sender; v0 control subject, retired (\xA713.11): nothing serves it and it MUST NOT be handled |\n| `cotal.main.chat.<ownerA>.alice` | no sender; malformed (owner+actor but no channel token) |\n| `cotal.main.chat.UAQGWOEVJKMIO4WXSYOTLARXYOZTCXFK67JASEH6AFFFYK6FOPSKQCAD.team.backend` | split-parses (`kind=chat`, `owner=UAQ...QCAD`, `actor=team`, `rest=backend`) but MUST be dropped: `UAQ...QCAD` is not a principal owner token (\xA73, \xA79) |\n\nSample multicast message:\n\n```json\n{\n  \"id\": \"018f1d0a-0000-7000-9000-000000000001\",\n  \"ts\": 1710000000000,\n  \"space\": \"main\",\n  \"from\": {\n    \"id\": \"u_aaaaaaaaaaaaaaaaaaaaaaaaaa.alice\",\n    \"name\": \"alice\",\n    \"role\": \"planner\"\n  },\n  \"channel\": \"team.backend\",\n  \"mentions\": [\"bob\"],\n  \"parts\": [{ \"kind\": \"text\", \"text\": \"Can you review this?\" }],\n  \"contextId\": \"ctx-1\"\n}\n```\n\nSample unicast message changes only the routing field:\n\n```json\n{\n  \"id\": \"018f1d0a-0000-7000-9000-000000000002\",\n  \"ts\": 1710000001000,\n  \"space\": \"main\",\n  \"from\": {\n    \"id\": \"u_aaaaaaaaaaaaaaaaaaaaaaaaaa.alice\",\n    \"name\": \"alice\"\n  },\n  \"to\": \"u_bbbbbbbbbbbbbbbbbbbbbbbbbb.bob\",\n  \"parts\": [{ \"kind\": \"text\", \"text\": \"Direct note.\" }]\n}\n```\n\nInterop scenario:\n\n1. Provision a space and credentials for Alice and Bob.\n2. Alice and Bob connect with inbox prefixes `_INBOX_<connId>` (per-connection, \xA72).\n3. Both write presence and join `team.backend`.\n4. Alice multicasts on `team.backend`; Bob receives with `kind=channel`.\n5. Alice unicasts to Bob; Bob receives with `kind=dm`.\n6. Alice anycasts to `reviewer`; exactly one reviewer receives with `kind=anycast`.\n7. A late joiner joins `team.backend`; replayed messages arrive with `historical=true` and\n   live-tail duplicates at or below the join watermark are ack-dropped.\n\n---\n\n## 13. Endpoint control surface (v0.4)\n\nEverything on the mesh that serves structured commands (the manager daemon, the delivery\ndaemon, a wrapped MCP server, a third-party service) is an **endpoint**: a daemon that\nregisters a service identity, publishes its contracts, and answers `describe`. There is no\nspecial-cased service in this contract: `manager` and `delivery` are endpoint names like any\nother, and no subject or envelope in this section knows them. This section supersedes and\n**deletes** the v0 control rail (`ctl.<service>.<owner>.<actor>`, `ControlRequest`/\n`ControlReply`, the `self`/`manager`/`admin`/`delivery`/`delivery-admin` service tiers, and the\nreserved `control.<instance>` subject). The cut is hard (\xA713.11): no v0 control subject,\nenvelope, handler, or grant survives, and a pre-cut control credential cannot reach a post-cut handler.\n\nLayering: identity and transport are \xA72/\xA73, extended by the lifecycle identity below; \xA713.1\nidentity; \xA713.2 grammar; \xA713.3 envelope; \xA713.4 delivery contracts; \xA713.5 verbs; \xA713.6\ncomposites; \xA713.7 contracts and discovery; \xA713.8 distributed guarantees; \xA713.9 authority\nboundary; \xA713.10 receipts and signing anchors; \xA713.11 the hard cut; \xA713.12 the NATS binding;\n\xA713.13 plane ownership; \xA713.14 conformance.\n\n### 13.1 Lifecycle identity\n\nThe principal `owner.actor` (\xA72) is a **recyclable routing alias**: despawning an agent frees\nits actor name, and a later spawn may legitimately reuse it. An alias is therefore never\nsufficient *authority* identity on this surface. Two further identity components exist:\n\n- **Lifecycle UID** (`lifecycleUid`, one token `[a-z0-9]{26,32}`, \u2265128 bits of CSPRNG\n  entropy in a fixed canonical encoding): an unguessable, never-reused\n  identifier of one managed lifecycle under a principal. The UID is entropy, never order:\n  no allocator counter exists, and what is durable and monotonic is only the never-used\n  set. Before anything else, the minting authority (the manager for managed agents; the\n  provisioner for endpoint daemons and operator credentials) **reserves the candidate UID\n  space-globally**: a create-only write of the reservation key `uid.<lifecycleUid>`\n  (\xA713.7), never deleted for the life of the space. A create conflict burns the candidate\n  and draws a fresh one (the alias head alone cannot reject the same UID under a different\n  alias, and the `gate.`/`cred.` families key by UID alone, so uniqueness must be\n  space-wide); a DEL/PURGE marker on a reservation is corruption, never reusable absence.\n  Only then does it mint **before the entity is reachable**, persisting a CAS-fenced\n  mapping\n  `{ owner, actor, lifecycleUid, managerInstance, processEpoch,\n  state: active | retiring | retired, currentCredentialId?, lastTakeoverOpId?, op? }` (closed\n  schema; the\n  embedded `owner`/`actor` MUST equal the key's alias tokens, so a key-mismatched row\n  never authorizes; `currentCredentialId` is absent until the credential ledger releases\n  a root under the reopened gate; `lastTakeoverOpId` is the opId of the takeover operation\n  that LAST advanced `processEpoch` (the epoch advance and this stamp are ONE head CAS, so a\n  completion is bound to exactly one operation: a resuming barrier confirms the completed head\n  carries ITS opId, and a LOSING concurrent takeover that captured the same pre-takeover\n  coordinates finds a foreign opId and refuses, never claiming the winner's completion; absent\n  until the first takeover); `op` is required at `retiring` and forbidden elsewhere)\n  under the alias's **CAS head key** (\xA713.7:\n  the **unsplit** `lifecycle.<owner>.<actor>` head key HOLDS this mapping as one atomic\n  record, the single authoritative current mapping and the only source of `mappingRevision`,\n  \xA713.9; the UID-suffixed `lifecycle.<owner>.<actor>.<lifecycleUid>` key is optional\n  append-only audit, never the authority). `mappingRevision` IS the head key's store\n  revision, learned from the publish ack or from the leader-served read that returned the\n  mapping (one read returns `{ mapping, revision }`); the value carries NO revision field,\n  and a body-supplied revision is never a CAS coordinate. Head states: `active` is the\n  ONLY current state. `retiring` is the containment phase of the terminal barrier (below),\n  bound to the retirement operation's `op.opId`; it is non-current and NOT replaceable.\n  `retired` is terminal and asserts the barrier COMPLETED (the cleanup proof), which is\n  what makes replacing a retired predecessor safe. **Every currency seam fails closed on\n  both non-`active` states**: target resolution, the process-epoch reads gating\n  record/status writes, admission/start, and supervision derive current authority only\n  from `state: \"active\"`; `retiring` and `retired` alike yield no current mapping and no\n  current epoch. Activation is the head CAS (create-only for a virgin alias;\n  revision-pinned from a `retired` predecessor), so two concurrent mints for one alias\n  serialize there and exactly one activates; the loser terminalizes its own orphan gate\n  and burns its reserved UID, never deleting either (`currentCredentialId` is a public key\n  identifier/fingerprint plus authority epoch, never secret material). A supervised restart\n  of the same entity **preserves**\n  the UID (revoking/rotating the connection credential and advancing the process epoch); a\n  terminal despawn, explicit stop, or supervision escalation retires the UID through the\n  terminal barrier *before* the alias is freed. A retired UID is never reactivated\n  (`retired \u2192 active` for the SAME UID is forbidden; only the ALIAS is replaceable, by a\n  freshly reserved UID); recycling cannot move to the reservation, which is never freed.\n- **Process epoch** (`incarnation`, an unsigned integer): the fenced ownership epoch of the\n  process currently animating an identity, advanced by CAS on every takeover or restart. At\n  most one live epoch owns an identity; a superseded process MUST stop serving and its commits\n  are rejected (\xA713.8). **The epoch fences egress only**: reply, event, timer, session, and\n  record-write-ingress publish grants pin it (\xA713.9), but request subjects deliberately omit it; a caller cannot\n  know the serving epoch, so **no subject-level fence for ingress exists or can exist**. An\n  un-revoked superseded serve credential remains a member of the class queue group and can\n  consume (and externally effect, and never validly answer) one call in N. Takeover therefore\n  carries a **normative barrier, in order**: freeze issuance for\n  the lifecycle in the credential ledger (below) \u2192 revoke EVERY active credential-ledger\n  row under the lifecycle prefix, every root (the superseded `currentCredentialId` and any\n  earlier unexpired root: each root mint, initial or rotation, writes its own ledger row)\n  and every ledgered descendant (handle-redemption-minted and per-session credentials,\n  \xA713.6), via the deployment's auth\n  authority, verifying the updated revocation state is enforced on EVERY server of the\n  cluster before proceeding (fail-closed on partial acknowledgment: an unrevoked-anywhere\n  credential can reconnect there) \u2192 evict the live connections of every revoked\n  credential's `holderPrincipal` (from its ledger row, above)\n  cluster-wide and verify the re-scan found none, the barrier executor (the trusted auth\n  path) holds the delivery endpoint's `evictPrincipal` capability for exactly this step\n  (Appendix B: granted to the barrier executor, not only `supervisor`); `evictPrincipal`:\n  system-account CONNZ scan \u2192 per-server KICK \u2192 re-scan verify, fail-closed on partial\n  scans; Appendix B) \u2192 **only THEN advance the process epoch by CAS (N\u2192N+1), reopen the gate\n  at the new generation, and activate the successor's serve subscription**. The epoch CAS is\n  LAST, not first: a superseded process is revoked and evicted before the successor's epoch\n  exists, so it cannot publish a reply or event in a window between the CAS and the eviction;\n  the egress epoch is honest attribution precisely because no live predecessor egress survives\n  the barrier. (A reply the predecessor emitted for an in-flight call before eviction reaches\n  a caller only within that caller's own deadline and from a not-yet-evicted process; the\n  barrier's job is that no such process remains once the successor answers.) Where\n  revocation or verified eviction is unavailable (e.g. static credential material\n  pre-rotation, Appendix B), takeover MUST fail loud rather than proceed.\n\n**Credential ledger (normative).** Ingress has no epoch fence, so revocation is only as\ncomplete as the set of credentials it covers, and the lifecycle's `currentCredentialId` is\nnot that set. Every credential the trusted auth path mints **derived from** a lifecycle (the\nshort-lived credential of a handle redemption, the two per-session credentials of a session\nredemption, \xA713.6) is recorded at mint time in a durable, auth-owned **credential ledger**\nrow `{ credentialId, holderPrincipal (the `<owner>.<actor>` whose connections the barrier evicts; the credential id is NOT the principal, and eviction is by principal), lifecycleUid (the holder's), sourceChain: [root |\nhandle.<issuerKeyId>.<id>\u2026 | session.<sessionId>], the FULL verified lineage: for a\nhandle redemption, EVERY handle in the presented `parentDigest` chain (\xA713.6), never only\nthe leaf, state: active | revoked (monotonic), exp }`, keyed\n`cred.<lifecycleUid>.<credentialId>` so both barriers enumerate a lifecycle's full descendant\nfamily by key prefix. Each mint additionally writes one reverse-index key\n`bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>` per chain member, so **revoking a\nsturdy handle revokes every credential minted under it or under any of its descendant\nhandles**; a credential redeemed through a child handle carries the parent in its\n`sourceChain`/`bysrc` keys, so parent revocation reaches it without walking handle records.\n**Source gates.** The same fence applies per issuing handle, because a handle's revocation\nstate lives in the records bucket while credential indexes live here, and two buckets share\nno order: each sturdy handle has an auth-bucket gate `srcgate.<issuerKeyId>.<id>`\n(`{ state: open | frozen }`, CAS). Handle revocation CASes the source gate to `frozen`\n**before** it enumerates `bysrc.`, and a redemption, after writing its `cred.`/`bysrc.`\nrows, revision-pinned-CASes the source gate of EVERY handle in the presented chain (plus the\nlifecycle gate below), releasing only if all are still `open` at their observed revisions. An\nin-flight redemption under a handle being revoked therefore either finishes before the freeze\n(its rows are in the enumeration) or loses a CAS and never releases. **Handle revocation\ncarries the SAME cluster-wide eviction as a lifecycle barrier** (\xA713.9 `evictPrincipal`):\nafter freezing the source gate and enumerating `bysrc.`, revocation revokes every descendant\ncredential AND verifies revocation enforced on every server, then evicts and re-scans the live\nconnections of every revoked credential's principal, fail-closed, an already-connected\ndescendant credential is never silently left with live grants. The handle status write is\nacked only after that eviction is verified complete.\n\nAn unledgered mint MUST NOT occur (the ledger write precedes credential\nrelease, fail-closed), and the rule carries a mechanical audit invariant in the style of the\n\xA713.9 matrix grep test: every credential the auth authority has ever released MUST resolve\nto a `cred.<lifecycleUid>.<credentialId>` row; an issuance path that cannot show its ledger\nrow is non-conformant, auditable by diffing issued-credential ids against the ledger.\n\n**Issuance gate (normative).** \"Freeze issuance\" is a durable transition, not an assertion:\neach managed-agent lifecycle has a gate key `gate.<lifecycleUid>` in the same auth KV,\n`{ state: open | frozen | retired, generation, op? }` (CAS). A `frozen` gate MUST carry a\ndurable **operation intent** `op = { opId, kind: activation | takeover | registration |\nretirement, successor? }`: after a crash the intent alone\ndecides WHICH operation a frozen gate belongs to and what may advance it, a retry or\nreconciler resumes the SAME `opId`, and a writer that is not that operation's executor\nMUST NOT advance, reopen, or terminalize the gate.\n**A crash can leave the gate frozen under an operation whose executor no longer exists**, and\nfail-closed then blocks every restart while protecting nothing. An operator-facing reconciler\nMAY complete that dead operation's obligation \u2014 resuming its SAME `opId` and reopening at the\nUNCHANGED coordinate with `generation` advanced by one \u2014 but ONLY after it has AFFIRMATIVELY\nverified that the gate's freeze-holder principal is gone, via the same liveness machinery the\nbarrier's eviction trusts (`principalLiveness`, \xA713.9). A holder that is alive, or whose\nliveness cannot be proven, MUST refuse; a timeout or an incomplete sweep is unknowability and\nMUST NOT be read as death. The affirmative check is a PRECONDITION ON TOP OF the barrier's own\nverified eviction, never a replacement for it. A `retired` gate RETAINS the\nterminalizing operation's intent as audit, and an idempotent terminal retry succeeds only\nfor that SAME operation. **Successor coordinates are per-kind and derivable, never loose\nprose**: an `activation` or `retirement` intent carries NO `successor` (an activation's\nsuccessor IS the head mapping the same operation writes; a retirement has none); a\n`takeover` or `registration` operation's successor artifacts are durably keyed by its own\n`opId` (the `stage.<opId>.` staging family and the operation's audit rows), so\n`{ opId, kind }` alone resumes deterministically. The gate MAY carry a `successor` summary\ntoken for those two kinds, but the staged rows are authoritative and a resumer MUST NOT\nact on a summary that the staged rows do not corroborate. **Allowed transitions are also\nper-kind**: a gate is BORN `frozen` only under an `activation` intent (and only for a UID\nwhose `uid.` reservation already exists); `open \u2192 frozen` belongs to `takeover`,\n`registration`, and `retirement`; `frozen \u2192 open` (reopen) belongs to `activation`,\n`takeover`, and a `registration` abort, NEVER `retirement` (a retirement freeze never\nreopens); `frozen \u2192 retired` belongs to `activation` (a head-CAS loser terminalizing its\nown orphan gate) and `retirement`, NEVER `takeover` or `registration` (those abort by\nreopening). An implementation MUST refuse a transition whose gate op kind is outside these\nsets, before any CAS is attempted. The `opId` is an identifier, never a\nbearer capability: a resumer re-authenticates as the operation's executor, and possession\nof the id alone grants nothing. `retired` is terminal, a retired\nlifecycle never mints again. `frozen` is **not** terminal, because a supervised restart\npreserves the UID (\xA713.1) and must mint the successor process's root credential: the\ntakeover barrier freezes at generation `G`, completes revoke + verified eviction of the\nfamily, and only then CASes the gate to `open` at generation `G+1`; the reopen is the\nbarrier's own final step, so no credential of generation `G` is ever live when generation\n`G+1` mints. A gate reopen by anyone but the completing barrier is non-conformant.\n**Endpoint instances use a disjoint gate family, distinguished by explicit prefix and\nnever by token arity**: the endpoint issuance gate is `epgate.<endpoint>.<instanceId>`,\n`{ state: open | frozen | retired, generation, processEpoch, registrationRevision,\nnameAuthorityRevision, principal, op? }` (the endpoint fence coordinates of \xA713.5/\xA713.7, plus\n`principal`: the serving instance's own CONNZ-attributable connection principal, recorded at\nregistration), and\nendpoint-derived credentials ledger under `epcred.<endpoint>.<instanceId>.<credentialId>`\nwith the same row schema, mint protocol, gate discipline, and never-delete rules as\n`cred.`/`gate.`. An interrupted endpoint registration repair MAY journal verified evictions\nunder the disjoint cursor key `eprepair.<endpoint>.<instanceId>`. A cursor MUST bind the exact\nregistration `opId`, the observed frozen-gate KV revision, and the sorted distinct holder set.\nA holder is appended durably only after its eviction verifies, and the holders one eviction sweep\nverified are appended before the next sweep is attempted. A retry MUST repeat the freeze-holder\nliveness precondition, MAY skip only holders in a cursor whose complete binding still matches, MUST\nrestart from empty progress on any mismatch, and MUST reopen only after every current holder\nverifies. Cleanup occurs after reopen; a cursor that\ncannot be deleted cannot authorize a later freeze because that freeze has a different gate revision.\n**`holderPrincipal` is ALWAYS a CONNZ-attributable `<owner>.<actor>` in\nBOTH families** (the barrier KICKs it; an endpoint NAME is not attributable and never sits\nthere): in `cred.` it is the caller principal; in `epcred.` it is the serving instance's own\nconnection principal, copied from the endpoint gate's `principal`, while the endpoint NAME that\nforms the `epcred.` KEY is a SEPARATE row field, so the key identity and the eviction target\nstay disjoint (an `epcred` row that put the endpoint name in `holderPrincipal` could never be\nKICKed). The `cred.`/`epcred.` families hold ONLY conformant ledger rows:\nimplementation staging, half-minted state, and tombstone fences live in a distinct\n`stage.` family, never under a ledger prefix a barrier enumerates.\n\n**Remote manager-service authority (user-auth only).** `manager-service` is one CLOSED,\nserver-authored authority view, not a profile name, arbitrary bearer profile, or client-supplied\npermission set. It exists only for a signed-in human whose current actor-ledger row contains the\ndedicated `supervise` scope. `spawn` and `admin` never imply `supervise`, and `supervise` never\nimplies either. Only the loopback/operator exchange MAY issue this view; the public exchange and\nevery managed-agent secret exchange MUST refuse it. The callout re-reads the ledger row at exchange\nand connect, so a missing, narrowed, or revoked `supervise` scope denies the next view exchange and\nnew connection with the full re-grant requirement. A plain user bearer remains `agent`-scoped.\n\nThe view names exactly one ordinary derived owner, a fixed server-selected manager actor, that\nactor's lifecycle UID, and one opaque locally selected `instanceId`. The actor and instance id are\nnot client-selectable, and the view grants no second manager instance, other endpoint, or other owner.\nIt may reach only the manager instance's own `svc.manager.<instanceId>` registration/status,\npre-authorized immutable contract publication, endpoint rails, and the disjoint\n`epgate.manager.<instanceId>` / `epcred.manager.<instanceId>.<credentialId>` family. It does not\nconfer the space signer, callout signer, owner secret, static provisioner credential, generic\nstream/KV authority, or authority over another instance's gate, records, contracts, or\ncredentials. A manager-service credential is ledgered and gated exactly as this section requires;\nits `holderPrincipal` is the derived-owner/fixed-actor principal, never the endpoint name.\n\nThe typed protocol includes two host-owned registration-maintenance operations. An\n`evict-family-principal` request names one principal, but the host MUST enumerate the authenticated\ncaller instance's `epcred.manager.<instanceId>.*` family and refuse unless that principal is one of\nits holders. The host, using its signer, then mints the bounded delivery-admin caller, requests\n`evictPrincipal`, and returns the closed `EvictionResult`; a garbled, foreign, or contradictory\nresult MUST NOT authorize. The participant never receives that credential. A\n`reconcile-registration` request MAY name another manager instance in the same space only to clear\nan abandoned governance-slot holder. The host MUST observe that target's frozen registration gate,\nprove the freeze-holder `gone` under a complete liveness sweep, run the normal registration repair\nwith verified eviction, and refuse live, unknown, incomplete, unestablishable, or non-registration\nstates. There is no force path. A participant credential still gains no direct authority over the\ntarget gate, records, family, or delivery-admin rail.\n\nThe bounded executor returned by `prepare` is renewable through `renew` for the same public nkey and\ncurrent open registration. A remote manager MUST obtain a fresh executor before maintenance or clean\nderegistration when its retained credential is not healthy. A restart MUST drive family eviction\nthrough the host operation before advancing its epoch. A registration blocked by a foreign frozen\nmanager governance slot MAY request guarded host reconciliation and retry exactly once.\n\nThe typed protocol also carries two host-owned MANAGED-AGENT operations,\n`manager-managed-agent-enrollment` and `manager-managed-agent-prepare-retirement`. Both name the\nauthenticated owner's own managed agent and both require the caller's current `supervise` scope;\n`spawn` and `admin` never imply it. Both MUST be authorized against the caller instance's CURRENT\nopen manager gate: the gate's principal MUST equal the server-derived serve principal, its process\nepoch MUST equal the request's `serveEpoch`, and the request's registration proof MUST match the\nproof the host issued for that registration revision and epoch. An enrollment request MUST carry the\nSHA-256 digest of the agent's standing actor token and never the token itself, and MUST NOT carry a\nlifecycle UID: the HOST selects it, because only the host can observe the retirement tombstones that\nmake a UID permanently unusable. A prepare-retirement request MUST name a target owner equal to the\nauthenticated owner, and its `opId` MUST equal `managedRetirementOpId(target.lifecycleUid)`,\nrecomputed by the host rather than trusted, so one lifecycle never carries two terminal operations.\n\nThese two operations mutate host-owned storage, so an implementation that owns no such storage MUST\nrefuse them with `unimplemented` rather than answering a manager-lifecycle phase for them. A host\nplatform that owns the writers MAY intercept them on its own authenticated route and obtain the\ndecision alone from the auth service's loopback door\n`POST /manager-service-authority/verify-enrollment`, which carries the same loopback guards as the\nmanaged-retire door (POST only, no `Origin`, JSON, the per-start capability, a closed\n`{ owner, request }` body). That door MUST derive the caller's capability scope from its own ledger\nand MUST NOT accept a scope from the caller. It decides only: it mints nothing, writes nothing, and\nreturns no secret.\n\nTwo further host-owned kinds address the hosted runtime of an already-enrolled managed agent:\n`manager-managed-agent-runtime-create` and `manager-managed-agent-runtime-status`. Each carries the\nmanaged-agent envelope plus exactly `target: { owner, actor, lifecycleUid }`. Both schemas are closed:\nan unknown top-level or target field, including `providerRef`, `handle`, or `name`, MUST be refused as\n`bad-request` with no effect. There are no participant stop, adopt, or probe kinds. Both MUST be\nauthorized with the same gate, epoch, and proof checks as enrollment, with a target owner equal to the\nauthenticated owner, and with `supervise` read from the host's own ledger row for the manager actor.\nThe decision yields only the verified owner, instance id, manager actor, and target. A status decision\nauthorizes no effect. An implementation without host intent storage MUST refuse both with\n`unimplemented`. The answer carries `state` (`reserved`, `creating`, `bound`, `create-unknown`,\n`closing`, or `closed`), `readiness` (`ready`, `bound-not-ready`, or `none`), and an optional\n`retirementPhase`. An enrollment result MAY carry `runtimeIntent: { state: \"reserved\" }`, which is\ndisplay-only and MUST NOT be treated as authority.\n\nThe host, not the participant, issues every data-account credential requiring the account signing\nkey. The only remote path is the lifecycle- and instance-bound typed protocol of \xA713.6; a broader\nbearer or a generic credential-mint endpoint is non-conformant. Its gate is frozen before staged\nmaterial becomes usable; every release is preceded by the ledger write and gate CAS; and all\nreplay/idempotency coordinates bind the owner, fixed actor, lifecycle UID, instanceId, operation,\nand public nkey. A remote manager may provision a managed descendant only after the host validates\nthat its current owner equals the manager-service owner and the current manager grant; that is a\nsame-owner validation seam, not delegated signer authority. Revocation freezes the one family,\nrejects fresh material and new connections, and proceeds through the bounded renewal/verified\nrevocation policy below. It MUST NOT silently substitute static or local authority.\n\n**Platform control authority (service view).** `platform-control` is a second CLOSED,\nserver-authored manager authority view, beside and separate from `manager-service`. It lets a host\nplatform run one control manager per assigned data account without any human's session. It is not a\nprofile name, not an exchange view, and not a generic host profile: the public exchange, the\nloopback exchange, and every managed-agent secret exchange MUST refuse it as a view. Its holder is a\nplatform principal. The holder's owner is a platform owner token, `p_` followed by 26 base32-lower\ncharacters, which the host derives from the space's owner secret, the space, and the assigned\ndata-account public key. This extends the \xA72 owner-token format for this view's principals and\ntheir same-owner descendants only; everywhere else \xA72 stands. A platform owner token is disjoint\nfrom every `u_` derived owner, from `local`, from nkeys, and from the \xA713.2 mode words. The host\nMUST NOT derive it from, or bind it to, an IdP subject, and MUST NOT name a `u_` owner on this path.\nNo human is authenticated, and no ledger `supervise` scope is read or synthesized.\n\nThe view exists only while the host's current platform-control assignment names it. An assignment\nis one row `{ space, accountPublicKey, instanceId, lifecycleUid, predecessorInstanceId?,\nassignmentRevision, state }` that the platform backend alone writes. An account has at most one\ncurrent row, so it has at most one platform control instance. The host MUST read it fresh for every\nrequest under this view\nand MUST refuse, writing nothing, when it is absent or `revoked`, or when it disagrees with the\nrequest's account, instance id, lifecycle UID, or assignment revision. A failed read MUST refuse\nrather than reuse an earlier answer. The instance id and lifecycle UID are the assignment's, not\nthe caller's choice. They stay the same across the instance's restarts: a restart re-registers\nthrough the same-principal registration barrier at an advanced process epoch and is never a second\ninstance. The actors are the same fixed functions of the instance id. When the assignment names a\n`predecessorInstanceId`, the host MUST refuse `prepare` and `activate` with `failed-precondition`,\nwriting nothing, while that instance has a current `svc.manager` registration or a `frozen`\nissuance gate. The host only reads that instance's rows. It MUST NOT probe, freeze, evict, revoke,\nreopen, or deregister them. Apart from the\nholder's owner and this authorization source, the view is the `manager-service` family: the same\n`svc.manager.<instanceId>`, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>` rows, ledgered and gated as this section requires, with\n`holderPrincipal` the platform owner plus the fixed actor.\n\nThe view MUST NOT reach an instance whose issuance gate names another principal, including an\ninstance a signed-in human registered under `manager-service` and a manager registered under the\n`local` owner. There is no force or takeover path between the two views. Such an instance retires\nthrough its own owner's path before a platform instance may register. A re-registration never\nchanges an instance's owner, so the view never binds to an existing instance registered under\nanother owner. It registers its own assigned instance once that instance's predecessor has left\nthrough the predecessor's own path. Both registration proofs bind the owner, so a `manager-service` proof never\nvalidates under this view and a `platform-control` proof never validates under `manager-service`.\n\nA manager holding this view MUST run with no local signing trust and no local or custodial runtime\n(pooled control). The view confers no space signer, callout signer, owner secret, provisioner\ncredential, or launch authority. It provisions, enrolls, retires, validates, and authorizes only\nsame-owner descendants, whose owner is its own platform owner token, and grants nothing over a\nhuman owner's agents.\n\n**A read is never a fence; only a CAS write is.** JetStream `DIRECT.GET` may be served by a\nfollower or mirror and gives NO read-your-writes guarantee (a mint that *reads* the gate can\nobserve a stale `open` after a barrier froze it on the leader), so the auth bucket sets\n`allow_direct=false` (\xA713.12) and every fence here is a leader-served, revision-pinned CAS\nwrite. The mint protocol is **observe gate \u2192 write rows \u2192 CAS the gate \u2192 release**: the auth\npath reads the gate (recording `state`, `generation`, and KV `revision`), writes the\n`cred.`/`bysrc.` rows, then performs a **revision-pinned CAS update of `gate.<lifecycleUid>`\nitself at the observed revision**; a leader write that fails if the gate changed at all,\nand releases the credential only on CAS success with the gate still `open` at the same\ngeneration. On CAS failure, `frozen`/`retired`, or any generation advance it aborts and marks\nits own row revoked, never releasing. A barrier CASes the gate to `frozen` FIRST and only then\nenumerates the family. The race is closed by **serialization on one key**, not by timing or\nread freshness: freeze and mint-finalize are both CAS writes to the SAME gate key, so one\nloses; a mint that wins wrote its rows before its winning CAS, so the barrier's later\nenumeration sees them; a mint that loses never released. The ledger is written only by the\ntrusted auth path (\xA713.9 matrix; NATS binding: the auth KV, \xA713.12).\n\n**Every lifecycle operation is a cross-bucket saga, never an implied transaction.** The\nrecords head and the auth gate/ledger live in different buckets with no shared order, so\neach operation persists its durable intent (the gate `op`, above) before touching the\nsecond bucket, every crash boundary resumes the SAME operation from that intent, and the\nsafe orders are normative. **Initial activation, in order**: reserve the UID (create-only\n`uid.<lifecycleUid>`, above) \u2192 create the issuance gate `frozen` carrying the activation\n`op` (unmintable from birth; no credential is ever released under a frozen gate, per the\nunledgered-mint rule) \u2192 CAS the alias head to the new mapping (`active`) \u2192 reopen the gate\nat its first mintable generation as the operation's LAST step. A head-CAS loser\nterminalizes its own orphan gate and burns its reserved UID (never deleting either); a\ncrash after the head CAS leaves the lifecycle active-but-unreachable, and recovery resumes\nthe same activation `opId`, never minting a second UID for one activation. **Takeover**\nkeeps the barrier order above (freeze \u2192 revoke + verified-evict \u2192 epoch head CAS LAST \u2192\nreopen). **Terminal retirement** keeps the barrier order below. No other head transition\nexists: the head advances only inside these operations, and no epoch-advance or retire\nseam is exposed outside the operation that completes its barrier.\n\nBinding rule (normative): **durable** authority and state; sturdy handles, accepted goals,\ncheckpoint tokens and resumes, durable consumers and delivery state, ledger rows, bind\n`(principal, lifecycleUid)` and survive supervised restart. **Live** authority, session\ngrants, reply attribution, serve/commit ownership, additionally binds the process epoch and\ndies on restart. The alias alone authorizes nothing: a delayed or redelivered request, handle,\nor teardown that names a recycled alias fails against the replacement because the lifecycle\nUID differs. Endpoint daemons carry the same triple, with the **stable logical instance id**\n(`instanceId`, `[a-z0-9]{26,32}`, \u2265128 bits of CSPRNG entropy, persisted for the endpoint\nlifetime) as their routable identity component. `instanceId` is **minted by the provisioner,\nnever reused, and unique within `(space, endpoint)`**, the allocator records it in the\ninstance's service record by create-only CAS and rejects collisions durably. Reply\nattribution, scatter deduplication, queue ownership, and the event/timer planes all key on\nit, so its uniqueness and entropy are load-bearing, not cosmetic. `instanceId` is to an\nendpoint what `lifecycleUid` is to a managed agent, and both follow the same\nrestart-preserve / terminal-retire / epoch-fence rules.\n\n**Cross-plane scoping.** Chat/DM/presence *subjects* keep the \xA73 grammar (the alias), but\ntheir backing state is lifecycle-scoped: presence carries the current `lifecycleUid` (\xA76);\nper-instance durable consumers, pending delivery cursors, durable memberships, history\ncutoffs, and ACL/ledger rows key on `(principal, lifecycleUid)` (\xA78, \xA79). The DM subjects\n(`inst.>`) DELIBERATELY stay alias-keyed; a second implementer MUST NOT uid-scope them; the\nsuccessor cut for DMs is the ACTIVATION FRONTIER (the DM stream sequence captured at the\nlifecycle's provisioning, delivery starting at frontier+1, \xA78), and that frontier capture is\na leader-served read (the \xA713.9 read-service class), never a follower get. Explicit same-name\nrecreation inherits **no** predecessor authority or content: terminal retirement records\nper-stream sequence cutoffs before the alias is freed, messages published while no lifecycle\nis active do not flow to a later replacement, and retirement across streams is ordered and\nreconciled (never assumed atomic). **Destructive cleanup is broker-enforced where the resource is broker-addressable**: durable\nconsumer names, ACL rows, KV record keys, and membership rows are lifecycle-keyed, the UID\nis part of the resource NAME, and the teardown credential (the deprovisioner) is minted\ntarget-pinned to `(principal, lifecycleUid)` by exact name, so a credential minted for\nlifecycle A cannot even NAME lifecycle B's resources; the broker denies the stale delete\noutright. Only resources the broker cannot see (the manager's local credential/token/health\nfiles) fall back to a handler-side **delete-if-current** check carrying the retiring UID +\nexpected ownership revision. In both regimes the alias stays reserved until retirement and\ncleanup have durably completed, so a stale detached teardown can never destroy a same-name\nsuccessor. **Terminal retirement is additionally a credential barrier, in order**: CAS the issuance\ngate `open \u2192 frozen` carrying the durable retirement `op` FIRST (the bar: a staged mint\nloses the gate CAS, exactly the mint-protocol race above; the gate revision moves, so a\nmint that observed `open` cannot finalize) \u2192 CAS the head `active \u2192 retiring` bound to the\nsame `op.opId` (from this point every currency seam yields no current mapping and no\ncurrent epoch, and the alias is NOT replaceable) \u2192 revoke every\nactive credential-ledger row under the lifecycle prefix (all roots and all descendants,\ncredential ledger above), verifying revocation enforcement on every server as in the\ntakeover barrier \u2192 cluster-verified eviction of every revoked credential's live connections\n(`evictPrincipal`, as in the takeover barrier above) \u2192 **drain the target's acceptance\nobligations to quiescence** (\xA713.8: enumerate `oblig.<targetUid>.>`, settle every\nunresolved row through its decision coordinate, and re-enumerate until an enumeration\nfinds none unsettled; every writer that observed the pre-`retiring` mapping is settled\nHERE, before the cleaner below runs and before any frontier closes) \u2192 **fence the drain's\nper-op repair principals** (the commit applier, pool-route reconciler, and effects canceller\nminted inside the drain, `local.{epapl|eprec|epcan}_<opId-hash>`): cluster-verify eviction of\nany live connection under each BEFORE the cleaner and BEFORE any frontier \u2014 the applier\nespecially, whose records-KV last-value write is returned to a normal reader regardless of the\nper-stream frontier cutoff. These are self-minted data-account bearers with NO credential-ledger\nrow, so there is no connect-time deny-new: the guarantee here is **kill-live** (verified eviction\nof currently-connected principals), NOT reconnect prevention; a fresh connect within the\nbearer's TTL is the accepted residual NAMED per drain-repair profile in the \xA713.9 matrix (each\n\"RETIREMENT-FENCE residual\" row), of the same kill-live-not-deny-new class \xA713.13 fences for the\nplane connections (repair connections MUST be minted non-reconnecting so a verified eviction is\ndurable) \u2192 the trusted terminal **pool\ncleaner** settles the lifecycle's expired and orphaned pool work under a DISTINCT,\nseparately minted, exact-pool scoped profile whose pool set is this operation's **effective\ninventory**: the target's accepted `oblig.<lifecycleUid>.>` pool routes enumerated from the\nSAME drained, now-`retiring` obligation set (so no new row can appear and the enumeration is\ndeterministic across resumes). The inventory is DISCOVERY-ONLY: the barrier takes no\ncaller-supplied pool hint, so every inventory entry is an obligation-discovered pool this target\nholds accepted work on, and no pool ever enters the cleaner/executor grant without a backing\nobligation. Confinement is the EXACT per-pool effective-inventory grant plus the\nexecutor's per-item decision/horizon/retire-target checks (which bind HONEST execution, not a\ncompromised bearer): (\xA713.9\nmatrix row: bind-only on the pool's\npre-created durable, terminal-only ACK after the item's durable terminal fact, no consumer\ncreate/update/delete, no raw stream DELETE; it never holds, reuses, or impersonates the\nrevoked owner's authority, which this barrier just killed) \u2192 **retire the cleaner\ncredential itself, verified, BEFORE any frontier closes**: once the cleaner has settled the\npool and proven it quiescent (every pre-existing owner ACK drained through `AckWait`, and a\nfresh consumer read shows zero `num_pending` and zero `ack_pending`; a fire-and-forget ACK\nis confirmed with `AckSync` or re-proven, never assumed), the barrier REVOKES the cleaner's\nown bounded-lived credential and cluster-verifies eviction of its principal (`evictPrincipal`,\nexactly as for the owner above), so no in-flight cleaner can ACK a redelivery or write a\nterminal after the alias is reused; the cleaner's authority MUST be dead before the frontier\nrecords \u2192 record the\nper-stream retirement frontiers (the create-only, never-deleted `frontier.<lifecycleUid>`\nrecord, \xA713.7: one key per retired lifecycle, recorded once under this operation's `opId`) \u2192\nCAS the gate `frozen \u2192 retired` (terminal; unlike\ntakeover, retirement never reopens it) \u2192 CAS the head `retiring \u2192 retired` \u2192 only then\nfree the alias, and a successor activates only with a freshly reserved UID. `retired` on\nthe head therefore ASSERTS completed cleanup: replacing a retired predecessor needs no\nfurther proof, because nothing reaches `retired` without the barrier. Every boundary of\nthis sequence is crash-resumable through the durable `op` intent, and only the same\noperation resumes it. A **managed** lifecycle's terminal retirement has exactly one operation\nidentity, `managedRetirementOpId(uid)`, whichever entry point requests it: the participant\nmanager's `retire-lifecycle` rail request (\xA713.2) or the host's loopback managed-retire door, which\nfinishes the retirement when that manager is gone and requires the managed grant to be revoked at\nthat UID first. Both entry points create or resume the same durable operation, and one process\nnever executes it twice concurrently. Chat/DM/presence subjects stay\nalias-keyed, so without the revoke-and-verified-evict step a still-connected stale process\ncould keep speaking as the recycled alias. Where the deployment cannot revoke the credential\nor cannot verify eviction, alias reuse is **forbidden**: a same-name respawn fails loud.\nSupervised restart of the same UID retains all of it.\nIntentional role-mailbox continuity across lifecycles is only available as an explicit,\nseparately authorized transfer operation, never an accidental consequence of string reuse.\n\n### 13.2 Grammar\n\n**Endpoint names.** An endpoint name is one or more DNS-shaped labels, each matching\n`[a-z0-9]([a-z0-9-]*[a-z0-9])?` (no leading/trailing dash, no bare dashes; `_` MUST NOT\nappear in a label). Single-label names (`manager`, `delivery`) are reserved for\nendpoints shipped by this contract's reference implementation and require the space operator's\nprovisioning authority to serve; a third-party endpoint name MUST be reverse-DNS (two or more\nlabels under a domain its author controls, e.g. `com.acme.deploy`) and is mintable only under\nthe owner that registered that domain claim. In a wire subject the name is one token with `.`\nreplaced by `_` (`com_acme_deploy`); because `_` cannot appear in a label the mapping is\nbijective. Name authority is the credential, never the registry (\xA713.9). Endpoint-name\ntokens may contain `-` inside labels; they are never used to derive principal dash-form\nnames; control-surface consumer names are the \xA713.9 pinned grammars, each carrying a\nstated collision-freedom argument, and none is ever parsed back into its components, so\nthe \xA72 dash-form separator stays unambiguous.\n\n**Command tokens.** A command name is one token `[a-z0-9-]{1,32}`. The command is a validated\nsubject token so the broker enforces per-command authority (\xA713.9). `describe` and `cancel`\nare reserved command names (\xA713.7, \xA713.6).\n\n**Request subjects.** Three **addressing modes** under one kind `ep`, the mode token says\nwhere a request routes, never which verb it is (the verb rides the envelope, \xA713.3/\xA713.5):\n`one` (queue-group anycast: exactly one class member), `all` (scatter: every instance),\n`inst` (one instance by its stable triple). The `one` rail's queue group is canonically\nnamed by the endpoint-name token, and serve subscriptions to it are **queue-qualified\nonly** (\xA713.9): no credential can plain-subscribe the class rail, which is what keeps\nper-request nonces visible only to the queue-selected instance. Every request carries the caller as **three**\nforge-locked tokens `<owner>.<actor>.<uid>` (principal + lifecycle UID, \xA713.1) followed by a\ncaller-chosen unguessable **nonce** token (`[A-Za-z0-9_-]{22,64}`, \u2265128 bits of CSPRNG\nentropy; one outstanding call per nonce; reuse before the prior call resolves is a caller\nerror and the reply rail MUST treat the earlier subscription as dead); always, on calls and\ncasts alike, so one grant row covers both verbs and no shape is distinguished by counting. A\ncommand whose contract declares it **targeted** carries an **authorization-mode token** and,\nper mode, zero to three pinned target tokens between the command and the caller:\n\n| Form | Subject | Tokens |\n| --- | --- | --- |\n| Class, untargeted | `cotal.<space>.ep.one.<endpoint>.<command>.<owner>.<actor>.<uid>.<nonce>` | 10 |\n| Class, `self` | `cotal.<space>.ep.one.<endpoint>.<command>.self.<owner>.<actor>.<uid>.<nonce>` | 11 |\n| Class, `owner`/`any` | `cotal.<space>.ep.one.<endpoint>.<command>.<authz>.<tOwner>.<owner>.<actor>.<uid>.<nonce>` | 12 |\n| Class, `child`/`ledger` | `cotal.<space>.ep.one.<endpoint>.<command>.<authz>.<tOwner>.<owner>.<actor>.<uid>.<nonce>` | 12 |\n| Class, `handle` | `cotal.<space>.ep.one.<endpoint>.<command>.handle.<tOwner>.<tActor>.<tUid>.<owner>.<actor>.<uid>.<nonce>` | 14 |\n| Class, `exact` | `cotal.<space>.ep.one.<endpoint>.<command>.exact.<tOwner>.<tActor>.<tUid>.<owner>.<actor>.<uid>.<nonce>` | 14 |\n| Scatter | as class forms with mode token `all` | 10-14 |\n| Instance | `cotal.<space>.ep.inst.<endpoint>.<instanceId>.<command>[.<authz>[.<target tokens per mode>]].<owner>.<actor>.<uid>.<nonce>` | 11-15 |\n| Reply | `cotal.<space>.ep.reply.<endpoint>.<instanceId>.<epoch>.<owner>.<actor>.<uid>.<nonce>` | 11 |\n| Versioned rail (\xA713.15) | every form above with `ep.v1` in place of `ep` and `<generation>` inserted between `<uid>` and `<nonce>` | 12-17 |\n\n**The versioned rail.** An **issued** caller (\xA713.15) rides `cotal.<space>.ep.v1.\u2026`: the same\nforms, one more token, the caller's issued `<generation>` (32 lowercase hex characters), placed\nbetween `<uid>` and `<nonce>` on every request and reply form. The legacy `ep.` rail and the\n`ep.v1.` rail are disjoint subject spaces at the broker: an issued credential holds rows on the\nversioned rail only, a legacy credential holds rows on the legacy rail only, and an endpoint\nserves both. A responder derives the reply subject from the authenticated request subject on\nwhichever rail it arrived, generation included. `v1` versions the rail encoding, not the\nprotocol.\n\n**Single-owner endpoint names (normative).** An endpoint name binds to exactly ONE owner\n(\xA713.9: operator-provisioned core names, domain-owner-bound reverse-DNS names), so the name\ntoken alone determines the serving owner and instance-addressed subjects carry **no owner\ntokens**: `(endpoint, instanceId)` is the complete routable instance address. Two parties\nwanting the \"same\" name use their own reverse-DNS names; an owner-qualified shared-name form,\nif ever wanted, would be a later additive subject form, not a change to these. This trades an\nalready-forbidden expressiveness for structurally smaller subjects and credentials.\n\n**Remote manager service.** The core `manager` name remains operator-governed: a\n`manager-service` bearer (\xA713.1) does not transfer its name authority or create a generic\nuser-owned endpoint. It is the one closed user-auth exception to the single-owner endpoint rule:\nthe host may authorize one `manager` service instance whose service-record owner and serving\nprincipal are the bearer's derived owner plus fixed server-selected manager actor. The exception is\nscoped by the server-authorized lifecycle UID and opaque globally unique instance id, so the\n`(manager, instanceId)` route stays unambiguous and no registration can be mistaken for another\nowner's. The standard `ep` grammar is unchanged: the bearer reaches only that exact manager\ninstance, while the manager's own agent-control requests use the existing owner and same-owner\ndescendant checks. No endpoint name, target form, or wildcard is added for this view.\n\nThe target's **lifecycle UID is body-carried, not a subject token** (`target.lifecycleUid`,\n\xA713.3): a grant could only ever wildcard it (targets are dynamic; the UID is unknowable at\nmint time), so a token there would add zero broker enforcement while costing every targeted\ngrant row a token, the trusted validator, not the broker, compares the expected UID against\nthe current mapping (\xA713.1). The one exception is `handle` mode: at handle redemption the\ntarget's UID IS known and current, so the redemption-minted form pins the full target triple\nas subject tokens (below); pin what is knowable at mint time; body-carry only what is not.\nEvery form stays within the NATS 16-token recommendation.\n\n**Explicit discrimination (never arity counting).** The forms are distinguished by the token\nafter `<command>`: it is either one of the six reserved authorization-mode tokens (`self`,\n`owner`, `any`, `child`, `ledger`, `handle`) or the caller's owner token, and the two sets\nare disjoint by construction, because an owner token is `local` or `u_`+base32 (\xA72), never a\nbare mode word. The target-block arity then follows the mode (`self`: none;\n`owner`/`any`/`child`/`ledger`: one `<tOwner>` token; `handle`: three,\n`<tOwner>.<tActor>.<tUid>`); a closed set at a fixed position, exactly the property that\nmakes per-mode arity safe. A parser dispatches on that set; a subject matching no defined shape\nhas no sender and MUST NOT be handled.\n\n**Token bounds (normative).** On the endpoint rails every identity token is bounded:\n`owner` \u2264 64, `actor` \u2264 64, `command` \u2264 32, `endpoint` \u2264 64, nonce and ids \u2264 64 characters;\n`lifecycleUid` and `instanceId` are bounded by their single defining grammar\n`[a-z0-9]{26,32}` (\xA713.1); deliberately not restated here, so the bound cannot drift from\nthe definition. A total request or reply subject MUST NOT\nexceed 1024 bytes; implementations validate fail-loud at build time. (Transport headroom:\nthe reference deployment raises `max_control_line` to 64 KiB; the PUB line is never the\nbinding constraint; minted-credential size is, \xA713.9.)\n\n**The authorization-mode token** (`<authz>`) makes the authority gradient explicit and\nbroker-enforced where it is statically expressible, and honestly validator-primary where it is\nnot. Seven modes:\n\n- `self`, the target IS the caller: the form carries **no target tokens and no body\n  `target`** (a supplied one is `target-mismatch`, never ignored); the endpoint derives the\n  target from the broker-authenticated caller triple in the same subject. Fully\n  broker-confined, including the lifecycle UID, because the caller's own `<uid>` token is\n  the target's UID, forge-locked by the mint: a stale lifecycle's credential cannot even\n  publish the successor's subject.\n- `owner`, owner-domain: the target block is `<authz>.<tOwner>` (ONE target token); grants\n  pin `<tOwner>` to the caller's own owner (standing mints; a handle redemption instead pins\n  the issuer-signed target owner, \xA713.6). The target actor and expected lifecycle UID are\n  body-carried (`target`) and validator-checked against the current mapping, the broker\n  cannot express \"any actor under my owner, currently mapped to this UID\". An `owner`-mode\n  grant is NEVER minted with a wildcard target owner. Broker-confined on the owner; validator\n  on the rest.\n- `any`, unrestricted target owner (`<authz>.<tOwner>` with `*`): a distinct mode mintable\n  only for operator/admin capabilities, so no widening of an `owner` grant can ever reach\n  it. Validator-checked target as for `owner`.\n- `handle`, **redemption-minted only** (\xA713.6): the target block is\n  `handle.<tOwner>.<tActor>.<tUid>` (THREE target tokens), each a literal pinned at\n  redemption from the issuer-signed grant against the then-current mapping. Never a standing\n  capability, never wildcarded. Broker-confined on the full target triple; the validator\n  re-checks only currency; a subject `<tUid>` that no longer matches the current mapping is\n  `expired`.\n- `exact`, **privileged exact incarnation, minted only through its owning profile** (Cotal\n  #399): the target block is `exact.<tOwner>.<tActor>.<tUid>` (THREE target tokens), the same\n  literal-triple shape `handle` carries, minus the redemption promise. There is no issuer-signed\n  artifact, no redemption step, and no `sourceChain`; the row is built directly by the profile\n  that owns this command under root authority for one target it names, never a standing\n  capability, never wildcarded. Broker-confined on the full target triple, exactly as `handle`;\n  the validator re-checks only currency, and a subject `<tUid>` that no longer matches the\n  current mapping is `expired`. A generic reader of this mode infers precisely a privileged,\n  grant-pinned exact triple with a current-mapping check, and nothing more.\n- `child`, static-mesh own-child (`spawner == caller`): a **distinct trusted-validator form**.\n  The grant means \"may ask this validator\", not \"already authorized\"; the handler MUST\n  fresh-check the immutable spawner relation against durable state and fail closed. Its\n  `<tOwner>` ceiling is the caller's own owner, as for `owner` mode (a static-mesh child\n  shares its spawner's owner).\n- `ledger`, fresh-ledger escalation: a distinct trusted-validator form; the handler MUST\n  fresh-read the authorization ledger and fail closed on lookup failure, timeout, or absence.\n  Its grants pin literal `<tOwner>` values named at mint; a wildcard target owner in `ledger`\n  mode is mintable only for operator/admin profiles.\n\n`any`, `child`, `ledger`, `handle`, and `exact` are never wildcard-reachable from a `self`/`owner`\ngrant (distinct token \u21D2 distinct subject \u21D2 distinct grant row). A handler MUST resolve the target (the\nrevision-pinned `(alias, lifecycleUid)` mapping, \xA713.1) immediately before effect and reject\nany request whose body target disagrees with the subject target tokens (`target-mismatch`) or\nwhose expected target lifecycle UID does not match the current mapping (`expired`). The\nsubject, never the body, is the authorization boundary; handler policy only narrows.\n\n**Replies.** Every reply rides the dedicated reply rail above, **deterministically derived\nfrom the authenticated request subject**: the responder copies the caller triple and nonce\nfrom the request subject and prefixes its own endpoint/instance/epoch tokens (the owner is\ndetermined by the endpoint name; no owner tokens appear). A responder\nMUST ignore any transport- or payload-supplied reply target (the confused-deputy boundary).\nThe grants are exact-arity, no `>` tail admits subjects outside the grammar: the caller's\nread grant is its own rail (`ep.reply.*.*.*.<owner>.<actor>.<uid>.*`), so it reads only\nreplies addressed to it; the responder's publish grant pins its own instance triple and\nepoch (`ep.reply.<endpoint>.<iId>.<epoch>.*.*.*.*`), so the answering instance and\nepoch are read off the broker-authenticated reply subject, never trusted from the payload.\nTwo properties, enforced differently, stated precisely: **attribution** (who answered) is\nbroker-enforced by the responder's pinned prefix; **addressing** (whom a responder may\nanswer) is capability-by-secret, the responder's grant spans all caller suffixes, and what\nconfines it to the requester is possession of the unguessable per-request nonce, which only\nthe request's recipients hold. A stale process (superseded epoch) publishes attributably\nstale replies that callers reject; scatter gathers additionally reject replies from\ninstances outside the frozen expected set (\xA713.5).\n\n**Incarnation admission (the bound-incarnation fence).** Rejecting a reply is a REPORT, not a\nguard: it happens after the responder has already handled the request. On the class rail the\nqueue picks the responder, so a caller that resolved incarnation B can have its command executed\nby A and then be told the call failed \u2014 with no way to say whether any effect landed. A caller\nthat will accept an effect only from the incarnation it resolved therefore declares it in the\nrequest (`bind`, \xA713.3), and a responder that is not that incarnation **MUST refuse it at the\npre-effect seam** \u2014 before args validation, before target resolution, and before the \xA713.6/\xA713.10\ngoverned gate, which may consume a one-use payment proof. The refusal carries\n`ai.cotal.ep.bind-refused` and means the command did not run, so re-resolving and re-issuing\ncannot duplicate an effect; that is the distinction `ai.cotal.ep.unbound-responder` (raised by the\ncaller, on the reply) cannot make. `bind` is a caller declaration and never authority: it can only\nnarrow a request the subject already routed, and attribution still comes from the reply subject \u2014\na refusal attributed to the very incarnation the caller bound is incoherent and MUST be rejected\n(`internal`) rather than honored. A responder that does not implement the fence ignores the field\n(\xA75) and executes; the caller-side check remains the only protection in that skewed pair.\n\nThe **caller's** process epoch is\ndeliberately NOT encoded in the rails: reply consumption binds to the requesting process\nbecause a caller MUST subscribe the exact concrete nonce subject before publishing a call\nand MUST NOT persist nonces; a restarted successor never holds the predecessor's nonce\nsubscriptions, so in-flight calls die with the process (they are ephemeral by definition)\nand a late reply is unreadable rather than misdelivered.\n\n**Event and journal subjects.** Endpoint-published planes, captured by per-space streams\n(\xA713.12); the publishing instance's identity is forge-locked into the subject:\n\n| Plane | Subject |\n| --- | --- |\n| Events | `cotal.<space>.epe.<endpoint>.<instanceId>.<epoch>.<topic...>` |\n| Canonical facts | `cotal.<space>.epf.<endpoint>.<topic...>` |\n| Submissions | `cotal.<space>.epj.<endpoint>.<command>[.<authz>[.<target tokens per mode>]].<owner>.<actor>.<uid>` |\n| Timers | `cotal.<space>.ept.<endpoint>.<instanceId>.<epoch>.<timerId>.<schedule\\|armed\\|fire>` |\n| Record writes | `cotal.<space>.epr.<endpoint>.<instanceId>.<epoch>.<kind>.<qualifier...>` (mediated record-writer ingress; the instance's epoch-pinned rail for `svc`/`goal`/`cp` status writes; consumed ONLY by the record writer, which reads the writing epoch from the broker-authenticated subject, never from payload, \xA713.9) |\n| Contract artifacts | `cotal.<space>.epc.<digest-hex>` (one immutable artifact per subject; `<digest-hex>` is the artifact's SHA-256 hex, 64 chars; the `sha256:` prefix is not a subject token; \xA713.7) |\n| Work pools | `cotal.<space>.epw.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (one item per subject; the trailing four tokens are the item's **acceptance identity**; the accepted submission's caller triple + request id, \xA713.6) |\n| Sessions | `cotal.<space>.eps.<endpoint>.<sessionId>.<epoch>.<in\\|out>` |\n\nEvents carry the publishing instance's **epoch as a subject token**, pinned by the serve\ngrant, so a superseded process cannot emit progress indistinguishable from the current\nincarnation's; readers match the current (or goal-accepted) epoch and treat stale-epoch\nevents as attributably stale. A **targeted** journal command carries the same authz/target\nblock in its submission subject as its request forms, so the broker confines targeted\njournal work exactly as it confines calls; the canonicalizer additionally requires exact\nbody/subject agreement before acceptance. Timers use three forms: `.schedule` is the\ninstance-published **schedule request**, captured by a stream with message schedules\nDISABLED, so any client-set scheduling header is inert bytes, and the mediated timer writer\nrejects a request carrying one; `.armed` holds the **authoritative schedule message**,\npublished only by the mediated timer writer (\xA713.9), which derives the ADR-51\n`Nats-Schedule-Target`, the sibling `.fire` subject, from the broker-authenticated\nREQUEST subject's own tokens, never from any payload or header (a schedule's target MUST\ndiffer from its publish subject per ADR-51; replacement is the writer's same-subject\npublish on `.armed`); `.fire` is where fires appear. An instance's serve grant covers\n**only `.schedule`** (epoch-pinned); no client credential holds `.armed` or `.fire`\npublish; fired messages are written by the broker's scheduler alone, and the handler\nvalidates the carried `(timerId, generation)` against current status AND\n`now \u2265 the authoritative deadline` AND that the broker-authored scheduler-origin header\nnames its own exact sibling `.armed` subject (\xA713.12) before acting.\n\nReserved event topics: `ev.<cluster>.<event>` (cluster events), `goal.<cOwner>.<cActor>.\n<cUid>.<goalId>.<t>` (per-goal action progress; the caller identity in the subject gives\nmint-time read containment), `cp.<token>.<t>` (checkpoint transitions). Reserved fact topics:\n`dec.<cOwner>.<cActor>.<cUid>.<id>` (canonical decisions (accepted/rejected) caller-scoped, \xA713.4), `quar.<sourceSeq>` (poison quarantine, \xA713.4; its own family,\ndisjoint from the caller-id `dec` namespace by construction), `goal.<cOwner>.<cActor>.<cUid>.<goalId>.result` (terminal\nresults), `wrk.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (per-work-item terminal results,\nkeyed by the item's acceptance identity, \xA713.5/\xA713.6), `eff.<cOwner>.<cActor>.<cUid>.<id>`\n(per-request effect-complete facts for non-action effects commands, \xA713.9), `cp.<token>` (one-use checkpoint\nresume, journaled by create-only CAS, \xA713.6),\n`receipt.<cOwner>.<cActor>.<cUid>.<id>.<sourceSeq>`\n(caller-scoped; request ids are caller-chosen, so an endpoint-wide `receipt.<id>` would\nlet two callers collide and read each other's receipts, and **execution-scoped**: the\naccepted submission's `sourceSeq` is unique per execution, so a request id lawfully reused\nafter its decision retention expires (\xA713.4) mints a NEW receipt subject instead of\nappending to the old one, where a last-by-subject read would have hidden the earlier\nreceipt for the rest of its 90-day retention). Submissions are publishable directly by capability holders\nand are **explicitly untrusted** (\xA713.4); canonical fact subjects are publishable only by\ntheir mediated writer (\xA713.9). `<id>`, `<goalId>`, `<timerId>`, `<token>`, `<sessionId>` are\nsingle tokens `[A-Za-z0-9_-]{1,64}`.\n\nThe v0 subjects `cotal.<space>.ctl.>` and `cotal.<space>.control.>` are retired: nothing\nserves them and no post-cut credential carries a grant on them. `trace.<instance>` remains reserved,\nunchanged. `<pool>` is a single token `[a-z0-9-]{1,32}` (command-token grammar).\n\n### 13.3 Envelope\n\nRequests, replies, submissions, events, facts, and progress payloads are UTF-8 JSON. The\nenvelope is versioned and typed; `ControlRequest`/`ControlReply` are deleted.\n\n`EndpointRequest`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `v` | `1` | MUST | envelope schema version (independent of the wire `protocolVersion`; the envelope starts at its own v1 inside the v0.4 revision); other values rejected (`unsupported-version`) |\n| `id` | string | MUST | caller-chosen request id, `[A-Za-z0-9_-]{1,64}`; the idempotency key at the declared scope (\xA713.8), realized on journaled planes by the caller-scoped decision CAS (\xA713.4), never by a transport header |\n| `op` | object | MUST | `{ endpoint, command, inputDigest, outputDigest }`; MUST agree with the subject (`op-mismatch`). The digests bind the invocation to the described contract and are **both REQUIRED on every command except `describe`** (the discovery bootstrap), unconditional, because every command declares both schemas: a side with no payload declares the canonical void schema (\xA713.7), whose digest exists like any other. A serving member rejects a missing digest (`contract-mismatch`) before any effect, and one that cannot honor a pinned digest replies `contract-mismatch`, never coerces |\n| `class` | `ephemeral` \\| `journal` | MUST | the submission's declared delivery contract; MUST equal the command's contract class (`class-mismatch`); immutable per submission. (`record` is a state contract, never a request class; the action composite is a command marker, not a class; an action command's submissions are `journal`) |\n| `replyExpected` | boolean | MUST | the verb: `true` = call (a reply is expected on the reply rail; `deadlineMs` required; the caller subscribes its exact nonce before publishing), `false` = cast (fire-and-forget; a responder MUST NOT reply). The subject shape is identical for both; the verb never changes the grammar |\n| `goalId` | string | action commands | MUST for a command whose contract declares the action composite: the client-generated goal id (\xA713.6); absent otherwise. `id` remains the per-request idempotency key |\n| `target` | object | per mode | `{ owner, actor, lifecycleUid, mappingRevision? }`. **Absent for `self`** (and for untargeted ops): a supplied one is `target-mismatch`, never ignored. **Required for `owner`/`any`/`child`/`ledger`/`handle`**: `owner` MUST equal the subject `<tOwner>` token (`target-mismatch`); `actor` and `lifecycleUid` are validator-compared against the current mapping (`expired` on mismatch), and in `handle` mode MUST additionally equal the subject `<tActor>`/`<tUid>` tokens (`target-mismatch`); `mappingRevision`, when present, additionally pins the exact mapping revision the caller observed |\n| `bind` | object | MAY | `{ instanceId, epoch }` \u2014 the incarnation the caller's `describe` resolved against. A responder whose own `(instanceId, epoch)` differs **MUST refuse before any effect**, at the pre-effect seam and ahead of the governed gate: `failed-precondition` when a different instance received it, `expired` when the same instance is at another epoch, both carrying `details[].kind = ai.cotal.ep.bind-refused`, which asserts the command **did not run**. **Absent on `describe`** (the bootstrap that produces the bind; a supplied one is `bad-request`) and **absent on the scatter rail** (which addresses every incarnation; `bad-request`). On the `inst` rail it MUST name the subject's instance (`bad-request` otherwise) and adds the epoch the subject grammar has no token for. It confers nothing and can only make a responder the subject already reached refuse, so it satisfies monotonic attenuation |\n| `args` | object | MAY | validated against the input schema before any effect (`bad-request`) |\n| `from` | `EndpointRef` | MUST | as \xA75; `from.id` MUST equal the subject sender principal, and the sender UID token MUST match the caller's minted lifecycle UID (broker-enforced by the grant) |\n| `deadlineMs` | number | MUST for call/scatter and journal submissions | caller deadline budget; bounded, never unbounded. On a journal-class submission it is the **decision deadline**: the bound within which the caller expects its durable decision fact (\xA713.4) |\n| `correlation` | object | MAY | `{ traceparent?, tracestate?, baggage? }` per W3C Trace Context; propagated to downstream calls, events, facts, receipts |\n| `auth` | string | MAY | opaque signed authorization-context slot (capability handle, obligations, payment proof). Opaque to the transport, never to identity: its **`authDigest`** (\xA713.4 fingerprint) is `sha256:<hex>` over the UTF-8 bytes of this string **exactly as carried**; the slot is already a canonical signed artifact, so it is digested as bytes, never re-canonicalized, and is absent from the fingerprint iff `auth` is absent |\n\n`EndpointReply`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `v` | `1` | MUST | |\n| `id` | string | MUST | echoes the request `id` |\n| `ok` | boolean | MUST | |\n| `data` | any JSON | MAY | present iff `ok`; validated against the output schema |\n| `error` | object | iff `!ok` | `{ code, message, details?[], outcome? }`; codes below; `details[]` entries carry reverse-DNS `kind`; `outcome` per **Effect outcome** below |\n| `receipt` | string | MAY | opaque signed receipt slot (\xA713.10) |\n\n**Effect outcome.** An error reply MAY carry `error.outcome`, one of `executed`, `not-executed`,\nor `unknown`, stating whether the command's effect occurred. It is emitted by the **responder**,\nwhich is the only party that knows: a responder that refuses BEFORE dispatching to the handler\nMUST carry `not-executed`, and one that refuses AFTER the handler has run MUST carry `executed`.\nA responder that cannot distinguish the two MUST carry `unknown` rather than guess. An error\nreply that omits `outcome` MUST be read as `unknown`.\n\n`outcome` describes a reply, and only a reply. A refusal a CALLER raises locally is not an\n`EndpointReply` and carries no `outcome` field. It does not follow that the caller knows nothing:\nit MUST classify the refusal from what it observed, and only one of the four cases below is\ngenuinely `unknown`.\n\n- **Refused before publication** \u2014 the request was never put on the wire. The caller knows the\n  effect did not occur and MUST classify it `not-executed`. Treating this as `unknown` suppresses\n  a retry that is provably safe, including for a `write`.\n- **Refused while holding a reply** \u2014 the caller parsed a reply and then rejected it for a reason\n  of its own, the \xA713.2 post-reply currency check being the case in this document. What the caller\n  knows comes from the reply it holds: an `ok:true` reply means the handler ran to completion, so\n  the refusal is `executed`; an `ok:false` reply carries the responder's own `outcome`, which the\n  caller MUST adopt rather than overwrite. Discarding a held reply's outcome because the caller\n  went on to reject the reply loses the one fact the responder was in a position to state.\n- **Answered by the broker with no responders** \u2014 the request subject had zero subscribers, and\n  the broker says so on the reserved no-responders sentinel. That is a positive, broker-attested\n  fact that nothing received the request, so it is `not-executed`, not merely unanswered. A caller\n  MUST trust it ONLY on that reserved sentinel, which carries no responder publish grant: the same\n  status on an ordinary reply subject is a responder's own claim and proves nothing about\n  delivery.\n- **No reply observed** \u2014 a deadline that expires with no answer at all, a transport failure after\n  publication, any path where the caller cannot tell whether the request was handled. This is\n  `unknown`, and it is the only local case that is.\n\nA caller **MUST NOT infer execution from the mere arrival of a reply**: a reply proves the request\nwas HANDLED, never that it executed. The two differ on every path where a responder refuses before\nthe handler \u2014 the version, class, target, sender, authz, contract, and guard checks all publish\n`ok:false` having executed nothing, and each of those replies says so in its own `outcome`.\n\n`outcome` exists because a refusal code alone cannot carry this fact: the same code and the same\nmessage are correct for a request that ran and for one that never left, and a caller that cannot\ntell them apart and retries duplicates the effect. `effect` (\xA713.7) tells a client whether a\nrepeat is safe; `outcome` tells the caller what already happened. Neither substitutes for the\nother, and a `write` command refused with `unknown` is precisely the case where no automatic\nrecovery is available and the decision belongs to the caller.\n\n`outcome` is NOT a goal's terminal state. An action accepted under \xA713.6 reports its result as a\ngoal fact; an accepted action whose caller then loses its follow has an `outcome` of `executed`\nfor the SUBMISSION and no terminal state at all, which are different facts about different\nthings. `outcome` MUST NOT be used to report, replace, or summarize a goal outcome.\n\nThe answering instance, its epoch, and the addressee are read from the **reply subject**\n(\xA713.2), not from payload fields; a payload claim of either is advisory display data only.\n\nEvery other plane is typed too: a journaled **submission** is an `EndpointRequest` (same\nenvelope, published to `epj`); an **event** (incl. per-goal progress) is\n`{ v: 1, topic, ts, data, correlation? }`; an **acceptance fact** is the `AcceptanceFact` of\n\xA713.4; a **terminal result fact** carries the goal's terminal state (one of the five\nterminal values of \xA713.6), outcome digest, and\nresult payload (or its digest-pinned reference). All are runtime-validated at their\nconsuming boundary.\n\n**Monotonic attenuation (invariant).** Envelope content, the `auth` slot, a handle,\nobligations; may only narrow what the presenting credential already permits, never widen it.\nA handler that honors envelope content as authority beyond the broker grant is non-conformant.\nAuthority *conferral* exists only as trusted redemption (\xA713.6 capability handle).\n\n**Error catalog.** `code` is one token: `bad-request`, `unsupported-version`, `op-mismatch`,\n`class-mismatch`, `target-mismatch`, `sender-mismatch`, `unauthenticated`,\n`permission-denied`, `not-found`, `already-exists`, `conflict` (CAS/fencing loss,\nfingerprint conflict, duplicate resume), `contract-mismatch`, `contract-invalid` (schema\noutside the profile / over budget at registration), `failed-precondition`,\n`deadline-exceeded`, `cancelled`, `expired` (lease, handle, lifecycle UID, epoch, token),\n`unavailable` (no responder), `unimplemented`, `resource-exhausted`, `internal`. Extensions\nadd codes only under reverse-DNS. A `code` (catalog or extension) is one token of at\nmost **64 bytes**, so every fact shape that embeds one (`RejectionFact`, `QuarantineFact`)\nstays bounded by construction and the \xA713.12 fact fixture is a true worst case.\n\n### 13.4 Delivery contracts\n\nThree delivery contracts, chosen per command class, declared in the contract, immutable per\nsubmission. Decision rule: crash means \"just re-ask\" \u2192 **ephemeral**; long-lived state\nsomething converges on \u2192 **record**; must survive restart, be audited, metered, or\ncompensated \u2192 **journal**. Wrong-class submission fails loud.\n\n**Ephemeral**, request/reply on the `ep` rails; no broker persistence; at-most-once effect\nunless the command is idempotent by `id`. No-responder is a loud `unavailable`.\n\n**Record**, a `{kind, schema, spec, status, meta}` resource in the per-space records bucket,\nstored as **two keys with independent revisions**: `<key>.spec` and `<key>.status`. The split\nis the broker-enforced writer boundary: the spec-writer and status-writer roles hold publish\ngrants on their own key only (per-kind writer table, \xA713.9). Writes use per-key CAS; a lost\nrace is a loud `conflict`. The merged logical read returns both\nrevisions and carries `status.observedSpecRevision`; a reader treats\n`observedSpecRevision < spec.revision` as a stale-but-valid level-triggered projection, not\nan error, and `observedSpecRevision > spec.revision` (a lagging spec read, possible across\nreplica freshness points) as its own signal to re-read the spec key, bounded retries until\ncaught up or the caller's deadline, never trusting the mismatched pair. Watch delivers\ncurrent values then deltas per key; a watcher that falls behind MUST re-read both keys and\nresume, never patch forward across a gap. Records are\nbounded (\xA713.8).\n\n**Journal**, an explicitly **untrusted at-least-once submission log** feeding **canonical\naccepted-fact subjects** with a mediated writer; effects consume only canonical facts, never\nraw submissions.\n\n1. A journaled submission is published to the submission plane (`epj`) as a **plain append**:\n   submitters MUST NOT set `Nats-Msg-Id`, and native dedupe is **not relied upon**, the\n   server does not accept a zero duplicate window (\xA713.12), so the reference config sets the\n   server minimum and the guarantee rests on the header rule, not the window: a conformant\n   submission carries no dedupe header and cannot be suppressed by one. Native broker dedupe\n   keys on a caller-set header value compared\n   **stream-wide**, so on a shared submissions stream any writer could pre-seed a predicted\n   header value from its own allowed subject and silently suppress another caller's first\n   submission for a full dedupe window, a cross-caller denial that no \"advisory\" framing\n   makes safe; with the MUST NOT in force, a hostile header-bearing publish can suppress only\n   another non-conformant header-bearing write. Transport retries therefore simply append\n   again; the caller-scoped decision\n   CAS below resolves every copy to one decision. Submission subjects and fact subjects are\n   disjoint by construction (\xA713.2), so a submission credential cannot write a fact.\n2. The **semantic fingerprint** covers every effect-defining dimension, the fingerprint\n   object is `{endpoint, command,\n   class, authz?, target?: {owner, actor, lifecycleUid, mappingRevision?}, inputDigest,\n   outputDigest, args, authDigest?, caller: {id, lifecycleUid}, goalId?, id}`, and the\n   fingerprint VALUE is that object's `sha256:<hex>` content digest per \xA713.7 (strict\n   RFC 8785 over I-JSON, the SAME canonicalization every contract artifact uses; one\n   canonicalizer, never a second): absent optional fields are OMITTED from the object, never\n   written `null`, so two implementations digest identical bytes, which also makes the\n   fingerprint **computable for EVERY parseable submission**, however incomplete: a\n   parseable envelope missing `class` or digests fingerprints the subset it carries and is\n   rejected with that fingerprint. **\"Parseable\" here means canonicalizable I-JSON**, not\n   merely syntactically valid JSON: bytes that parse but cannot be canonicalized, duplicate\n   object names, a lone surrogate, a non-finite or out-of-I-JSON-range number; have no\n   interoperable RFC 8785 form and therefore no fingerprint, so they take the quarantine\n   path exactly as unparseable bytes and an invalid `id` do (\xA713.4 item 3: raw-byte digest,\n   no fingerprint). Every submission thus has exactly one terminal path. Same id +\n   same fingerprint is the same request (idempotent, first-wins); same id + different\n   fingerprint (including the same args retargeted at a different lifecycle) is a loud\n   `conflict`, never accepted or effected.\n3. The **canonicalizer**, the narrowly scoped mediated writer for this endpoint's facts\n   (\xA713.9); consumes the submission plane through a **normative durable `AckExplicit`\n   consumer** and acks a submission ONLY after a durable decision fact exists, and, for a\n   pool-admitted acceptance, ONLY after the \xA713.6 EPW enqueue create has additionally\n   succeeded (or lost its CAS to an already-present entry): a crash anywhere between\n   acceptance and enqueue therefore redelivers the submission, and the reconciliation\n   predicate resolves the redelivered copy; recovery never has to DISCOVER orphaned\n   acceptances, because an acceptance without its enqueue is by construction an unacked\n   submission that comes back. A crash before\n   the fact redelivers the submission; a crash after it observes the CAS winner on\n   redelivery. It validates each submission (schema, body/subject agreement incl. the target\n   block, authorization per \xA713.6, and (for work-pool commands) pool admission/capacity\n   BEFORE acceptance) and then decides each request exactly once by publishing a\n   **decision fact** to the caller-scoped subject\n   `epf.<endpoint>.dec.<cOwner>.<cActor>.<cUid>.<id>` with create-only CAS (expected last\n   sequence on the subject = 0), so distinct callers can never squat each other's ids. **For\n   an action command the canonicalizer additionally binds the goal before accepting**: it\n   create-only-CASes a **goal-bind fact** `epf.<endpoint>.goal.<cOwner>.<cActor>.<cUid>.<goalId>.bind`\n   carrying the accepted fingerprint, and rejects (`conflict`) any later submission whose\n   `goalId` matches but whose fingerprint differs, so two distinct `id`s naming one `goalId`\n   cannot both be accepted-and-effected (the decision CAS keys on `id`, which alone would let\n   both through; the goal-bind CAS keys on `goalId`, which stops the second BEFORE acceptance\n   and effect, not at the terminal-result stage where the effect has already happened).\n   The decision is `accepted` or `rejected` (with the catalog error); **rejection is as\n   durable, caller-readable, and idempotent as acceptance**, so a permanently invalid\n   submission is distinguishable from a lost one. First decision wins atomically; a later\n   attempt fails its CAS and reads the existing fact. There is no append-then-memo pair to\n   crash between. The canonicalizer is a **singleton per endpoint** (one active principal,\n   epoch-fenced like any serve identity, recovered through the \xA713.1 takeover barrier):\n   admission checks (pool capacity for work-pool commands) are thereby serialized with the\n   decisions they gate, so two canonicalizers cannot both admit the last slot; capacity is\n   consumed by the acceptance itself, never checked apart from it. A submission that cannot\n   yield a decision key; bytes that are not canonicalizable I-JSON (unparseable, duplicate\n   object names, lone surrogate, out-of-range number), or no `id` within the token\n   grammar; **or bytes that breach the command's declared `admissionCeiling`** (\xA713.7): raw\n   size over `maxBytes`, nesting over `maxDepth`, or member count over `maxItems`; is\n   **quarantined, never redelivered forever**: the canonicalizer publishes a\n   **`QuarantineFact`** to the disjoint quarantine family\n   `epf.<endpoint>.quar.<sourceSeq>` (\xA713.2); keyed by the source sequence, which exists\n   for every stored copy by construction, in a family that shares no namespace with\n   caller-chosen `dec` ids, so no legal request id can collide with a quarantine key, with\n   create-only CAS, and terminally acks\n   (`AckTerm`) the submission ONLY after that fact durably exists (or its CAS loss shows it\n   already does), so a poison message cannot pin `MaxAckPending` and the\n   fact-before-terminal-ack rule holds on the poison path exactly as on the decision path.\n   `QuarantineFact` = `{ v: 1, decision: \"quarantined\", sourceSeq, submissionDigest (the\n   `sha256:<hex>` digest of the raw stored bytes, \xA713.7), error: { code (catalog token),\n   detail? (\u2264 256 bytes) }, caller?: { id, lifecycleUid } (from the broker-authenticated\n   submission subject, when it parses), ts }`, every field bounded or fixed-size, so the\n   fact fits by construction; it never carries the poison bytes themselves.\n4. Journal submissions set `replyExpected: false`; the caller **observes its decision** by\n   watching/reading its own decision subtree (`epf.<endpoint>.dec.<its triple>.>`, a\n   caller-scoped read grant minted with every journal capability). An action command's\n   accept/reject is exactly its decision fact, expected within the submission deadline.\n5. The **acceptance fact is self-sufficient for effect and replay** (`AcceptanceFact`, the\n   `accepted` decision): `{ v: 1, id, decision: \"accepted\", fingerprint, request: <the\n   canonical EndpointRequest, args INLINE, bounded by the broker's max_payload; a submission\n   too large is refused loudly with resource-exhausted, never spilled into storage>, caller:\n   {id, lifecycleUid}, target?: {owner, actor, lifecycleUid, mappingRevision},\n   contractDigests: {input, output}, authzDecision: {revision, epoch},\n   route: \"effects\" | `pool.<pool>` (the acceptance's SINGLE execution route, decided by\n   the canonicalizer at admission: a pool-routed acceptance is executed by the pool's\n   worker path (\xA713.5) and the effects consumers MUST ack it without effect; an\n   effects-routed acceptance is executed by exactly one instance off the shared effects\n   durable (\xA713.9). No acceptance is ever executed twice, because the fact names its route),\n   readinessDeadlineMs?: <the acceptance-relative readiness bound, present iff the command\n   declares bounded readiness, \xA713.6; persisted HERE because it is goal state, not the\n   request's decision deadline>,\n   workExpiry?: <absolute expiry of a pool-routed item, present iff `route` is a pool, \xA713.8;\n   survives reconciliation re-enqueue unchanged>, sourceSeq, ts }`. A `target`-bearing\n   acceptance (work bound to a lifecycle) publishes ONLY after its target-indexed\n   obligation row exists AND only under an unexpired admission proof the mediator issued\n   for that row (\xA713.8: proof issuance is the post-create currency recheck, so a row whose\n   target or policy moved between create and recheck never admits; the fact's durable\n   address is caller-scoped, so the obligation row, keyed target-first, is the ONLY\n   target-enumerable record a retirement barrier can drain;\n   `target.mappingRevision` is provenance, never a fence). The\n   canonicalizer preflights the **serialized decision fact**, not merely the inline args,\n   against `max_payload`: a submission whose acceptance fact would not fit is rejected\n   `resource-exhausted`, and the rejection fact always fits by construction: every field\n   is bounded or fixed-size (the operator floor assertion covers the maximum serialized\n   rejection/quarantine fact, \xA713.12):\n   `RejectionFact` = `{ v: 1, id, decision: \"rejected\", fingerprint, error: { code (catalog\n   token), detail? (\u2264 256 bytes) }, caller: {id, lifecycleUid}, authzDecision?: {revision,\n   epoch}, sourceSeq,\n   ts }`; the fingerprint and the catalog error, never the args (a parseable submission\n   always yields the fingerprint; the unparseable/no-id case is the QuarantineFact above,\n   which requires neither `id` nor `fingerprint`). Digest-pinned\n   references inside a fact may name **only already-published public contract artifacts**,\n   never per-request payloads: the contract store is public, immutable, and permanent,\n   the opposite lifecycle of private, horizon-bounded request content (a large-payload\n   facility, if ever needed, is its own future primitive with its own store, retention, and\n   \xA713.9 rows). Effects and replay read the fact, never the raw submission (a TOCTOU re-read\n   of the untrusted log is non-conformant).\n6. Decision facts/tombstones are retained at least the declared **idempotency horizon**\n   (default 24h, space-configurable) AND longer than the maximum submission-log retention\n   plus recovery/redelivery lag; otherwise a rebuilt canonicalizer could re-accept an old\n   submission still sitting in the log as new work. The horizon is **realized by decision\n   retention, not by a clock**: the create-only CAS returns the recorded decision for exactly\n   as long as the fact exists, and a reused id becomes new work only once retention has\n   evicted the old fact and freed its subject; there is no separate time rule for the CAS\n   to disagree with. The \xA713.12 retention floor states the horizon by OUTCOME: no removal\n   cause may drop a decision fact or tombstone before it. The canonical subjects are the authority (D12) for anything\n   auditable, metered, compensated, effected, or replayed. Ordering is per-subject;\n   consumers never assume cross-subject order.\n\n**Events are not facts.** Cluster events and per-goal progress (`epe`) are direct,\nepoch-fenced, instance-published notifications on a durable, ordered, replayable stream;\nthat is the sense in which they ride the journal contract. They do NOT pass through the\ncanonicalizer, carry no acceptance semantics, and MUST NOT drive effects that require\ncanonical acceptance; anything auditable/metered/compensated goes through submissions and\nfacts.\n\n### 13.5 Verbs\n\n- **call**, bounded request/reply (`replyExpected: true`, `deadlineMs` mandatory). On the\n  `one` rail it is queue-group anycast; on `inst` it addresses one stable instance. No\n  responder \u2192 `unavailable`.\n- **cast**, the same subjects and grants (`replyExpected: false`): fire-and-forget,\n  at-most-once, the responder MUST NOT reply and the caller never reads the rail (the nonce\n  is present but unused). A cast to a journaled command is `class-mismatch`; journaled work\n  goes through submissions. In the NATS binding a publish violation is asynchronous \u2014 the\n  publish call returns normally while the broker refuses \u2014 so a caller-side cast\n  implementation MUST watch the connection status for a violation on the cast's own subject\n  and raise `permission-denied` naming that subject, exactly as a call does; a cast\n  implementation MUST NOT resolve as though a refused publish had been cast.\n- **watch**; observe a record (KV watch; fell-behind \u21D2 re-read, \xA713.4) or an event topic\n  (live subscription within the read grant plus filtered replay from the event stream).\n  Per-key and per-goal subjects carry read containment; a watch grant names the exact subtree.\n- **claim**, competitive at-most-one-winner acquisition from a durable work pool (`epw`),\n  **owner-mediated**: the pool's owning endpoint holds the pool's single `AckExplicit` pull\n  consumer (\xA713.12); workers hold **no** JetStream grant on the pool and acquire, renew, and\n  settle work exclusively through the owning endpoint's reserved **`lease`** and **`commit`**\n  commands on the ordinary `ep` rails. This is the only shape that satisfies both claim\n  invariants at once: the delivery's ack token never leaves the party allowed to use it, and\n  the attempt binding is **owner-recorded at assignment** rather than asserted by the worker\n  (a worker-carried \"sequence + attempt\" proves nothing about delivery; an owner assignment\n  does). The stored pool message is **work identity and input only, never the authoritative\n  lease**: broker redelivery re-delivers the same stored bytes, so a token in the payload\n  cannot fence, and the consumer's `ack_wait` is the broker's redelivery-to-owner timer only,\n  never the lease. `lease` (call): the owner fetches the next stored item and records the\n  lease `{item, sourceSeq, attempt: the delivery count, worker: the broker-authenticated\n  caller (principal + lifecycle UID, plus epoch for endpoint workers), fencingToken,\n  leaseDeadline}` in its `lease` record (key grammar \xA713.7, writer table \xA713.9) by\n  **first-wins idempotent CAS per (item, attempt)**, a duplicate or\n  delayed `lease` call for a still-current attempt returns the SAME lease; an attempt is\n  superseded once redelivery advances the delivery count; `fencingToken` is CAS-incremented\n  per attempt and `leaseDeadline` comes from the owner's own clock. Expiry revokes the claim\n  at that deadline even before reassignment. Every Cotal-owned commit from claimed work is\n  submitted through the reserved **`commit` command** carrying the exact lease tuple; the\n  handler validates token currency AND unexpired lease against its own clock AND that the\n  caller is the lease's bound worker, then performs an **atomic, idempotent per-item CAS to\n  a cached terminal result**, the per-item terminal fact\n  `epf.<endpoint>.wrk.<pool>.<acceptance identity>` (\xA713.2), create-only CAS per item,\n  under its mediated writer credential (\xA713.9): a committed item\n  can never be leased again, a duplicate commit returns the cached terminal outcome, and a\n  raced commit loses loudly. Only after observing the committed terminal state does the\n  owner ack the WorkQueue message; it holds the delivery natively, so the deletion\n  capability is never transferred, and no worker-side ack can destroy an item whose commit\n  was rejected. A lost owner ack merely redelivers the item to the owner, which observes the\n  committed terminal state and acks again: **settled work is never re-enqueued as new** (the\n  durable bridge is the acceptance fact plus the per-item terminal CAS; an accepted item\n  with no terminal result and no live pool entry is the only re-enqueueable state, \xA713.6). A\n  stale token, expired lease, or superseded worker is `expired`/`conflict`; workers hold no\n  bypass write.\n- **scatter**, a request on the `all` rail. The caller freezes a **request-scoped expected\n  set**, the live instances of the class from the service registry, each as\n  `(instanceId, registrationRevision, epoch)`, where `registrationRevision` is the store\n  revision of the instance's `svc\u2026.spec` record key (\xA713.7: it advances only on mediated\n  registration writes, and the record read/watch grant that freezes it is a \xA713.9 matrix\n  row), at send time. Gather accepts at most one\n  terminal reply per expected `instanceId`, attributed from the reply subject **including its\n  epoch** (\xA713.2): a second reply from the same `(instanceId, epoch)` is classified\n  `duplicate` and **reported, never silently dropped** (first reply wins); a reply from a\n  frozen `instanceId` at a different epoch, or an observed registration-revision advance;\n  is classified `churn` (the instance restarted mid-scatter and may never have seen the\n  request) and does not count toward completion; replies from outside the frozen set are\n  classified `unexpected` and never count toward completion. Completion is\n  all-expected-replied or deadline, in which case the result is explicitly partial with\n  `missing` / `churn` / `unexpected` / `duplicate` / `late` classifications (a churned slot\n  reports as `churn`, not `missing`). An empty or unreadable registry is\n  `failed-precondition`, not an empty success. Deadline mandatory. A per-instance liveness\n  probe that asks the broker about an instance's own rail is such a cast, and a refused\n  probe publish MUST surface as that same `permission-denied` refusal naming the refused\n  subject, never as a liveness verdict: only the broker's no-responders answer is a\n  liveness fact, and a refusal licenses nothing (a caller that swallowed it into `unknown`\n  would read a permission problem as \"no verdict\" and pay the full budget for it).\n\n### 13.6 Composites\n\nPatterns over the verbs and contracts; zero new transport.\n\n**Action**, a long-running command. `action` is a command **marker**, never a class: an\naction command's submissions are `class: journal` (\xA713.3).\n\n1. The caller submits with a client-generated `goalId` and the request fingerprint (\xA713.4).\n   Accept/reject is the durable decision fact (\xA713.4), expected within the submission's\n   decision deadline; there is no reply-rail answer to recover.\n   **Authorization linearizes at acceptance**: the acceptance fact persists the caller and\n   target lifecycle tuples, command + contract digests, and the authorization decision\n   revision/epoch it was made under. A scope narrowing before acceptance rejects the goal;\n   after acceptance it blocks *new* goals but an accepted goal continues, unless the\n   command's contract declares **continuous reauthorization**, in which case each declared\n   checkpoint re-validates and deterministically transitions to `cancelling`/`failed`\n   (`permission-denied`) on narrowing. Handle expiry/revocation mid-goal follows the same\n   declared policy.\n2. States: `accepted \u2192 running \u21C4 waiting \u2192 succeeded | failed | cancelled | expired |\n   uncertain`, with\n   `cancelling` between a cancel and its terminal state. This is the **single status\n   vocabulary** for every long-running surface. All five of `succeeded`, `failed`,\n   `cancelled`, `expired`, and `uncertain` (item 6) are **terminal**, and first-terminal-fact-wins\n   applies uniformly: `uncertain` is not an absence of an outcome, it is the outcome\n   \"this action's success signal did not arrive within its readiness deadline\".\n3. Progress rides per-goal events (`epe\u2026goal.<caller triple>.<goalId>.progress`), read-scoped\n   to the caller at mint time. The goal's current state is a status-only record projection;\n   the journal owns the facts.\n4. Cancel is the reserved `cancel` command: `graceful` (compensations, default) or\n   `terminate`. Cancel of an unknown/terminal goal is `failed-precondition` with the cached\n   outcome attached. Cancel races completion at the mediated commit point: first terminal\n   fact wins; the loser observes it.\n5. The terminal result is a journal fact and is cached. The full payload is retained at least\n   the declared result retention (default 24h); a **terminal tombstone**\n   `{goalId, fingerprint, state, outcomeDigest}` at least the idempotency horizon (\u2265 result\n   retention; outcome-stated by the \xA713.12 retention floor). Same goalId + fingerprint returns the cached outcome (after payload eviction:\n   the tombstone summary, `data.evicted: true`); same goalId + different fingerprint is\n   `conflict`; beyond the horizon a reused goalId is explicitly new work.\n6. **Bounded readiness (`uncertain`).** An action whose success signal may lawfully not\n   arrive within its readiness bound declares a **readiness deadline**, a distinct,\n   acceptance-relative bound persisted in the acceptance fact/goal state, NOT the\n   submission's `deadlineMs` (which bounds only the decision, \xA713.3). Spawn readiness is\n   the reference case: its readiness deadline is **30 s**, the migrated presence-or-exit\n   backstop, D29; every legacy spawn-timeout consumer converges on this single bound. When\n   the deadline passes without the signal, the owner records the goal's terminal **result\n   fact** (`goal\u2026.result`, \xA713.2) with the outcome\n   `uncertain`, and the goal IS terminal: `uncertain` is a terminal outcome like\n   `succeeded`/`failed`, immutable, first-terminal-fact-wins as for any goal (there is no\n   call and no reply rail here: an action is a journal submission, and the result fact IS\n   the caller-visible outcome, item 5). The underlying ENTITY's later convergence\n   (ready/exited) is observable on that entity's own status record (`svc\u2026.status`, the\n   lifecycle mapping); a caller that needs the eventual answer watches the entity, never\n   the goal; the goal is not rewritten and its status does not linger non-terminal.\n7. Goals bind the target's `(principal, lifecycleUid)` (\xA713.1): a goal accepted against a\n   lifecycle is not redeemable, cancellable, or effectful against a same-name successor. A\n   restarted instance (same `instanceId`/UID, advanced epoch) recovers its goals from journal\n   + records; a superseded epoch cannot commit transitions.\n\n**Awaitable checkpoint**; one durable pause primitive (approvals, guard holds, payment\nauthorization). A waiting action mints a checkpoint: a durable token persisted with the goal,\na `waiting` status carrying the checkpoint id and its **deadline generation**, and a durable\ntimer (\xA713.12). Deadlines are mandatory. Heartbeat/extension CAS-advances the generation in\nstatus, then replaces the timer (a new `.schedule` request; the mediated timer writer's\nsame-subject `.armed` publish is the server rollup, \xA713.2/\xA713.12, the 2.14 atomic\nstop-plus-publish is NOT assumed at the 2.12 floor). A firing timer carries\n`(timerId, generation)`; the endpoint validates the generation against current status before\nacting, stale fires **no-op**. Because status and timer are two resources with no atomic\nbridge, a **durable reconciler** on the owning endpoint repairs the pair after crash or\nleadership change WITHOUT any status\u2194schedule read the no-read timer plane cannot serve: the\nreconciler **re-emits a `.schedule` request at the current generation for every `waiting`\nstatus it owns**, and a same-`(timerId, generation)` arm is **idempotent at the timer writer**\n(it re-derives the same `.armed` message; a duplicate is a no-op replacement), so\nover-emission is harmless and a missing schedule is repaired without the reconciler ever\nhaving to observe whether one exists. Stale-generation fires still no-op at the handler. Cancellation of a timer is cleanup, never the correctness boundary.\nTimer retention MUST exceed the maximum deadline plus a recovery margin. Resume: a `resume`\ncommand presenting the checkpoint token; resume authorization is **one-use** (journaled by\ncreate-only CAS on the checkpoint token; duplicate resume is `conflict`) and holder-bound\n(\xA713.10). Expiry fails the checkpoint closed.\n\nA settlement MAY name the answer it accepted. The one-use settle fact carries an OPTIONAL\n`answerId`, and the status carries the matching OPTIONAL `settledAnswerId`; both are id tokens,\nboth are permitted ONLY on a `resumed` settlement, and an implementation MUST reject either on an\nexpiry. Their key sets are closed: an endpoint that does not know these keys MUST hard-error on a\nfact that carries one. The answer's payload MUST NOT ride either field.\n\n**Guard checkpoint**, the pre-effect authorization hook. A command carrying the governed\n`ai.cotal.guarded` trait MUST NOT effect until the guard endpoint named by the trait value\nanswered **allow** (class call). Answers: `allow | deny | hold` plus optional signed\nobligations (attenuations the endpoint MUST apply; monotonic). `hold` converts the action to\n`waiting` on a checkpoint owned by the guard decision. Timeout or unreachable guard is\n**deny** (fail closed). Ordering is guard-then-effect. Side-effecting guards own their own\nreconciliation.\n\n**Capability handle**, the one passable reference type: a signed JSON grant, RFC 8785\ncanonical, Ed25519-signed by a key in the trust-anchor registry (\xA713.10):\n\n`{ v: 1, id, space, issuer: { keyId }, holder: { id, lifecycleUid }, grants: [{ endpoint,\ninstanceId?, commands: [{ name, authz?, targetOwner?, targetActor?, targetLifecycleUid? }],\nreads?: [<record-key or event-topic subtree>] }], iat, nbf?, exp, parentDigest?, sturdy,\nepoch?, sig }`\n\nA grant entry carries **every subject-level dimension** a capability has (\xA713.9): a targeted\ncommand names its authorization mode and target components; read scopes name exact\nrecord-key / event-topic subtrees. The per-command target tuple is a **closed set of three\nlegal shapes**, no target components; `targetOwner` alone; or the full triple\n`{targetOwner, targetActor, targetLifecycleUid}`, and **every other combination is\nschema-invalid** (`contract-invalid`): in particular `targetActor` without\n`targetLifecycleUid` (a handle that pins a recyclable alias component MUST pin the lifecycle\nit means) and `targetLifecycleUid` without `targetActor` (a lifecycle restriction with no\ncompile target would otherwise be silently DROPPED into an owner-wide grant, a partial\ntuple never weakens into a broader one). The normative compiler maps a grant entry to\nexactly the subjects the equivalent minted capability would receive (never wider) it MUST\nconsume every present signed component (a component the compile target cannot express is\nschema-invalid, never ignored), and every legal entry HAS a compile target:\n\n- a **no-target** entry compiles to the untargeted or `self` form per the command's\n  contract; an `authz` field on it is schema-invalid.\n- an **owner-domain** entry (`targetOwner` alone) compiles to the mode its `authz` field\n  names, `owner` (the default), `child`, or `ledger`, and NOTHING else: each pins the\n  signed `targetOwner` in that mode's own subject form (\xA713.2), **never collapsing `child`\n  or `ledger` to `owner`** (the modes are distinct validator-primary rails and rewriting\n  one into another widens authority), and **`authz: \"any\"` is schema-invalid in a handle\n  grant entry** (`contract-invalid`): the `any` rail is operator-ceiling authority, minted\n  only as a standing capability under an operator-scoped anchor (\xA713.10), never conferred\n  or attenuated through a handle; a compiler therefore has no `any` case, and no\n  implementation choice exists between rejecting, literalizing, or widening it.\n- an **actor-pinned** entry (the full triple) compiles to the `handle`-mode form pinning the\n  full signed triple `<targetOwner>.<targetActor>.<targetLifecycleUid>` (\xA713.2); an `authz`\n  field on it is schema-invalid (the triple IS the mode).\n- an **instance** entry compiles to\n  the exact `ep.inst` rails; complete, because `(endpoint, instanceId)` is the whole instance\n  address and instance ids are never reused (\xA713.1).\n\nA capability that cannot be represented in this shape MUST\nNOT be carried by a handle.\n\n- **Two uses, both fail-closed.** *Attenuation:* presented in the `auth` slot, a handle only\n  narrows; the handler enforces `effective = presenter-cred \u2229 handle.grants \u2229\n  issuer-authority`, and additionally requires any signed target triple to match the\n  request's target and the current mapping (`expired` on mismatch); it never confers broker\n  reach. *Conferral:* a handle grants reach only by **redemption through the trusted auth\n  path** (the exchange/callout of \xA79/\xA710), which verifies the signed target triple against\n  the current mapping **at redemption time** (`expired` on mismatch) and mints a short-lived\n  credential whose grants are the intersection of issuer authority, handle grants, and the\n  redeeming holder's current lifecycle + credential; actor-pinned grants compile to\n  `handle`-mode subjects carrying the verified triple (\xA713.2), so a target lifecycle that\n  rotates after mint is caught by the endpoint's currency check; no handler-side widening\n  exists. The minted credential is **ledgered before release** in the credential ledger\n  (\xA713.1), keyed under the redeeming holder's lifecycle with the FULL presented handle\n  chain as its `sourceChain` (plus the per-ancestor `bysrc.` index keys), so\n  takeover/retirement barriers revoke it with the family and revoking ANY handle in its\n  lineage (parent or leaf) cascades to it. Chain verification itself checks the\n  revocation status of EVERY sturdy link in the chain, not only the presented leaf,\n  failing closed on any revoked ancestor.\n- **Holder-bound:** `holder` names the one `(principal, lifecycleUid)` that may present or\n  redeem it; bearer transfer exists only as an explicit issuer-signed re-issue. `space` binds\n  it to one space. A recycled alias cannot present its predecessor's handles (UID mismatch).\n- **Attenuation chain:** `parentDigest` references the parent handle; a child MUST be \u2286 its\n  parent under the **normative containment order**, per grant entry: endpoint within the\n  parent's endpoint/domain pattern; `instanceId` equal or newly pinned (never widened to\n  absent); commands a name-subset with per-command mode never higher in `self < owner < any`\n  (`child`/`ledger`/`handle` are grantable only where the parent names the same mode); target\n  components equal or newly pinned; read subtrees subject-prefix-contained, and per\n  envelope: same `space`, validity window within the parent's, `sturdy` only if the parent is\n  sturdy. The issuer of a child is the parent's holder, anchor-registered with a `handles`\n  role whose scope covers the child (\xA713.10); the same containment order defines issuer-scope\n  coverage. Presentation carries the full chain inline (`parentDigest`-linked artifacts\n  presented together, no ambient fetch); verification walks every link to a registered\n  anchor, failing closed on widening, unknown/revoked keys, or expiry.\n- **Sturdy vs live:** live handles (`sturdy: false`) bind the current process `epoch`, are\n  never persisted, `exp \u2264 24h`, and die on restart. Sturdy handles bind the lifecycle UID\n  (surviving supervised restart), persist as issuer-namespaced `handle.<issuerKeyId>.<id>`\n  records (spec create-only; status = revocation state, monotonic; \xA713.9 writer table), and\n  verifiers MUST check revocation (fail closed if unreadable). Max sturdy TTL is\n  space-configured (default 30d).\n- Handles are reusable within TTL unless a composite declares one-use (checkpoint resume);\n  the replay matrix of \xA713.10 governs every signed artifact.\n\n**Session (bidirectional stream)**, the generic composite for interactive byte/frame\nstreams (terminal attach is its first consumer; nothing terminal-specific is normative). It\nis exactly D26's cast-ingress + watch-egress composed over dedicated per-session subjects,\nno new verb and no new transport: the `in` subject is a cast-only rail (caller publishes,\nendpoint subscribes) and the `out` subject is a watch rail (endpoint publishes, caller\nsubscribes). A session is established by an ordinary command whose answer is a **session\ngrant**: a one-use,\nholder-bound handle (live: bound to the caller's lifecycle AND current process epoch,\nlive authority dies on restart, \xA713.1, so redemption fresh-checks the holder epoch and an\nunredeemed grant does not survive the caller's restart, plus the serving instance epoch) naming a fresh\nunguessable `sessionId` and the epoch-pinned session subjects\n`eps.<endpoint>.<sessionId>.<epoch>.in` (caller \u2192 endpoint) and `\u2026.out` (endpoint \u2192 caller).\nSession subjects are **core-only**, never stream-captured; the bounded flow window lives in\nmemory and a dropped frame is the composite's problem, not retention's. Redemption mints\nexact asymmetric per-session credentials: the caller publishes `in` and subscribes `out`;\nthe serving instance the reverse; no third party holds either, and no standing wildcard EPS\ngrant exists. Frames are opaque; flow control is bounded (window declared in the grant;\noverflow is `resource-exhausted`, never unbounded buffering). Close is explicit, and\nrevocation has a **durable** named authority that survives the\nserving endpoint: the trusted auth path (the exchange/callout of \xA79/\xA710) persists a **session\nledger row** at redemption, key `session.<sessionId>` in the auth store (\xA713.12), value\n`{sessionId, endpoint, serving instance + epoch, holder (principal + lifecycleUid), both\nminted credential ids, per-credential revocation marks, state, exp}` (the endpoint is in the\nrow because an `instanceId` is unique only within its endpoint, so every serving-party\noperation authenticates against the full serving identity the row pins), create-only CAS per\n`sessionId` (this CAS IS the one-use\nredemption), state monotonic\n(`active \u2192 closed | expired | superseded | retired`, all terminal), and each per-session\ncredential is simultaneously a credential-ledger row under its holder's lifecycle (\xA713.1),\nwhich is the index the \xA713.1 barriers enumerate, and a barrier that revokes a\nsession-sourced credential MUST resolve its `session.<sessionId>` row, transition it\nterminal, and revoke BOTH per-session credentials, so either side's takeover or retirement\ntears down the whole pair, not its own half. Redemption's writes are ordered by a **finalize CAS**, so no half-issued session is ever\nusable: the create-CAS writes the session row in state `issuing` (this create IS the\none-use), then both per-session credential rows are written gate-checked (\xA713.1), then the\nredemption **CAS-finalizes the session row `issuing \u2192 active`**, fresh-checking BOTH the\nholder and serving process epochs and both lifecycle gates at that CAS, and releases the two\ncredentials only on finalize success. A credential is authority ONLY once its session row is\n`active`; an `issuing` row confers nothing. Close/expiry/either barrier CAS the row to a\nterminal state (`closed`/`expired`/`superseded`/`retired`) and revoke both credential ids by\nname (the ids are known from the row, whether or not both credentials were released) so a\ncrash mid-issue leaves an `issuing` row that the expiry sweep collects (revoking both ids and\ntombstoning), never a live half-pair, and a redemption racing a close loses its finalize CAS\nand releases nothing. A revocation mark is set only by a revoke that SUCCEEDED; a terminal\nrow with an unmarked credential is retried by every later sweep pass, exactly the unconfirmed\nids, until both marks confirm, so a transient revocation failure can never quietly leave half\na pair alive. The auth path revokes BOTH per-session\ncredentials with eviction (bounded\npropagation) on any of: an **authenticated close input** on the trusted auth path itself,\na defined operation of the SAME exchange/callout surface that redemption already uses\n(\xA79/\xA710, off-broker, so no broker grant row applies): the caller authenticates as one of\nthe session's two parties (its lifecycle or per-session credential) or as the operator and\nnames the `sessionId`; the auth path verifies party membership against the ledger row\nbefore transitioning it. The in-band close frame\nis an advisory peer signal, never the revocation authority, because EPS subjects are\ncore-only and captured by nothing; expiry per the handle rules (`exp` is enforced by the\nauth path's own timer, not by the endpoint), or the serving\nepoch's supersession / lifecycle retirement via the \xA713.1 barriers (either side's lifecycle:\nholder and serving rows both index the family). Neither side can keep a\nhalf-closed session alive, and a crashed serving endpoint cannot orphan one, the ledger, not\nthe endpoint, remembers what to revoke. Ledger rows are retained at least the maximum\nsession `exp` plus a recovery margin. The session dies with the serving instance's epoch\n(the epoch is in the subject, so a restarted instance cannot resume it; a durable session is\na new establishment). Routing is authenticated broker routing end to end; there is no loopback URL\nor out-of-band transport in the contract, and cross-machine reachability is exactly broker\nreachability.\n\n**Remote manager service registration.** A remote registered user becomes a manager only through\none host-operated, typed `prepare \u2192 activate \u2192 renew` exchange. It is not a generic credential\nmint surface and is available only on the loopback/operator face to a signed-in human holding the\nclosed `manager-service` view (\xA713.1); the public exchange and managed-agent secret exchange\nrefuse every stage. All inputs and stored stage records are closed schemas. An operation is keyed\nby `{ owner, managerActor, lifecycleUid, instanceId, operationId }`, where `managerActor` and the\nlifecycle UID come from the server-authorized view, `instanceId` is opaque and collision-resistant,\nand `operationId` is caller-generated for replay convergence. A repeated operation with the same\nfingerprint returns its recorded result; a different fingerprint at the same coordinate is\n`conflict`; a retired lifecycle or instance is never revived.\n\n`prepare` fresh-checks the ledger scope and lifecycle, freezes only\n`epgate.manager.<instanceId>`, and durably stages the exact service registration, contract closure,\nstatus coordinate, requested public nkey, and credential lifetime. It releases no usable material.\n`activate` re-checks that same live ledger row and gate, creates the exact `svc.manager.<instanceId>`\nregistration, publishes only the staged immutable contract artifacts, and asks the host to sign\nNATS JWT material for that public nkey. The host writes the matching\n`epcred.manager.<instanceId>.<credentialId>` row before the gate-finalize CAS and returns the JWT\nonly after that CAS; it never returns a signing seed. `renew` is the only way to obtain successor\npublic-nkey JWT material. It re-checks the live `supervise` grant, owner, actor, lifecycle,\ninstance, current gate, and bounded renewal window, then records and releases a replacement under\nthe same family. It cannot create another instance or broaden a staged contract, record, endpoint,\nor credential grant. A crashed operation resumes only from its durable stage and operation id.\n\nRenewal is bounded and denial is fail-closed. When a manager cannot renew because its login,\nledger scope, or host service is unavailable, it reports degraded state, retains already-live\nagents only while their independently valid authority remains usable, and refuses new starts,\nrestarts, replacement credentials, and unsafe recovery. It MUST NOT turn a transient failure into\nstatic authority or kill a live agent merely to make the state look healthy. When the current\nfamily expires or is revoked, the host's verified revocation path closes it; a later restart still\nrequires a new successful prepare/activate operation. Same-owner descendant provisioning is\nhost-validated at every request, and loss of that validation also refuses a new start or restart.\n\n**Platform control registration.** A platform-run control manager registers, activates, renews,\nand retires through the same typed `prepare \u2192 activate \u2192 renew` protocol and operations as the\nremote manager service above: `session`, `retire`, `renewStandingBundle`, `renewRunDriver`, the\nhost-owned maintenance operations, retained-agent validation, the goal-index scan, admin\nauthorization, and run admission and attempt. Each request rides inside one closed\n`platform-control-authority` envelope that adds only the space, the assigned account, and the\nassignment revision. The envelope and every inner request are closed schemas. The envelope carries\nno profile name, permission set, subject, lifetime, claim, or identity assertion. An inner request\nkeeps its existing operation-specific coordinates, such as the `session` operation's requested\n`exp`, which the host caps at its own bound, and the run admission's served `run.subject`, which\nthe host re-parses and checks against the caller's issued ceiling. The host validates each one as it\ndoes under `manager-service`. No field of either selects a signing subject, permission set,\nprofile, claim, or a credential lifetime past the host's bound, and an unknown kind or field MUST\nbe refused as `bad-request` with no effect. The managed-agent enrollment, retirement-preparation, and\nruntime kinds are not carried; a host without its own storage for them MUST refuse them as\n`unimplemented`. The door is a typed in-process operation of the host's authority context. It\nexists only where the host supplies its assignment source, and no listener serves it. It needs no\nexchange capability: the host MUST NOT hand its loopback capability or account signer to a control\nmanager, and a host that runs the control manager in another process carries the closed envelope\nover its own caller-bound channel. A request carrying a human IdP token MUST be refused. It is not a\ngeneric credential-mint surface and adds no daemon, listener, or protocol.\n\nHost-owned maintenance is narrower under this view than under `manager-service`. Under\n`platform-control`, a maintenance request's `targetInstanceId` MUST equal the assigned instance id\nfor both `evict-family-principal` and `reconcile-registration`, and the host MUST observe that the\ntarget gate's principal is the platform owner plus that instance's fixed serve actor. Both checks\nrun after the assignment check and before any liveness probe, revocation, eviction, or reopen. A\nfailure is `permission-denied` with no effect. A foreign slot holder therefore blocks platform\nregistration with the existing registration refusal, and it is repaired only through its own\nowner's `manager-service` maintenance or the host operator's guarded gate repair, neither of which\nthis view reaches. `manager-service` maintenance, including its reconciliation of a foreign slot\nholder, is unchanged.\n\nRenewal and fencing are the remote manager service's, unchanged. `renewStandingBundle` returns the\nclosed five-credential family for the same caller-held nkeys and the assigned account only when the\ncurrent gate is open, its principal is the platform owner plus the fixed serve actor, its process\nepoch equals the request's, and the host-keyed current registration proof matches. A stale epoch\nis `conflict`. A revoked or advanced assignment refuses the next request, renewal included, so\nrevocation never waits on a person and renewal never authenticates one. The remote manager\nservice's degraded-state and fail-closed renewal rules apply with the assignment in place of the\nlogin and ledger scope. A start after revocation or expiry requires a fresh `prepare` and\n`activate` under a current assignment.\n\n**Virtual endpoints.** An endpoint MAY be virtual: registered (`spec.activation = on-demand`)\nwith no live instance. A virtual endpoint's commands MUST be journal-class: the buffered\ningress path is the ordinary submission plane (`epj` is durable and needs no live\nsubscriber), and the canonicalizer, which for a virtual endpoint runs wherever its\nactivator/owning authority runs, checks pool admission BEFORE deciding (an over-capacity\nsubmission is rejected `resource-exhausted` as its durable decision fact, never accepted and\nstranded), then accepts and enqueues the work into the endpoint's `epw` pool. Admission\noccupancy is the pool consumer's `num_pending + num_ack_pending`, read fresh from the exact\nper-pool consumer INFO after reconciling the canonicalizer's own outstanding acceptances\nagainst the predicate below (a repaired item is inside the count new work competes under);\nthe read fails closed (an unreadable consumer is `unavailable`, never an empty pool), and the\nsum is honest only while the pool consumer's delivery ceiling is unlimited\n(`max_deliver = -1`) AND its filter is exactly the pool's own subtree; BOTH are editable after\ncreation, so both are pinned at creation AND re-proved at every read (a message that exhausts\na finite ceiling stays stored but leaves both counters; a narrowed or foreign filter reads\nempty while stored work remains). The admission capacity comes from the endpoint's REGISTERED\nactivation policy (declared as the registration's `spec.activation` block, a closed schema\nwhose `capacity` is required; the registration path publishes each version as an immutable\n`policy` record, \xA713.7, and the govern head's selector below names the enforced one), READ\nleader-served at each decision (the read is FENCING by use, so a\nfollower Direct Get is never used; a scoped canonicalizer executes it only through the\nconfined policy reader of \xA713.8, whose request subject binds the authenticated endpoint)\nand its enforced revision RE-PROVEN after the decision's\nlater reads and carried into the acceptance commit, never a free-standing argument; the\ncarried revision is provenance, and the FENCE against the policy or lifecycle moving while\nthe acceptance is in flight is the \xA713.8 obligation row, not the carried value. The\n**endpoint-wide policy coordinate** is not a new head: it is the governance head\n`govern.<endpoint>` (\xA713.7, the endpoint's registration linearization point). To make the\nenforced policy MACHINE-SELECTABLE by any second implementer (not inferable from prose), the\ngovern head value carries a normative **policy selector**: `{ enforcedPolicyKey (the exact\nrecords key of the immutable `policy` record currently governing, \xA713.7), enforcedPolicyRevision\n(that record's STORE revision), pendingPolicyKey?, pendingPolicyRevision? }`. A canonicalizer reads\ngovern leader-served, follows `enforcedPolicyKey`, and re-proves it is still at\n`enforcedPolicyRevision`, with no per-instance guesswork; `policyRevision` throughout this\nsection IS `enforcedPolicyRevision`. **`enforcedPolicyKey` MUST name an IMMUTABLE,\nREVISION-ADDRESSED policy record, not a mutable per-instance slot** (a bare\n`svc.<endpoint>.<instanceId>.spec` overwritten on every re-registration is disqualified: the\nrecords bucket keeps history 1, so once a mutation overwrites it the OLD `enforcedPolicyRevision`\ncan no longer be read, and the drain window's claim that \"the old policy keeps governing\" would\nbe unbacked). The normative immutable form is the **`policy` record kind** (\xA713.7):\n`policy.<endpoint>.<digest-hex>`, one unsplit, create-only, NEVER-DELETED key per policy\nversion, where `<digest-hex>` is the SHA-256 hex of the record's canonical value bytes: the\nkey is self-certifying (a reader re-digests the value and refuses a mismatch), so a\ndifferent-byte overwrite is caught on read, and BOTH the enforced and the pending revisions\nstay readable throughout the drain. Immutability is upheld by the sole writer's create-only\nCAS plus that read-time self-certification, not a broker-level subtraction (\xA713.9). A\ndeployment that cannot provide an immutable policy key MUST pause admission during the\nmutation rather than claim the old value remains readable.\nA policy mutation is a re-registration under the frozen registration gate that lands in TWO\nfenced govern-head CAS steps (\xA713.9): (1) **stage** records the new registration as\n`pendingPolicy{Key,Revision}` (a NEW immutable policy key) while `enforcedPolicy...` still\npoints at the OLD immutable record, so\nthe old policy keeps governing and stays readable; (2) **promote**, only after the mutation has **drained the\nendpoint's unresolved obligations to quiescence** (\xA713.8: enumerate `oblig.*.<endpoint>.>`,\nsettle every unresolved row pinning an older `enforcedPolicyRevision` through its decision\ncoordinate, re-enumerate until none remain), moves `pendingPolicy...` into `enforcedPolicy...`\nand clears the pending slot. Admission always pins the CURRENT `enforcedPolicyRevision`,\nand **while a `pendingPolicy\u2026` is staged, proof issuance for policy-admitted decisions\nREFUSES** (`failed-precondition`: the endpoint is inside its drain window; target-bound-only\nadmissions are unaffected). The pause is what makes the drain CONVERGE under load and makes\n\xA713.8's rule (a row created after the drain's final enumeration can never admit) hold for\npolicy movement exactly as it holds for retirement; rows admitted BEFORE the stage keep their\npinned old revision readable through the immutable key, so no admission is ever judged\nagainst a policy it did not pin. The stage/drain/promote order is a durable, resumable\ngovern-head sequence, never an implied transaction. The **restart-status commit is the same two-coordinate\nclass**: before its status CAS the supervisor obtains a `self`-class obligation (\xA713.8)\nthrough the same mediator, pinning the `enforcedPolicyRevision` its thresholds were read\nunder AND the complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }`\nof the\nstatus record it will write; the status CAS is authorized only while that obligation is\n`accepted`, so a policy or lifecycle movement settles the obligation and the delayed commit\nloses a CAS, and a crash after `accepted` is finished deterministically from the pinned\nintent (\xA713.8 recovery), never a\ncarried-revision comparison. The\nrestart-intensity thresholds are read leader-served from the SAME registered policy, so neither\na caller nor a follower-stale read can loosen the window to suppress an escalation. A command\nname is declared ONCE across the whole closure; a cross-cluster duplicate is an ambiguous\nsurface and registration refuses it, and a command declared non-journal-class in ANY cluster is\nnon-journal for the on-demand registration check. The supervisor-owned status fields (the\nrestart history and the retirement mark) and the `escalated` state can be ORIGINATED only\nunder the supervisor's DISTINCT WRITE AUTHORITY (a package-private branded capability held by\nthe restart-note and the escalation reconciler, never an ambiently-mintable factory or the mere\npresence of a revision pin): an instance-side status write, whether it creates the first status\nor updates a later one, has them stripped and cannot originate `escalated`. The restart history\nand retirement mark are validated at every read boundary (a unique-epoch history, an integer\nmark present only on an escalated row), and a DEL/PURGE status marker fails closed on the\nretirement path (a deletion is never clean absence). Every status write operates on a validated DETACHED snapshot\ntaken before its first read, so a caller mutating a shared status object mid-write cannot split\nthe authenticated coordinate from the stored bytes. The activator's reply authority is its\nown CONNECTION-SCOPED inbox (`_INBOX_<connId>.>`), never the account-wide default, and its\noccupancy read re-proves the pool consumer's ack policy and pull mode alongside its editable\ndelivery ceiling and filter (a delete/recreate must not substitute a semantically different\nconsumer). A supervision clock behind the newest recorded restart is refused before the\nduplicate-note short-circuit, so a rolled-back clock never returns a stale count. The virtual endpoint's canonicalizer durable serializes admission\n(`max_ack_pending = 1`): one submission is in the count-decide-enqueue path at a time, so two\nsubmissions cannot both observe the same free slot; because MaxAckPending is also editable\nafter creation, every admission re-proves the live pin and refuses on drift rather than\ndeciding under a serialization it no longer has; pool-worker execution concurrency is an\nindependent knob, already inside the count via `num_ack_pending`. A virtual endpoint's\nregistration REFUSES if any declared command is not journal-class (an ephemeral surface\ncannot exist with no live instance). Acceptance and\nenqueue span two streams with no atomic bridge, so the enqueue is **idempotent, keyed by the\nacceptance identity, and reconciled against a decidable predicate**: the pool subject carries\nthe acceptance identity and the enqueue is a create (expected-last-sequence-for-subject 0),\nso a duplicate enqueue loses its CAS harmlessly; because the pool owner acks only after the\ncommitted terminal state (\xA713.5), an acceptance fact **with** a terminal result is settled\nand never re-enqueued, and an acceptance fact with **no** terminal result and **no** live\npool entry (a FENCING absence: the probe is the leader-served `STREAM.MSG.GET` last-by-subject\nread of the \xA713.9 work-pool reconciliation row, never a follower-servable Direct Get, because a stale\nfollower miss would re-arm settled work) is unambiguously never-enqueued-or-lost, the\nonly re-enqueueable state. A crash after the acceptance CAS but before the enqueue is\nrepaired by exactly that predicate; an enqueue without an acceptance fact cannot occur\nbecause only the canonicalizer holds the pool-write grant and it enqueues only from its own\naccepted decisions. The stored item bytes are the CANONICAL derivation of the acceptance \u2014\nthe RFC-8785 canonical JSON of exactly `{ v: 1, id, fingerprint, sourceSeq, workExpiry,\ncaller, request }` (work identity + input only; never a lease, token, or decision metadata) \u2014\nso any two conforming writers (a first enqueue and a crash repair) produce BYTE-IDENTICAL\nitems, and the create's same-subject-same-bytes idempotency holds across them; a differing\nbody under the same acceptance identity is a mixup and refuses loud. An ephemeral\ncall to a virtual endpoint with no live instance is an honest `unavailable`; nothing\nsilently buffers it. An **activator** (holder of its activation capability) watches the pool\nand starts an instance; single-writer per identity is fenced by instance-record CAS +\nepoch. The exact consumer INFO the activator watches is a request/reply snapshot with no\nbroker wakeup, so watching is bounded polling with backoff to a finite maximum interval, and\nan INFO failure is loud, never a silent skipped poll; the activator's broker authority is\nexactly that INFO read plus its mediated, target-bound start seam (no pool consume/ack, no\nstream read, no consumer create/update/delete). Passivation drains, updates status, exits;\ndurable reminders ride the timer plane.\nSupervision is restart-intensity escalation: more than `maxRestarts` (default 3) within\n`restartWindow` (default 60s) escalates; the instance stops restarting, status records\n`escalated`, the lifecycle retires terminally (\xA713.1), and the failure is loud. The restart\nhistory is DURABLE on the instance's own status record, SUPERVISOR-OWNED (the status writer\ncarries it forward through every ordinary instance-side write, so a successor's `ready`\nconvergence can neither reset nor forge it), and each note is a revision-pinned CAS: a\nsupervisor restart cannot amnesty the count and two concurrent notes cannot merge-lose a\nrestart. Each history entry is bound to the DYING PROCESS EPOCH (a real restart advances the\nepoch), so a replayed or duplicated notification of one restart is an idempotent no-op, never\na double count; and a supervision clock behind the newest recorded restart REFUSES rather\nthan silently truncating history. `escalated` is IRREVERSIBLE at the status writer (no later\nwrite, any epoch, replaces it), refuses further notes, and is excluded from every liveness\nderivation (a frozen scatter expected set never contains an escalated instance). The\nescalation commits before the lifecycle retirement runs; the retire seam MUST be idempotent,\na retirement failure leaves the escalation standing, and a reconciler retries retirement on\nalready-escalated rows until it completes, recording completion durably (nothing\nun-escalates).\n\n**Interactive session**, a one-use, holder-bound, bidirectional byte stream to a managed target\n(the `attach` reference case). Establishment is a two-step, collapsible exchange: the serving endpoint\nmints a signed **session grant** bound to `(holder triple, target (owner, actor, lifecycleUid),\nserving instanceId + epoch, expiry)` and returns it as the establishment answer, **never a transport\nURL and never logged**; the holder **redeems** it by opening the session, which consumes it (create-only\nCAS on the durable `session.<sessionId>` ledger row, \xA713.12; a second redeem is `conflict`). The grant\nis non-bearer: redemption is **presenter-equality** bound to `holder` (\xA713.10), so a leaked grant confers\nnothing. Authorization is the target command's own (`owner`/`any` + name authority, \xA713.9); a session is\nnever a path around the despawn/attach authorization.\n\nThe byte stream rides two CORE-ONLY rails, `eps.<endpoint>.<sessionId>.<epoch>.<in|out>` (\xA713.9), never\nstream-captured: the holder publishes `in` and subscribes `out`, the serving endpoint the reverse; the\nholder's grant covers exactly its own session's two subjects. **Framing** (the terminal-session profile):\napplication bytes are `{ k: \"data\", b: <standard base64> }`; control is structured JSON, `{ k: \"ready\" }`,\n`{ k: \"resize\", cols, rows }` (both positive integers), `{ k: \"end\", reason }`, `{ k: \"drop\", bytes }`.\nOrdering is per direction by publisher sequence. Flow is a bounded in-flight window per direction; output\nthe window cannot take is **dropped, counted, and surfaced** as a `drop` frame before the resumed stream,\nnever silently lost. On the holder's `ready` the serving side replays a byte-exact reconstruction of the\ntarget's current screen, then streams live output in order. A degenerate or unparseable caller frame is\ndropped, never a session teardown.\n\n**Termination is honest and distinct**: every teardown surfaces an `end` frame naming a bounded reason,\n`process-exit` (the target exited), `closed` (a party closed), `expired` (the session TTL elapsed),\n`target-despawn` (the target lifecycle retired), `manager-restart` (the serving incarnation advanced its\nepoch). The session binds the target's `(principal, lifecycleUid)` and the serving epoch (\xA713.1): a\nsuccessor incarnation (advanced epoch) refuses old-epoch grants, and a same-name successor is a distinct\nsession.\n\n### 13.7 Contracts and discovery\n\n**Clusters.** An endpoint's surface is a set of composable **capability clusters**, each\n`{ urn, revision, attributes[], commands[], events[] }`:\n\n- `urn`, reverse-DNS cluster type URN (`ai.cotal.lifecycle`, `com.acme.deploy`).\n- `attributes`, readable/watchable state; each declares a name, value schema, and record\n  derivation (which record key carries it). Attribute reads/subscribes ride the record\n  contract, never ephemeral replies.\n- `commands`, each declares name, input/output schemas, `class`, `targeted` (and if so which\n  authz modes it admits), its **capability requirement** (the named capability minting maps to\n  subjects, \xA713.9), its `effect` (below), and optional traits.\n  Each `journal`-class command **MUST** declare **`admissionCeiling`** =\n  `{ maxBytes, maxDepth, maxItems }`, the bounds its canonicalizer refuses beyond (\xA713.4\n  item 3). The ceiling is **declared, never compiled in**, because it decides what a\n  submission durably *becomes*: two implementations that agree on the wire and disagree on a\n  constant would write different permanent decisions for identical bytes.\n- `events`, name + payload schema; events ride the journal contract on the event plane\n  (`epe\u2026.ev.<cluster>.<event>`), read-contained by event-topic grants.\n\n**Effect.** A command declaration carries `effect`, one of `read` or `write`.\n\n**Reachability.** `effect` is reachable only under `protocol.v: 2` (*Version*, below). A responder\nwhose descriptor is pinned to `v: 1` cannot declare the field on the command surface a caller\nresolves against, and nothing in such a deployment consumes it, so the `v: 1` rule below is the\nwhole of what governs.\n\nNote what the pin does NOT do. A descriptor MAY inline the registered cluster artifact verbatim\n(*Descriptor and describe*, \xA713.7), and an artifact is not filtered against the parsed command\nsurface, so a key named `effect` inside one can appear on the wire under a `v: 1` descriptor. Its\npresence there is not a declaration and MUST NOT be read as one. Repeat-safety information exists\nonly at `protocol.v: 2`, and a caller that recovers it from raw artifact bytes under a `v: 1`\ndescriptor has reinstated exactly the retry this section exists to stop, while believing it read a\ndeclaration. A reference implementation that has not moved to\n`2` therefore carries its repeat-safety knowledge somewhere off the wire, as a static allowlist of\nthe commands it knows to be safe to repeat. Such an allowlist stands in for this field for exactly\nas long as no `v: 2` descriptor can exist, and it is superseded by the declaration the moment one\ncan: allowlist-says-safe and author-declares-`write` are answers to the same question, and two\nanswers to one question is one answer too many.\n\n`read` asserts that executing the command again **changes nothing the command is trying to\nchange**: the state after two executions is the state after one, and any difference between their\nresults is only the freshness a caller would see by asking twice. The state in question is not\nonly the endpoint's own \u2014 a command whose intended effect lands somewhere else is still a `write`.\n`evictPrincipal` on the delivery endpoint is the case that fixes the boundary: it drops live\nbroker connections and leaves the endpoint's own records untouched, and it is a `write`, because\ndropping those connections is the point of calling it.\n\nExactly one class of difference is excluded, and it is narrow: the incidental trace of having been\ncalled. Request ids, spans, access logs, metrics, counters, and timing are observable and are not\nwhat the command was for, so a command is not `write` merely because it can be seen to have been\ncalled. The test is not \"did anything change\" \u2014 something always does \u2014 but **would a caller who\nrepeated this command be surprised by what the repeat did**. If the answer is no, it is `read`.\n\n`write` asserts nothing and MUST be assumed unsafe to repeat.\n\nA client MUST NOT automatically re-issue a command declared `write` after any outcome that does\nnot prove non-execution (\xA713.3), **whatever `id` the re-issue carries**. The exemption is not the\ntoken but the CONVERGENCE: a re-issue is a resubmission, governed by \xA713.8 rather than by this\nrule, only while the responder will converge it onto the recorded prior decision. A re-issue the\nresponder accepts as NEW WORK is a repeat, and this prohibition binds it however the `id` was\nchosen.\n\nThat distinction is load-bearing because the two are not distinguishable by inspection. Same-`id`\nconvergence lasts only while the prior decision is retained (\xA713.8), and a caller cannot observe\nretention from outside \u2014 so a client that reuses an `id` after the horizon has issued a repeat\nwhile believing it issued a resubmission. Reusing the token is therefore not a substitute for the\nproof this rule demands: absent an outcome that proves non-execution, a client that cannot\nestablish convergence MUST treat its re-issue as a repeat and MUST NOT make it automatically.\n\n`effect` is a property of the command, not of its delivery class: `class` says how a request is\ncarried, `effect` says whether carrying it twice is safe, and the two are independent \u2014 an\n`ephemeral` command may be either.\n\n`effect` is declarative, and a declaration is a claim the endpoint author makes. It binds\nclients, not the responder: nothing in this section relieves a handler of its own correctness,\nand a `read` declaration over a mutating handler is a defect in the endpoint, not a licence.\n\n**Version.** `effect` cannot be introduced additively. A client that does not implement it\nignores it and retries exactly as it did before, and no default value repairs that direction,\nbecause the field's entire purpose is to STOP a retry an older client already performs. So it\nrides the discovery protocol's version marker rather than the unknown-field rule (\xA77).\n\nThat marker is the one that already exists: `protocol.v` on the **service record spec and the\ndescribe descriptor** (*Descriptor and describe*, below). It is deliberately not a new field on\nthe cluster document, which has no `protocol` of its own \u2014 adding one there would be subject to \xA77\nand dropped unread by exactly the clients this cut has to stop, which is the failure it is meant\nto prevent. An instance whose registered clusters declare `effect` MUST register and describe with\n`protocol.v` of `2`, and every command in every cluster it serves MUST then carry `effect`. `v:1`\ndescriptors remain valid, carry no `effect`, and give a resolving caller no repeat-safety\ninformation \u2014 it MUST treat every command served under one as `write`. There is therefore no\n\"omitted `effect`\" case under a `v:2` descriptor, and no surface in which the field is present but\noptional.\n\nA client that does not implement this section MUST refuse to resolve a descriptor whose\n`protocol.v` it does not implement, rather than ignore what it cannot honor. **That refusal is a\nrequirement this section CREATES, not one already met.** What protects an unamended client today\nis a fence on the other side of the wire: `describe`'s pinned output schema fixes\n`descriptor.protocol.v` to the constant `1`, so an unamended responder cannot publish a `v:2`\ndescriptor at all \u2014 its own reply fails output validation and surfaces as a responder bug. The\nregistry read path fails closed the same way, refusing a service record whose `protocol.v` is not\n`1`. The resolving caller does neither: it reads the describe answer without validating it, and\nthe shape it reads does not carry `protocol`. So the version marker is enforced today by the\nRESPONDER's contract and by the REGISTRY reader, and by nothing in the caller \u2014 which is safe only\nfor as long as no `v:2` descriptor can exist.\n\n**Emission.** Moving to `protocol.v: 2` **is** a non-additive discovery change, so \xA711's\nchange-process rule for one governs it and is the authority on how it is rolled out; this section\nadds only what is specific to `2` and states no cutover rule of its own.\n\nSpecific to `2`: a caller that resolves a descriptor whose `protocol.v` it does not implement MUST\nfail the resolve (`unsupported-version`) and MUST NOT invoke against it \u2014 a descriptor it cannot\nread is not a weaker descriptor, it is no descriptor, and treating it as `v:1` reinstates exactly\nthe repeat this section exists to stop. Implementing that refusal is what makes a caller count as\nhaving adopted this section for the purposes of \xA711's rule, which is the condition a responder's\ndeployment must satisfy before any responder in it registers or describes at `2`.\n\nWhy the rule lives there and not here: the condition is a property of the whole deployment, and a\nresponder cannot evaluate it from where it stands \u2014 per \xA711 there is no in-band capability\nnegotiation and no request carries a caller version, so a responder cannot tell an amended caller\nfrom an unamended one. A rule stated here would bind the one party unable to check it. \xA711 assigns\nit instead to the deployment, which can.\n\nAn **endpoint type** is a conformance set of cluster URNs. `manager` and `delivery` are\nordinary conformance sets defined by the reference implementation; core knows only\n\"endpoint\".\n\n**Schemas.** Contract schemas are JSON Schema **2020-12**, validated by a real 2020-12\nvalidator (the reference implementation pins `ajv`), under this normative resource profile: a\nschema is a **closed resource bundle**, either fully self-contained (local `$defs`/`#/\u2026`\nrefs) or referencing other contract-store artifacts **by digest** only. `$id`/`$anchor`/\n`$dynamicRef` resolve deterministically within the bundle; ambient HTTP/file/URI resolution\nMUST NOT occur. Contract identity is the **closure digest** (above): the digest of the\nmanifest naming the complete resolved closure, not of the root document alone. Registration-time bounds (loud `contract-invalid`, distinct from\ninvocation-time `bad-request`): document \u2264 256 KiB, closure \u2264 1 MiB, nesting \u2264 32, ref chain\n\u2264 32, bounded pattern complexity, compile/validation time budgets, and a bounded compiled-schema cache (reference: 256-entry LRU) (\xA713.8). Runtime\nvalidation at the serving boundary is mandatory: args before any effect, replies against the\noutput schema. Authoring tooling is free (the reference implementation authors in Zod); the\nwire artifact and validation semantics are the JSON Schema documents themselves.\n**Every command declares BOTH an input and an output schema**: a side with no payload\ndeclares the **canonical void schema**, the artifact `{\"type\":\"null\"}`, whose RFC 8785\ndigest is therefore one fixed value, so both `op` digests exist for every command (\xA713.3)\nand no shape in this section is conditional on a missing side. Validation against the void\nschema means the side's payload is absent or `null`.\n\n**Content addressing.** A contract artifact (cluster document, schema bundle member, trait\ndefinition or attachment) is identified by the SHA-256 digest of its RFC 8785 canonical JSON\n(strict RFC 8785 over I-JSON; the reference implementation pins `json-canonicalize`'s strict\npath and gates on the RFC's published test vectors, including number-serialization and\nsurrogate edges). **Two digests, never conflated.** An **artifact digest** identifies ONE\ndocument's bytes and is the value that keys its subject and every by-digest reference. A\n**closure digest** identifies a whole resolved bundle, a cluster document or a schema\nclosure, and is the artifact digest of that bundle's **manifest**: the artifact\n`{ v: 1, root: <artifact digest>, members: [<artifact digest>, \u2026] }`, `members` being every\nartifact transitively reachable through by-digest references from `root`, sorted\nlexicographically and deduplicated. The manifest is itself an ordinary artifact on its own\ndigest subject, so a closure digest is an artifact digest, nothing dispatches on which kind\na digest is. Contract identity (\xA713.7 `contractDigest`, `clusterDigests[]`, and the\n`op.inputDigest`/`outputDigest` a caller pins) is always a CLOSURE digest; a `$ref`-by-digest\ninside a schema is always an ARTIFACT digest.\n\n**Every `*Digest` field in this section is one scalar shape**, `sha256:<hex>`, lowercase\nhex, and each names exactly one input, so no field's digest is implementation-defined:\n`inputDigest`/`outputDigest`, `contractDigest`, `clusterDigests[]` = the CLOSURE digest of\nthe named bundle (above); a schema's by-digest `$ref` = an ARTIFACT digest;\n`argsDigest`/`outcomeDigest`/`resultDigest` = over the strict RFC 8785 canonical JSON of\nthat value (absent iff the value is absent); `authDigest` = over the raw UTF-8 bytes of the\n`auth` slot as carried (\xA713.3); `submissionDigest` = over the raw stored submission bytes\n(\xA713.4). Integer fields on the wire (`sourceSeq`, `revision`, `epoch`, `ts`,\n`deadlineMs`, `readinessDeadlineMs`) are non-negative integers \u2264 2^53 \u2212 1, the I-JSON\ninteroperable range, so at most 16 decimal digits, which is what makes the \xA713.12\nmaximum-fact fixture a computable worst case rather than an estimate.\n\nArtifacts live in the per-space **contract stream**: one artifact per\ndigest-keyed subject `cotal.<space>.epc.<digest-hex>` (\xA713.2), published as a single\nmessage; possible because a document is bounded at 256 KiB (below) and the operator floor\nasserts `max_payload` covers it (\xA713.12); a closure is fetched artifact-by-artifact through\nits digest references, never as one blob. Reads are the subject-scoped last-by-subject\nDirect Get on the exact digest subject, no consumer, no replay machinery, and nothing\nbody-selected (\xA713.9). Readers MUST verify fetched bytes against the digest and fail loud\non mismatch. Publication is mediated and create-only (\xA713.9): artifacts are immutable once\npublished. A single-message digest subject is readable subject-confined; a chunked object\nstore is not, because chunk replay needs a consumer whose delivery target is body-selected\n(\xA713.9).\n\n**Record kinds and key grammar.** Every record kind is registered: core kinds are defined\nby this section (writer table, \xA713.9), and each kind's registry entry pins its **key\ngrammar** (the qualifier tokens between the kind token and the `.spec`/`.status` suffix),\nits writer roles, and its mediation class; grants and merged watches are derived from that\ngrammar, so two implementations always agree on which key carries what. The core kinds'\nkey grammars, pinned here (each key then splits `.spec`/`.status` per \xA713.4, EXCEPT the\nunsplit atomic keys the table marks: the `lifecycle` head, `govern`, `uid`, `oblig`,\n`goalidx`, `goaleff`, `epname`, `epmig`, and `answer`):\n\n| Kind | Key grammar |\n| --- | --- |\n| `svc` | `svc.<endpoint>.<instanceId>` |\n| `signer` | `signer.<keyId>` |\n| `handle` | `handle.<issuerKeyId>.<id>` |\n| `contracts` | `contracts.<endpoint>` |\n| `goal` | `goal.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>` |\n| `goalidx` | `goalidx.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>` (atomic; an in-flight action's reconcile index, written create-only before the goal binds and deleted at its terminal, enumerated by a bounded boot-sweep authority so a superseded executor's orphaned goals settle; never caller-addressed). The reference local signer composition uses its ephemeral provisioner. The signerless remote-manager composition uses an authenticated host operation backed by a sealed, owner-filtered `goalidx.manager.<cOwner>.>` scan; no participant credential carries records consumer create or delete. Writer: the **goal-writer** principal (\xA713.9), which composes the commit principal with three additions, this index subtree among them, and NOT the bare commit principal, whose enumeration does not reach this kind. The two are separated because the index is created BEFORE the bind, so the principal that writes it is the one that also binds; a deployment that grants the index on the bare commit row has widened every commit principal to reach a key only the goal writer needs |\n| `goaleff` | `goaleff.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>.<gen>` (atomic; the at-most-one-launch election for one accepted action, written create-only by the effects executor that wins it and advanced by revision-CAS through its phases). `<gen>` is the accepted submission's **EPJ `sourceSeq`**, the sequence it was delivered at, carried verbatim into the acceptance fact; the only discriminator that exists at the EARLIEST coordinate, since `goalidx` is created before the bind and therefore before any decision fact exists, so a decision sequence cannot key it. The generation token is what keeps this kind out of the one-use-forever trap: a lawful later acceptance under the same `goalId` gets a different `<gen>` and a fresh key, never a permanent tombstone. Writer: the owning endpoint's **commit path** ONLY (\xA713.9), inherited by the goal-writer principal that composes it; the generic per-kind spec/status writer row does not reach it, because this kind is unsplit and has no `.spec`/`.status` to write. The value machine, including which actor may settle a row, is *The two coordination machines* below |\n| `epname` | `epname.<endpoint>.<nameToken>` (atomic; the durable claim on one name, keyed by the NAME rather than by a caller triple, because the thing being made exclusive is the name and two callers must contend on one key). Writer: the owning endpoint's **commit path** ONLY (\xA713.9); unsplit, so create-only for the claim and revision-CAS for every state change. The state machine, its actor roles, and the claimant union are *The two coordination machines* below |\n| `epmig` | `epmig.<endpoint>` (atomic; the endpoint's cutover manifest: the inventory a migration is performed against, and the durable record of the cutover runs performed against it, so a run generation is never reused by a later run). That run generation is **scoped to cutover and is key material nowhere else**: the `<gen>` token in the `goaleff` grammar is the accepted submission's EPJ `sourceSeq` and only that, the `goal`, `goalidx`, and `goal\u2026.result` grammars carry no generation token at all, and an implementation that keys any of them from this manifest has built an election two conforming peers can never meet inside. Writer: the owning endpoint's **commit path** ONLY (\xA713.9); unsplit, and its qualifier profile is `[qEndpoint]` alone, one manifest per endpoint, never one per caller or per run |\n| `cp` | `cp.<endpoint>.<token>` |\n| `lease` | `lease.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (the item's acceptance identity, \xA713.2) |\n| `lifecycle` | `lifecycle.<owner>.<actor>.<lifecycleUid>` (the \xA713.1 mapping detail) |\n| `lifecycle` head | `lifecycle.<owner>.<actor>`; the alias's **authoritative current mapping**, and the ONLY key `mappingRevision` (\xA713.3) counts: a **single unsplit key** (NOT `.spec`/`.status`-split; the mapping is one atomic record, and a handler's \"fresh current mapping\" read is one leader-consistent read of this key returning `{ mapping, revision }`, the revision being the STORE revision, never a value field), CAS-updated, NEVER-DELETED (the head discipline: no grant permits DEL/PURGE, true absence alone is virgin, a deletion marker refuses loudly as corruption). States `active | retiring | retired` (\xA713.1): the mapping is current ONLY at `active`; `retiring` is the op-bound containment phase, non-current and not replaceable; `retired` asserts the completed \xA713.1 barrier. Activation CASes it from none (create-only) or from a `retired` predecessor to a freshly reserved UID's mapping; two concurrent mints for one alias cannot both win the CAS; the terminal barrier CASes `active \u2192 retiring` at its bar and `retiring \u2192 retired` as its final head step. The per-UID `lifecycle.<owner>.<actor>.<lifecycleUid>` detail below is optional append-only audit, never the authority |\n| `uid` | `uid.<lifecycleUid>`; the \xA713.1 **space-global UID reservation**: a **single unsplit key**, create-only, NEVER-DELETED, value = `{ owner, actor, mintedBy }` (the reserving authority and intended alias, audit only; the KEY is the reservation). A key exists for every UID ever reserved, including burned candidates; a DEL/PURGE marker is corruption |\n| `policy` | `policy.<endpoint>.<digest-hex>`; the \xA713.6 **immutable admission-policy version**: a **single unsplit key** per policy version, create-only, NEVER-DELETED. `<digest-hex>` is the SHA-256 hex (64 chars) of the record's canonical value bytes, so the key is SELF-CERTIFYING: a reader re-digests the value it read and refuses a mismatch. Immutability is a TRUSTED-WRITER invariant (create-only CAS by the sole writer) BACKED by that read-time self-certification, not a broker subtraction (KV create/update/delete share the one subject, \xA713.9): a different-byte overwrite is refused on read, and the residual (a DEL or same-byte overwrite by a buggy/compromised writer destroying availability under history 1) fails admission closed rather than admitting a lost policy. `enforcedPolicyKey`/`pendingPolicyKey` on the govern head (\xA713.6) name keys of exactly this kind, which is what keeps BOTH the enforced and the pending policy readable through a mutation's whole drain window. Writer: the provisioner registration path ONLY (\xA713.9); a DEL/PURGE marker is corruption |\n| `oblig` | `oblig.<targetUid>.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`; the \xA713.8 **target-indexed acceptance obligation**: a **single unsplit key** whose grammar IS the deterministic acceptance identity (target lifecycle UID first, so a retirement barrier enumerates `oblig.<targetUid>.>`), create-only winner, monotonic value states, NEVER-DELETED. An admission under policy with NO target lifecycle keys the row with the fixed sentinel target token `ep` (which the \xA713.1 UID token grammar can never produce, so no collision exists): `oblig.ep.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`: excluded from retirement drains (it binds no lifecycle) and included, like every targeted row, in the endpoint's policy drain via the endpoint-position filter `oblig.*.<endpoint>.>` (\xA713.6/\xA713.8) |\n| `frontier` | `frontier.<lifecycleUid>`; the \xA713.1 **per-stream retirement frontiers**: a **single unsplit key** per retired lifecycle, create-only, NEVER-DELETED, value = `{ lifecycleUid, opId, streams }` where `streams` maps each lifecycle-bounded stream to its last sequence at retirement. Written by the terminal barrier AFTER the obligation drain, the drain's repair-principal fence, the pool cleaner, and the cleaner-credential revoke+evict, and BEFORE the gate/head terminals (\xA713.1 order), so a `retired` head implies its frontier exists. The cutoffs bound the predecessor's half-open interval `(activationFrontier, retirementFrontier]` (\xA78); they are never a successor's start (a successor captures its OWN activation frontier). Writer: the minting authority's retirement barrier ONLY; it records once, under its own operation (a foreign-op record refuses the barrier closed); a DEL/PURGE marker is corruption |\n| `govern` | `govern.<endpoint>`; the endpoint's **governance head**: a **single unsplit key** (NOT `.spec`/`.status`-split), value = the endpoint's MONOTONIC binding map, command to governed URN set, the NORMATIVE **admission-policy selector** `{ enforcedPolicyKey, enforcedPolicyRevision, pendingPolicyKey?, pendingPolicyRevision? }` (\xA713.6: `enforcedPolicyKey` is the exact records key of the immutable `policy` record currently governing admission and `enforcedPolicyRevision` its store revision, so any implementer selects the endpoint-wide enforced policy WITHOUT per-instance guesswork; a mutation stages `pendingPolicy\u2026` and promotes it into `enforcedPolicy\u2026` only after the endpoint's obligation drain, so the selector alone decides which revision governs during the drain window), plus whatever internal serialization state the provisioner's registration CAS needs (that state is non-normative: a second implementer may linearize registration with a different slot shape and conform, provided every registration contends on this head under its frozen gate through spec publication, the policy selector fields carry the meaning above, and the external guarantees hold). One of those external guarantees is LIVENESS of the linearization itself, and it is normative however the slot is shaped: an in-flight registration that stops before its spec publication MUST NOT block the endpoint's registrations permanently. Whatever state a registration holds on this head, an implementation MUST be able to decide that state ABANDONED from durable facts rather than from a liveness probe, and a later registration MUST then be able to take it. The reference implementation decides it by comparing the held state's recorded gate generation against the holder's live issuance gate: a gate that has reopened past it proves the hold can never complete, since completion requires that same generation still frozen. An implementation that cannot make that determination MUST refuse rather than take the hold, because an in-flight registration and an abandoned one are otherwise indistinguishable, and taking a live one would put two registrations through the linearization point at once. Enforcing the governed-attachment no-strip/no-downgrade mandate (Traits, below) is a HISTORY-bearing, ENDPOINT-WIDE property: a fresh instance, a remove-then-re-add, or a concurrent registration must not launder a governed binding away, so this head is also the endpoint's **registration linearization point**. Writer: the provisioner registration path ONLY (\xA713.9); NEVER-DELETED, per the `lifecycle`-head discipline |\n\n| `run` | `run.<endpoint>.<runId>`; a **workflow run's** last-value-wins state beside its append-only step journal (\xA714). `.spec`/`.status`-split, and the split is load-bearing: the spec is what the run IS, decided once at start and never rewritten (`{ v: 1, run, pins, createdAt }`, the resolved PIN SET of \xA714.3), the status is what it is DOING (`{ v: 1, observedSpecRevision, state, holder, epoch, fencingToken, journalHigh, at }`), so a lease renewal can never rewrite the pins. `<runId>` is an id token minted by the DRIVER, never caller-supplied and **never reused**: a run is never re-run under its own id (that is a fork, and a fork takes a new id), so a deleted `run` key staying closed is correct and no generation token is owed. A fork's child is a new run under a new id and this revision records no lineage on it (\xA714.3); a later revision that adds a parent field puts it on the SPEC half and never the status half, because parentage is decided at creation and a status-half lineage could name a different parent after a takeover. Writer: the run driver's commit path ONLY (\xA713.9) |\n| `answer` | `answer.<endpoint>.<token>.<answerId>`; a checkpoint's ANSWER payload beside its one-use settle fact (\xA713.6, `answerId`/`settledAnswerId`): a **single unsplit key**, create-only, never updated and never deleted, value `{ v: 1, token, answerId, value?, artifact?, by, at, supersedes? }` (`supersedes` only on an amendment, \xA714.5). **Keyed per answer rather than per presenter because a workflow checkpoint's holder is the run driver and every resolver reaches the checkpoint through it, so every presenter is the same principal**: a presenter-keyed slot collapses to one, two racing resolvers overwrite it, and the settlement then selects whichever answer was written last rather than the one that won. `<answerId>` is derived from the answer's own content (\xA714.5), so a retry after a crash lands on its own record with its own bytes; an amendment's is minted fresh per filing (\xA714.5). Writer: the run driver's commit path ONLY (\xA713.9) |\n| `notice` | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>`; one bounded decision a workflow told one agent (`notify`, [`spec/cotal-lang.md`](spec/cotal-lang.md) \xA76.8), filed onto the run and rendered ahead of that agent's next turn, never a channel message. `.spec`/`.status`-split: the spec is the notice (`{ v: 1, run, step, addressee, fact, at }`) and is create-only, the status is its consumption (`{ v: 1, consumedAt, by, observedSpecRevision }`). **`<addresseeId>` is a digest of the agent's name and never the name, because an agent name is dotted and a dot is the key separator**: a raw name re-tokenizes the key into a key of another shape, and mangling it destroys the identity being keyed on; a reader holding the handle re-derives the same token (\xA714.5), so per-addressee enumeration stays one prefix scan. `<noticeId>` is derived from the step's request id and the addressee, so a `notify` re-run after a crash lands on the same records. Writer: the run driver's commit path ONLY (\xA713.9) |\n| `migration` | `migration.<endpoint>.<runId>.<migrationId>`; one run's move onto edited source ([`spec/cotal-lang.md`](spec/cotal-lang.md) \xA711.2): what the divergence-and-orphan check found, which refusals a person overrode, and who they were. `.spec`/`.status`-split: the spec is the REPORT (`{ v: 1, run, fromHash?, toHash, at, consumedThrough, orphans[], overrides[], actor }`) and is create-only, the status is the APPLICATION (`{ v: 1, appliedAt, by, observedSpecRevision }`) and names the driver that advanced the run. Its own kind because it is neither half of the run record: a migration is append-only history with an actor on it, and a run can migrate more than once, so the status half would let the second erase the first and the spec half cannot be written twice. **`<migrationId>` is a digest of the report's own content and never a counter**, because a migration is decided by a dry walk a crash can force to be re-run, so the same decision must land on the same record rather than filing a second one, and a counter would need a second arbiter for a fact the content already determines (\xA714.5). **The application is create-only for the same reason the notice's consumption is**: two drivers racing to advance one run both find no status and both write, and the store decides which one moved it. Writer: the run driver's commit path ONLY (\xA713.9) |\n\nThird-party kinds\nregister under reverse-DNS kind names.\n\n**The two coordination machines.** `goaleff` and `epname` carry closed value machines. A row's\nlegal field set is fixed per phase or per state, and a writer that presents a field the phase does\nnot define, or omits one it does, is refused rather than accommodated: a single broad object with\neverything optional cannot express that a field is present exactly when a launch is in flight, and\npresent-exactly-when is the only form in which those fields decide anything.\n\n`goaleff` has four phases: `claimed`, `launching`, `launched`, `settled`. Every row carries `v: 1`,\nthe electing `executor` as an incarnation `{ instanceId, processEpoch }`, the `attemptId` nonce of\nthe attempt that won the election, and `ts`. `launching` and `launched` additionally carry `addr`,\nthe allocated address `{ nameToken, lifecycleUid }`; `settled` MAY carry it; `claimed` MUST NOT.\nThe legal edges are `claimed \u2192 launching`, `claimed \u2192 settled`, `launching \u2192 launched`,\n`launching \u2192 settled`, and `launched \u2192 settled`. `settled` is terminal because no edge leaves it,\nwhich is the terminality rule itself rather than a separate check that could come to disagree with\nthe table. The `executor` and `attemptId` do not move across an edge, and an allocated `addr` is\nnever rewritten to a different one.\n\nTwo actor roles take those edges. An **executor** may take any of them and MUST be the row's own\nexecutor at the row's own `attemptId`: a re-read that finds a foreign incarnation or a foreign\nnonce is a loss, never a licence to proceed. A **sweeper** acts for an executor it believes is gone\nand MAY take only the edges into `settled`, because advancing a launch phase on a dead executor's\nbehalf is the split brain the election exists to prevent, and the resulting row is\nindistinguishable from the executor having advanced it. An actor presenting neither role is\nrefused; an unrecognized role that falls through both checks is the most permissive possible answer\nto the question of who is acting.\n\nEvery settle is gated on the goal's terminal fact **already existing**. Settling without one\npublishes a row asserting that a goal finished when nothing durable records that it did, so the\nterminal-first order is normative and the reverse order is never legal. A crash between the two is\na row left un-settled with its terminal present, which is recoverable; the reverse would not be.\n\n`epname` has seven states: `claimed`, `launching`, `live`, `preserved`, `relaunching`, `draining`,\n`released`. Every row carries `v: 1`, `ts`, `state`, and `claimant`, which is either `null` or one\nof three kinds: an **action** claim `{ goalId, gen }`, a **direct** claim\n`{ instanceId, processEpoch, opId }`, or an **incumbent** claim `{ backfillId }` recorded by a\ncutover backfill. A launch in flight (`launching`, `relaunching`) additionally carries\n`lifecycleUid`, `launchAttemptId`, and the `executor` incarnation; a name that is up (`live`,\n`preserved`) carries `lifecycleUid` and `runtimeOwner`; `draining` carries `lifecycleUid`,\n`runtimeOwner`, and `enteredAt`; `claimed` and `released` carry the base fields alone.\n\n`runtimeOwner` is the incarnation that owns the handle table for the name, and it is **moved, never\nderived**. It MOVES on the four launch-resolving edges, `launching \u2192 live`, `relaunching \u2192 live`,\n`launching \u2192 draining`, and `relaunching \u2192 draining`: the row's full `executor` incarnation becomes\nits `runtimeOwner` and `launchAttemptId` is cleared, recorded at the moment it becomes true. Both\nfields of the incarnation move together, because an `instanceId` without its `processEpoch` names a\nprocess rather than the run of it that holds the handle table. On the three edges that neither\ncreate the row nor resolve a launch, `live \u2192 preserved`, `live \u2192 draining`, and\n`preserved \u2192 draining`, it is CARRIED unchanged. The one creation edge that produces a `live` row,\nthe cutover backfill, INSTALLS it instead, read from the incumbent's own live gate row: a cutover\nthat cannot read one MUST record a casualty rather than backfill, because a `live` row whose owner\nis unknown puts an unevaluable value into the durable record that every later release reads. Except\non that edge it is never reconstructed from any other row, because a supported deployment mode has no such row to read and a\npredicate that cannot be evaluated on a supported path either refuses forever or falls back to\nabsence. An `instanceId` alone will not stand in: an identity is not an incarnation, and a\nrestarted process under the same identity holds an empty handle table, which is the absence of\nknowledge rather than knowledge of absence.\n\nSix actor roles take the `epname` edges. An **allocator** creates a claim (`\u2192 claimed`, and\n`released \u2192 claimed`, so a released name is claimable again and the row is never deleted). A\n**claimant** drives its own launch (`claimed \u2192 launching \u2192 live`) and may abandon an unlaunched\nclaim (`claimed \u2192 released`). A **holder**, identified by the row's `lifecycleUid`, drives the\npreserve cycle (`live \u2192 preserved \u2192 relaunching \u2192 live`). A **sweeper** may release an unlaunched\nclaim and may move `launching`, `live`, `preserved`, or `relaunching` into `draining`. A\n**cutover** may establish a `live` incumbent directly, which is the backfill path. An **operator**\nhas exactly one edge, `draining \u2192 released`.\n\nThat last edge is operator-only by design rather than by omission. An ordinary release would\nrequire an actor attesting that a runtime is gone, and no such actor can exist: an owner still\nalive has no per-attempt handle to attest about, and a restarted one is a different incarnation.\nThe edge is therefore removed rather than weakened, and `draining` is a state an operator clears by\nhand until a durable runtime-attempt token exists. Two consequences follow and are normative. A\ngoal reaching a `succeeded` terminal does **not** release the name it holds; and release is a\ntransition to `released`, never a delete, so the row survives to answer who held the name last.\n\n**The actor roles above are entitlements inside the value machines, not wire principals, and which\nprincipal may present each of them is unspecified: RAISED, NOT SETTLED.** The write grants on both\nkinds are the commit path and the goal-writer principal that composes it (\xA713.9). No sweeper,\noperator, allocator, or cutover principal is granted anywhere in this document, so this section\ndoes not say whether a conforming sweep runs under the commit principal or under a principal a\ndeployment would have to add. An implementation MUST NOT read a role in these machines as\nconferring a grant, and a deployment that needs a distinct sweep identity is outside what this\nversion specifies.\n\n**Descriptor and describe.** Each instance registers a **service record** (kind `svc`, key\n`svc.<endpoint>.<instanceId>`; the owner is determined by the name and recorded in the\nvalue): spec = `{ endpoint, owner, endpointType?,\nclusterDigests[], protocol: { v: 1 | 2 }, activation? }`, status = `{ epoch, state,\nobservedSpecRevision, \u2026 }` (writer table \xA713.9). The spec key's **store revision is the\ninstance's `registrationRevision`**, the value scatter freezes (\xA713.5): it advances only\nwhen the mediated registration path writes the spec key, so an advance during a scatter is\nexactly a re-registration. `describe` is a reserved untargeted\nephemeral command every endpoint MUST serve, returning the descriptor with clusters inline or\nby digest. **Authorization-scoped answers use a trusted authorization source only**: the\nanswer is intersected against a fresh view of the caller's authority obtained from the\ndeployment's authorization ledger/callout (\xA79/\xA710), keyed by the broker-authenticated caller\nidentity, never against payload- or slot-asserted scope, which is ignored. If the trusted\nview is unavailable or stale beyond its declared freshness bound, describe fails closed\n(`unavailable`) rather than answering from a weaker source; deployments MAY declare an\nendpoint's descriptor public, in which case no view is consulted and the answer says so.\nDescriptor visibility is never inferred from reachability of `describe` alone. A KV browse\nindex (record kind `contracts`) is an advisory convenience copy; `describe` is authoritative.\n\n**Manager-service records.** A remote manager registration is one closed, opaque-instance family:\nits `svc.manager.<instanceId>` spec/status pair, its instance-bound contract closure, and its\n`epgate.manager.<instanceId>` / `epcred.manager.<instanceId>.<credentialId>` rows all name the\nsame server-authorized `{ owner, managerActor, lifecycleUid, instanceId }` tuple. The registration\nmediator MUST reject any tuple mismatch, instance collision, contract substitution, or status/gate\noperation from another principal or lifecycle. It may publish only the contract artifacts staged by\n`prepare`; it may not use manager-service authority to publish a contract for any other endpoint.\nRetiring the family retires the instance record and gate together; no stale stage, registration,\ncontract, status, or credential can activate a new lifecycle or another instance. `describe` and\nstatus report the manager instance's serving/degraded state without treating discovery as\nauthorization (\xA713.9).\n\n**Invocation binding.** The digests are not caller courtesy but a two-sided requirement\n(\xA713.3): a caller MUST pin `op.inputDigest`/`op.outputDigest` on every command except\n`describe` (the discovery bootstrap), and a serving member MUST reject their absence\n(`contract-mismatch`) before any effect; an unpinned invocation cannot silently bypass the\ndescribe\u2192invoke binding, and MUST honor pinned digests or reject `contract-mismatch`. Rolling updates keep classes contract-homogeneous: an incompatible\ngeneration registers a distinct routable identity (new endpoint name or explicit version\nlabel) until homogeneous.\n\n**Traits.** A trait attaches governed metadata to a cluster, command, attribute, or event.\nA **trait definition** `{ urn, valueSchema (digest), selector, breakingChanges, authority }`\nis content-addressed and signed: `ai.cotal.*` definitions by the space-operator authority;\nthird-party definitions by their defining owner's registered key. **Attachment authority is\ndistinct from definition authority**: every *required/governed* attachment (this revision governs\nexactly `ai.cotal.guarded` and `ai.cotal.priced`) is separately signed by the definition's\nnamed authority over `{ endpoint, command, contractDigest (the cluster document's complete\nclosure digest), traitUrn, value }`, so a self-published descriptor cannot strip, forge, or downgrade a governed\nannotation; removal or downgrade is an authorized contract revision. Enforcement is\nfail-closed at the pre-effect seam: missing, unverifiable, or stale governed attachments\nrefuse before effect. Non-governed traits are unsigned vocabulary.\n\n**Compatibility.** Cluster evolution is BACKWARD by default: within a revision line, changes\nMUST be additive and added fields MUST carry defaults; removal, rename, or semantic change\nmints a new cluster URN version. A push-time JSON-native compatibility differ + review gate\nenforce this in the reference workflow (repository tooling under `scripts/`, not shipped\nclient code). The discovery protocol itself is versioned under `protocol.v`, additively by\ndefault: a bump is reserved for a change a client cannot safely ignore, and `effect` (\xA713.7) is\nthe one such change so far \u2014 a client that ignored it would keep performing exactly the retry the\nfield exists to stop, so it refuses the document instead.\n\n### 13.8 Distributed guarantees\n\n- **Idempotency scope.** Ephemeral idempotent commands by `id` (handler-local, within result\n  retention); journaled submissions and actions by `id`/`goalId` + fingerprint within the\n  declared horizon. Exactly-once is bounded honestly: delivery is at-least-once; Cotal\n  guarantees idempotent submission/fact recording and fenced commits of Cotal-owned state; an\n  external side effect is exactly-once only when the external API honors the propagated\n  idempotency key or fencing token, else the contract documents at-least-once effects. A\n  workflow step inside a `once` scope (`spec/cotal-lang.md` \xA77.8) is dispatched at most once per\n  step key whatever the far side honors, a dispatch being one call of its handler under its request\n  id that the handler does not refuse (the handler may retry inside that call): a resume that finds\n  it begun and unsettled opens a hold under a token derived from its recorded request id instead of\n  dispatching it again, trading the run's liveness for the bound.\n- **Repeat versus resubmission.** **A command that is idempotent by `id` is NOT thereby `read`:\n  safe to resubmit is not safe to repeat.** That is the rule neither mechanism states alone, and\n  declaring such a command `read` licenses a fresh-`id` retry that duplicates the effect. The two\n  properties are independent; a command may hold either, both, or neither.\n\n  A **resubmission** is a re-send the responder CONVERGES onto the decision it already recorded; a\n  **repeat** is a re-send it accepts as new work. Reusing the `id` is how a caller ASKS for\n  convergence, and within the horizon below it is how convergence is keyed \u2014 but the `id` is the\n  request, not the answer, and a re-send under a reused token that the responder accepts as new\n  work is a repeat by this definition. `effect` (\xA713.7) governs repeats, whatever token they\n  carry. `id` governs resubmissions \u2014 and what `id` alone is worth differs by rail:\n  - **Ephemeral** \u2014 `id` is the whole key. A same-`id` resubmission within result retention is\n    the same call; an idempotent command may dedup on it and consult nothing else.\n  - **Journal** \u2014 `id` is necessary but NOT sufficient. It is one of the fields the fingerprint\n    binds, so a same-`id` resubmission converges to the first outcome only if the rest of the\n    fingerprint matches too. Same `id` with different args is neither a resubmission nor a fresh\n    call: it is a loud `conflict` (\xA713.4), because the decision subject is already occupied by a\n    fact with a different fingerprint. A caller that mutates arguments and reuses an `id`\n    therefore gets an error rather than either behaviour it might have expected from the\n    ephemeral rail.\n\n  **Both rails are bounded by a horizon, and outside it neither rule applies.** A resubmission is\n  a resubmission only while the prior decision is still retained \u2014 the idempotency horizon is\n  realized by decision-fact retention on the journal rail and by result retention on the ephemeral\n  rail, never by a clock (\xA713.4). Once the retained decision is gone, the `id` carries no history:\n  a re-send under it is a fresh call that WILL execute, and the same `id` with different args is\n  no longer a `conflict` but simply a new submission. The finite horizon is what makes the decision\n  store finite, so this is a fact callers MUST hold rather than a hole to be closed \u2014 but the hole\n  it WOULD open if `repeat` were defined by the token is closed at the definition above: a re-send\n  the responder accepts as new work is a **repeat**, so a post-horizon same-`id` re-send of a\n  `write` is exactly what \xA713.7 prohibits a client from making automatically. Reusing the token\n  buys nothing outside the horizon, and a caller that cannot establish it is still inside one has\n  not established that its re-send is safe.\n\n  Neither word is \"retry\": callers retry under a reused `id` and under a fresh one and mean the\n  same English word both times, which is the confusion this paragraph exists to remove. And the\n  dangerous reading is a REASONABLE one, not a careless one \u2014 an operator who has correctly\n  learned that a command is idempotent by `id` will retry it after a timeout, mint a fresh `id`\n  because the old request is gone, and get a second effect. Nothing in this document told them\n  those were different acts until now.\n- **Fencing and mediated commits.** Every Cotal-owned authoritative transition flows through\n  its mediated writer (\xA713.9) carrying `(fencingToken | lifecycleUid | epoch)` as applicable;\n  the writer validates token currency, unexpired lease against its own clock, lifecycle\n  currency, and epoch currency. Value-carried tokens + CAS stop conforming-but-stale writers;\n  scoped credentials + mediation stop everything else. The threat boundary of any\n  direct-owner write is explicitly downgraded (\xA713.9).\n- **CAS conflict.** Any lost CAS is a loud `conflict`; the loser re-reads and re-decides.\n- **Authority-head reservation/drain.** An authority head (the \xA713.1 lifecycle head; the\n  \xA713.6 registered admission policy) and a durable acceptance/start fact live in different\n  streams; no cross-stream CAS exists, and a revision carried inside a fact is provenance,\n  never a fence. Any durable acceptance or start that creates work bound to a lifecycle,\n  or admits work under a policy read, therefore contends with the head's movement on ONE\n  durable serialization coordinate: the **target-indexed obligation row** (kind `oblig`,\n  \xA713.7). In order: (1) BEFORE the EPF decision publish, the writer obtains the obligation\n  through the **admission mediator**. The mediator owns the `oblig.` prefix (the\n  canonicalizer holds no raw write on it), derives the coordinate from the\n  broker-authenticated request subject (never from a body field), and IMMEDIATELY before\n  the create performs the FENCING currency reads it will pin: for a target-bound\n  admission a leader-served read of the target's lifecycle head, REFUSING unless the state\n  is `active` (a `retiring` or `retired` target admits nothing); for a policy-admitted\n  decision a leader-served read of the governance head (\xA713.6) that FIRST refuses if a\n  `pendingPolicyKey` is present (the endpoint is inside its drain window; the drain-window\n  admission pause is a normative step of THIS algorithm, not only a \xA713.6 property, so any\n  conforming mediator refuses without needing to infer it) and only then follows\n  `enforcedPolicyKey`, self-certifies it (\xA713.7), and pins its `enforcedPolicyRevision` as\n  `policyRevision`. Refusing at the create-fence (not only at the post-create recheck) is\n  also what bounds the row set: a request that could not create its row leaves no\n  never-deleted `oblig` debt behind, so a long or crashed drain cannot accumulate an\n  unbounded set of rejected rows. An admission with no target lifecycle keys the\n  row under the fixed sentinel target token `ep` (\xA713.7). It then creates the row\n  create-only at the deterministic acceptance-identity\n  key `oblig.<targetUid>.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`. The KEY never contains\n  `sourceSeq`, delivery attempt, mapping revision, or writer op id (a redelivery of the\n  same logical acceptance MUST land on the SAME key); where a digest stands in for the\n  tuple it is a versioned, collision-resistant digest of exactly that tuple, never\n  delimiter-ambiguous concatenation. The VALUE pins the first winner under a CLOSED\n  per-class schema: every row carries `{ state: provisional | accepted | rejected |\n  terminal, decision: epf | self, opId }` plus the currency pins taken above\n  (`mappingRevision` iff target-bound, `policyRevision` iff policy-admitted; at least one\n  present); an `epf`-class row (a canonical acceptance) adds `{ fingerprint, sourceSeq,\n  route }`; a `self`-class row (a guarded record commit, e.g. the restart-status CAS,\n  \xA713.6) adds the COMPLETE commit intent `{ commitKey, commitBaseRevision, commitValue,\n  commitDigest }`: the exact record key its accepted state authorizes, the store revision of\n  that record the commit CASes FROM, the value it commits, and that value's digest.\n  `commitValue` is a CLOSED discriminated union, so two implementations resolve and replay the\n  SAME value: `{ enc: \"b64u\", bytes }` carries a JSON encoding of the committed value,\n  base64url-encoded (RFC 4648 \xA75, no padding), or `{ enc: \"ref\", key }` names an\n  IMMUTABLE, create-only records key (the \xA713.7 `policy` kind or another never-overwritten\n  key) whose stored value IS the commit value; a mutable or absent `ref` target\n  refuses at recovery, fail-closed. Never only a digest (a digest cannot reconstruct the\n  value a crash recovery must re-write). `commitDigest` is the RFC-8785 CANONICAL content\n  digest of the committed value, `sha256:<hex>` (the same `*Digest` scalar shape \xA713.7 uses\n  everywhere; over the CANONICAL value, never a non-canonical storage stringify, so the\n  landed/not-landed comparison is insensitive to how the store serializes the record). A\n  crashed writer's commit is thus deterministically finishable from the row alone (below). The\n  `decision` class is fixed by the TRUSTED operation kind, never caller-selectable. A\n  create loser leader-reads the winner: the FULL pinned identity must match to join (an\n  `epf`-class row on coordinate + fingerprint + route; a `self`-class row on the ENTIRE commit\n  intent `commitKey` + `commitBaseRevision` + `commitDigest`, so two different desired values\n  or base revisions never join under one `commitKey`); any\n  mismatch is `conflict`, never a second obligation. (2) **Proof issuance is a post-create\n  currency recheck, and admission is proof-gated**: after winning or joining the create,\n  the mediator leader-reads the SAME coordinates AGAIN, and only if the target head is\n  still `active` at the pinned `mappingRevision` AND (for a policy-admitted decision) the\n  governance head STILL stages no `pendingPolicyKey` and the enforced policy is still at\n  the pinned `policyRevision` does it return the opaque admission proof; otherwise it\n  IMMEDIATELY settles its own provisional through the row's decision coordinate (below) and\n  refuses. The recheck reads the SAME govern head the create-fence read, so a\n  `pendingPolicy` staged in the window between the create and the recheck also fails\n  proof issuance, not merely a moved `enforcedPolicyRevision`.\n  No target-bound or policy-admitted EPF acceptance may publish, and no `self`-class\n  guarded commit may run, without an unexpired proof issued under this rule. This is the\n  structural half of the head fence: an obligation created in the window between a fresh\n  `active` read and a head or policy movement exists durably, but its proof can never\n  issue, so it can never admit; it is inert cleanup debt any later drain settles. (3) The\n  EPF decision CAS runs as\n  specified (\xA713.4), publishing with the WINNER's pinned acceptance identity and\n  `sourceSeq`, whichever delivery is processing; a `self`-class writer instead advances\n  its own row `provisional \u2192 accepted` (revision-pinned) and performs its guarded commit\n  only while the row is `accepted`. (4) On acceptance the SAME key advances\n  `provisional \u2192 accepted` and is retained until the accepted route is\n  terminal and cleaned: the only enumerable record of accepted work is never\n  erased at the moment it wins. States are monotonic (`provisional \u2192 accepted \u2192\n  terminal`, or `provisional \u2192 rejected`), the row is NEVER-DELETED, and a DEL/PURGE\n  marker is corruption. The stored `opId` is not a bearer capability: a resuming writer\n  re-authenticates as the same endpoint-scoped principal through the mediator and joins\n  by acceptance identity + fingerprint; any opaque reservation token the mediator issues\n  is target/endpoint/connection-bound, bounded-lived, and checked against the CURRENT\n  obligation state; the durable obligation is the authority, never possession of its\n  identifier. **The decision coordinate is per-class** and is where every unresolved row\n  settles: an `epf`-class row settles through the EPF decision subject's create-only CAS\n  (read the winner; if absent, create-only publish the terminal rejection so a delayed\n  acceptance CAS loses; the mediator holds that rejection-publish authority and executes\n  it for its own recheck refusals and on behalf of the drains, \xA713.9); a `self`-class row\n  settles on ITSELF: while still `provisional`, the drain CASes `provisional \u2192 rejected`\n  (the writer's `provisional \u2192 accepted` CAS and the drain's rejection contend on the ONE\n  row, exactly one wins, and a delayed guarded commit finds its authority gone). An\n  `accepted` `self`-class row is NOT stuck and does NOT block quiescence: because the row\n  pins the complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }`,\n  either\n  the writer's own resume OR a drain reconciler drives it `accepted \u2192 terminal`\n  deterministically. Read the record at `commitKey`: if its value canonically digests to\n  `commitDigest` the commit landed, CAS the row `accepted \u2192 terminal`; if it is still at\n  `commitBaseRevision` the commit did not run, re-apply it by CASing the resolved\n  `commitValue` (decode `b64u`, or leader-read the immutable `ref` key's value, verifying its\n  canonical digest against `commitDigest` BEFORE writing) at\n  `commitBaseRevision` then CAS the row terminal; if the\n  record has moved PAST\n  `commitBaseRevision` to a foreign value the intended commit can never land (the guarded\n  CAS would lose), so CAS the row straight to `terminal` as superseded. Quiescence therefore\n  means NO `provisional` and NO un-driven `accepted` `self`-class rows remain: an accepted\n  commit is always completable from the row alone, never an unrecoverable orphan. **Reclamation is never\n  clock-only**, and because the EPF writer need not be the retiring lifecycle (a\n  cross-endpoint canonicalizer publishes decisions bound to a foreign target, and revoking\n  the TARGET's credential family disarms nothing that writer holds), target-side\n  revocation alone is NEVER the reclamation condition. An unresolved `provisional` is\n  reclaimed only by: settling it through its decision coordinate; or revoking +\n  verified-evicting the WRITER's own commit authority; or the target head being\n  non-current AND the drain below having completed to quiescence under the create fence +\n  proof gate. A timeout alone never frees a slot\n  while the writer retains publish authority. **Drain to quiescence**: after the head\n  CASes to `retiring` (\xA713.1), and equally when a policy mutation must enforce a new\n  revision (\xA713.6, enumerating `oblig.*.<endpoint>.>`), the drain enumerates the prefix\n  (`oblig.<targetUid>.>` for retirement), settles every\n  unresolved row through its decision coordinate, completes accept-side reconciliation\n  (enqueue/goal/terminal, \xA713.6) for accepted rows, then RE-ENUMERATES, and records its\n  cleaner and frontier completion (or treats the new policy as enforced) only when an\n  enumeration finds no unsettled row. A provisional whose pinned `mappingRevision` or\n  `policyRevision` is no longer the live coordinate is settled as REJECTION, never treated\n  as still open for acceptance. A row created after the final enumeration cannot admit\n  (its proof can never issue, step 2) and is settled by any later enumeration;\n  an acceptance published after the recorded cleanup frontier from a\n  stale `active` read is non-conformant even if later effect resolution would reject it.\n  Whether the obligation is released once the route is settled under ordinary policy\n  movement (`release-after-accept`) or survives as cleanup debt the terminal barrier must\n  observe (`promote-to-lifecycle-obligation`) is fixed by the TRUSTED operation kind,\n  never caller-selectable. The admission-policy specialization additionally binds\n  identity at the read: the confined policy reader's request subject pins the\n  authenticated canonicalizer endpoint AND the requested policy endpoint, requires their\n  equality, derives the reply rail from that authenticated subject, and returns\n  `{ policy, revision }` with an opaque proof binding `{ space, endpoint, policy\n  revision, obligation/op id }`; endpoint A can never obtain, or replay, endpoint B's\n  admission proof.\n- **Retry/backoff.** Only idempotent-at-scope operations are retried: exponential backoff,\n  base 250 ms, factor 2, cap 15 s, full jitter, bounded by the caller deadline.\n- **Deadlines.** Mandatory on call, scatter, claims, checkpoints, timers, sessions. Reference\n  default call deadline 15 s; defaults are overridable, never removable.\n- **Cancellation ordering.** First terminal fact at the mediated commit point wins.\n- **Watch recovery.** Fell-behind \u21D2 snapshot re-read then resume; bounded relist; no silent\n  gap-skipping.\n- **Ordering/partitioning.** Per-subject only; the subject is the partition key.\n- **Retention floors.** Submissions \u2265 recovery/redelivery lag (\xA713.12; native dedupe is not\n  relied upon, \xA713.4); facts/tombstones \u2265 idempotency horizon;\n  results \u2265 result retention; receipts \u2265 receipt retention; timers \u2265 max deadline + recovery\n  margin. **Pool coupling:** every accepted pool item carries an **absolute work expiry**\n  (`workExpiry`, set at acceptance in the AcceptanceFact, NOT a per-message age a\n  reconciliation re-publish would reset; a re-enqueue re-publishes with the SAME `workExpiry`,\n  and the item is dead once it passes, leased or not). The EPW stream's max age is \u2265 the\n  maximum `workExpiry` + recovery margin, and a pool item's decision and `wrk` terminal facts\n  are retained \u2265 that same bound, so a live (or crash-recovering) item can never outlive the\n  facts that identify it as accepted or settled: a decision that expired under a still-live\n  item would let a reused id collide with the old enqueue, and an expired `wrk` under a\n  lost owner ack would make settled work unrecognizable on redelivery. A reused `id` becomes\n  new work only after the old item's `workExpiry` AND its facts' retention have both passed.\n  An endpoint MUST refuse to start against a store below its declared floors.\n- **Backpressure and budgets.** Bounded consumer pending (default 1024), bounded\n  virtual-endpoint pools and session windows, flow control on watches; overload is\n  `resource-exhausted`. Schema compile/validate budgets (reference: 100 ms / 10 ms) and\n  bounded regex; over budget is `contract-invalid`/`bad-request`.\n- **Timers.** Broker message schedules at the 2.12 floor; same-subject replacement only (at\n  the mediated `.armed` subject, \xA713.12); generation- and scheduler-origin-validated firing\n  (stale or foreign-origin \u21D2 no-op); durable reconciliation repairs\n  status\u2194schedule divergence; replication and offline-assets downgrade fail loud at the\n  broker floor gate.\n\n### 13.9 Authority boundary\n\nThe credential is the coarse boundary; every subject in \xA713.2 is default-deny. Every\n**statically expressible** authorization dimension is broker-enforced through the subject\ngrammar: caller identity + lifecycle, endpoint,\ncommand, the target components each mode pins statically (\xA713.2: the full triple for `self`,\nthe caller's own, and for `handle`, redemption-pinned; the owner for\n`owner`/`any`/`child`/`ledger`), serve identity, reply\n**attribution**, and plane writer ownership.\nReply **addressing** is the one deliberate exception: it is capability-by-secret (the\nper-request nonce, \xA713.2), not a broker grant, and it is sound precisely because serve\ncredentials cannot plain-subscribe the class rail (queue-qualified grants, \xA713.2), so nonces\nare visible only to the instance the queue selected (plus every instance on a scatter, which\nis scatter's definition). Target enforcement is stated per mode, never as a blanket claim:\n`self` is broker-confined end to end including the lifecycle UID; `handle` is broker-confined\non the full redemption-pinned target triple, with the validator re-checking only mapping\ncurrency; `owner`/`any` are broker-confined on the target owner and validator-primary on the\nactor and UID currency; `child`/`ledger` are validator-primary within their distinct broker\nrails. The **named dynamic relations** (static-mesh\nown-child, fresh-ledger escalation, target-mapping currency, authorization epochs after\nacceptance) are trusted-validator-primary by design, fail-closed, and operate only within\nthe broker ceiling. Handlers only narrow. **The process epoch fences only the five planes\nwhose subjects carry it** (reply, `epe`, `ept`, `eps`, `epr`). Request-ingress subjects and durable record\nkeys cannot carry it; the caller cannot know it, and a restart-stable key must not change,\nso those two classes are fenced by the mechanism each admits: records by mediation (writer\ntable below), ingress by credential revocation with verified eviction (\xA713.1), never by\nsubject.\n\n**Caller grants.** Minting maps each named capability to exact endpoint+command subjects:\npublish on the request forms (class + instance) with the authz-mode/target pattern the\ncapability specifies, subscribe on the caller's own reply rail, publish on matching `epj`\nsubmission subjects for journaled commands, and the exact record-key / event-topic subtrees\nfor attribute/event read capabilities (per-goal containment rides the caller triple in the\ntopic). The caller's lifecycle UID token is pinned in every granted subject, so a credential\nis dead against its principal's next lifecycle by construction. Wildcards are bounded: `*` in\nthe command position only when the capability covers every command of the endpoint; `*` in\nthe endpoint position never, outside operator/admin profiles; `child`/`ledger` mode subjects\nare never covered by an `owner`-mode wildcard. `describe` is granted by default for all\nendpoints; a space MAY narrow it. Because the subject shape is verb-invariant (\xA713.2), one\npublish row covers call and cast of a command. Minted credentials MUST stay within the\ndeployment's JWT size envelope, and the envelope is validated against a **normative\nmaximum-capability fixture**, not an adjective: the reference fixture is an agent holding\nevery baseline grant plus capabilities on 3 endpoints x 12 commands each, each targeted\ncommand in both `self` and `owner` modes, plus journaled submissions and per-goal read\nscopes for all of them. Minting MUST fail loud before emitting a credential that exceeds the\npolicy gate (reference: 16 KiB); the transport bound is the CONNECT control line\n(`max_control_line`, \xA713.12) and the policy gate MUST be the tighter of the two. The mint\nMUST also refuse, before any issuance record is written, a user JWT whose byte size exceeds the\ncontrol line minus the CONNECT envelope (`MAX_MINTED_JWT_BYTES`), so a composition of individually\nvalid grants can never produce a credential the broker drops silently. The fixture\nset additionally includes a **maximum-command serve credential** (a 12-command endpoint's\nper-command rows, below); the \xA713.12 operator assertion uses the largest encoded CONNECT\nline in the set.\n\nThe agent baseline includes the self-targeted manager command `run-answer`. Its grant is only the\n`self` request form. The manager MUST authorize a baseline managed seat only when an open `ask` or\nescalated checkpoint is named by a pending relay addressed to that exact caller incarnation, and\nMUST refuse every other run or pause. A caller holding the explicit `run` capability may use the\nsame self-targeted form for ordinary run answers. The request never carries the answerer's name.\nThe amend form of `run-answer` (\xA714.5) addresses a settled pause instead, and the manager MUST\nauthorize it for a baseline managed seat only when the accepted answer it supersedes was recorded\nunder that seat's own name.\n\n**Serve grants.** Serving is granted authority, dual to calling. On the **subscribe side**\nan instance's credential binds its registered service name, stable instance id, and\n**registered command set**, one queue-qualified subscribe row per registered command\n(matrix below), never a bare `>` tail spanning commands the instance did not register. The\nper-command enumeration is affordable precisely where the caller-side equivalent is not:\nserve credentials are one per instance, a handful per space, with no capability-count\nscaling pressure. The subscribe side deliberately does NOT bind the epoch; a caller cannot\nname the serving epoch, so no request subject carries it and **ingress cannot be\nepoch-fenced by subject**; the fence for a superseded subscriber is the \xA713.1 takeover\nbarrier (revoke + cluster-verified eviction), not a grant shape. On the **publish side** the\ncredential binds the epoch everywhere it is real: the epoch-pinned reply prefix, the\nepoch-pinned `epe` event plane, its `ept` timer schedule requests, and its `epr`\nrecord-write ingress. Session subjects are\ndeliberately absent from the standing serve grant: both sides of a session hold only\nredemption-minted per-session credentials (\xA713.6); no standing EPS grant exists on either\nside. The credential also carries the record keys the writer table assigns it and, where\nthe endpoint owns a work pool, the pool's consumer + ack grants (\xA713.5; matrix below).\nNothing else. Every \"binds X\" in this paragraph has a matrix row below that actually binds\nX. Serve\ncredentials are re-minted on takeover (new epoch, \xA713.1 barrier); a superseded credential's\nreplies and commits are rejectable by epoch. Core names require operator provisioning\nauthority; reverse-DNS names bind to their registered owner. The registry is discovery; the\nserve grant is the authority: a foreign credential cannot subscribe a class rail, answer as\nan instance, or enter a frozen scatter set.\n\n**Remote manager-service grant.** The server-authored `manager-service` view is an\ninstance-scoped authority family, not a reusable host profile. Its generated grant is the exact\nunion of the one manager instance's serve rows, its one service registration/status mediator,\nits staged contract-publication row, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>`; no wildcard may span an instance, manager actor,\nowner, endpoint, record kind, contract digest, or credential id. The trusted auth path alone owns\ngate/ledger writes and all host signing. The manager service's descendant-provision request is\nmediated by that host path and MUST re-derive the requested agent's owner from the authenticated\ncaller, require it to equal the manager-service owner, and fresh-validate the active grant before\nminting any child material. It is never a raw provisioner, stream, KV, consumer, signer, or\ncross-owner control grant. The registration and renewal operations are typed/idempotent as \xA713.6\nrequires, and their stage records remain inaccessible to every ordinary agent, observer, admin,\nor managed-agent exchange.\n\n**Platform control grant.** The `platform-control` view's generated grant is the remote\nmanager-service grant above with the platform owner token as owner: the union of the one assigned\ninstance's serve rows, its one service registration/status mediator, its staged\ncontract-publication row, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>`, with no wildcard spanning an instance, manager actor,\nowner, account, endpoint, record kind, contract digest, or credential id. Descendant provisioning\nMUST re-derive the requested agent's owner from the authenticated caller and require it to equal\nthe platform owner token. Serve-time admin authorization answers `authorized: true` only for a\ncaller whose owner equals that token; a human `admin` scope never authorizes against it. It is\nnever a raw provisioner, stream, KV, consumer, signer, launch, or cross-owner control grant.\n\n**Platform readiness read.** A platform composition learns whether its assigned control manager\ninstance is serving through the auth context's readiness read. The trusted auth process answers over\nits own self-minted reader connection and hands out neither that connection nor its credential. The\nreader's grant is the `describe` and `status` request rows on `ep.inst.manager.<instanceId>` for the\none assigned instance under the reader's own caller triple, the subject-scoped contract-store Direct\nGet, its own reply rail, and its own `_INBOX_<connId>.>`. It holds no other command, instance, class\nor scatter route, no other store read, no KV write, and no signer. The read observes the current\nassignment on every call, refuses any other instance, and refuses an instance whose gate names\nanother principal. The reader renews as the other self-minted authority connections do: a\nshort-lived user JWT re-minted in process at half-life and presented on reconnect.\n\n**The ownership matrix (normative).** Every profile \xD7 resource \xD7 transition is classified\n**mediated** or **direct**, in an independently reviewed matrix from which grants are\ngenerated (never the reverse). Each row names the writer PROFILE, the exact subject/API\nnamespace (including the queue qualifier where one applies; the grant grammar has a queue\ndimension, \xA713.2), the operation, and the enforcement class; **read, consume, ack, and\ndelete authority are rows in the same table**, never prose that \"follows\" it. Every\ncredential and every audit probe is generated from these rows.\n\n**Consumer-name grammar (normative).** Every consumer a row names has a pinned name grammar\n(dash-form, \xA72; `<e>` is the endpoint-name token, `<uid>` the holder's lifecycleUid or\ninstanceId): `canonD = canon_<e>` (the canonicalizer durable), `poolD = pool_<e>_<pool>`\n(the pool durable, **pre-created by the provisioner** with exact filter\n`cotal.<space>.epw.<e>.<pool>.>`, the \xA78 item-3 pattern: the bare create form is\nbody-filter-selectable and is granted to NO ONE on control-surface streams), `timerD =\ntimerw_<space>` (the timer writer durable), `recwD-k = recw_<space>-<kind>` (one record\nwriter durable PER RECORD KIND, \xA713.9), `effD = eff_<e>` (the endpoint's ONE shared\neffects durable; below), `goalD = goal_<uid>-<e>` (the caller's own goal-result durable).\nEvery composite name is **collision-free by construction**, and\neach derivation states why: `pool_<e>_<pool>` parses uniquely from its LAST `_` because a\npool token contains no `_` (`[a-z0-9-]`) while `<e>` may (a dash separator would be\nambiguous, both tokens admit `-`); `dec_<uid>-<e>` parses from its FIRST `-` because\n`<uid>` is `[a-z0-9]` and contains none, and `goal_<uid>-<e>` likewise; `eve_<uid>-<e>-<gid>-<n>`\ncarries TWO `-`-adjacent soft components (`<e>` and `<gid>`), so `<gid>` is constrained\nSEPARATOR-FREE (`[a-z0-9]`, no `-` or `_`): then `<uid>` (leading, `-`-free), `<n>` (trailing\ndigits) and `<gid>` (separator-free) are each a single token off their edges, leaving `<e>` as\nthe only `-`-bearing component with an unambiguous extent (`eve_<uid>-a-b-c-0` can ONLY be\nendpoint `a-b`/gid `c`, never endpoint `a`/gid `b-c`). `rec_<uid>-<gid>-<n>` has one soft\ncomponent `<gid>` bounded by `-`-free `<uid>` and digit `<n>`. Without the separator-free `<gid>`\nthe two grants above would collide on one durable name. A derivation that cannot state its\ncollision-freedom argument is non-conformant. Reader consumers use **mint-time-enumerated LITERAL names**, and every one\nis **pre-created by the provisioner at capability mint as a PULL durable with its exact\nfilter; the holder receives BIND-ONLY grants** (INFO/MSG.NEXT/ACK, never CREATE or\nDELETE): `decD = dec_<uid>-<e>` (one per journal capability), `goalD = goal_<uid>-<e>`\n(one per action capability),\n`eveD = eve_<uid>-<e>-<gid>-<n>` and `recD = rec_<uid>-<gid>-<n>` (one per granted subtree;\n`<gid>` is the **grant id**, a short stable SEPARATOR-FREE (`[a-z0-9]`) id the provisioner\nassigns per minted capability grant, so two independent capability mints for one lifecycle UID\nnever collide AND the `<e>`/`<gid>` boundary stays unambiguous, and `<n>` is\nthe subtree's zero-based index within THAT grant, sorted lexicographically at mint; the\ndeprovision key is `<uid>-<gid>`, so revoking one capability deletes exactly its own reader\ndurables and cannot reach a sibling capability's). Two reasons, both\nload-bearing. A NATS wildcard replaces a\nWHOLE dot-separated token and never matches inside one, so an embedded `*` in a name token\n(e.g. `dec_<uid>-*`) is a literal character, not a glob; every name token in a grant is\nfully literal.\n\n**Mediated reads (normative).** No untrusted capability holder is granted **any** raw\nJetStream read of a control-surface stream, not a consumer create, not a bind-only pull,\nnot a `DIRECT.GET`. Every JetStream read is request/reply where the server delivers stored\nbytes to a **caller-chosen destination the broker does not confine to the caller's\n`pub.allow`**: a push consumer's `deliver_subject`, a pull `MSG.NEXT` request's reply\nsubject, and a `DIRECT.GET` request's reply subject are all set in the request body, and the\nserver's internal client publishes there regardless of the requester's publish permissions.\nA holder with only `MSG.NEXT` or\n`DIRECT.GET` on its own filtered reader can therefore route stored bytes onto a victim's DM,\nreply, or record subject, a confused deputy no filter tail, literal name, or pull-vs-push\nchoice prevents, because the destination is the vulnerable field, not the filter. Untrusted\ncallers instead read exactly as the \xA78 durable backstop already does, through a **trusted\nread path**, never a self-bound consumer: a caller receives its decisions, goal results,\nevent catch-up, and record reads over its OWN confined rails, a live core subscription to a\nsubject inside its `sub.allow` (bytes land only on the caller's own subscription), or a\nmediator that owns the reader consumer, re-authorizes each read against the caller's current\ngrants, and returns bytes over the caller's own attribution-pinned reply rail\n(`ep.reply.\u2026<caller triple>.<nonce>`: the mediator holds the publish grant, the caller the\nread grant, and the nonce confines addressing, \xA713.2). The mediator IS a trusted\nsingle-purpose principal (the delivery/read daemon, \xA78/Appendix B) that delivers only to the\nre-authorized caller and never proxies to an arbitrary subject; raw\nconsumer/`DIRECT.GET`/`STREAM.MSG.GET`\nauthority stays with trusted single-purpose infra principals (canonicalizer, commit\nprincipal, record writer, timer writer, the read mediator, the auth path) that deliver to\nthemselves. A registered endpoint MAY also mediate its own callers' goal-result reads through\nits separate trusted commit/read connection. Each request MUST be authorized by the requesting\nconnection's broker-enforced command grant on its authenticated caller triple. User-auth revocation\nhas the same bearer-lifetime bound as other live endpoint commands; renewal requires a fresh\nexchange and connect that re-authorize the caller. This read does not claim a per-request ledger\ncheck. The endpoint and full caller triple MUST come from the broker-authenticated request\nsubject; caller input supplies only the goal id. The response MUST\nuse the derived attribution-pinned caller reply rail, never a caller-supplied destination. This\nhosting choice grants no raw read to the endpoint's serve credential or to its callers. The\nexisting trusted reader's body-selected, space-wide leader-read residual MUST remain documented.\nThis contract fixes the boundary; untrusted callers never hold raw reads; reads are mediated onto\nconfined caller rails, and leaves the read-command wire shape (batching, cursors, flow control) to\nthe reference implementation.\n**Subject convention:**\napplication subjects in rows are written relative and are prefixed `cotal.<space>.` on the\nwire; **JetStream API tails (extended-create filter tails and `DIRECT.GET` subject\ntails) are always spelled in FULL** (`cotal.<space>.\u2026`/`$KV.\u2026`/`$O.\u2026`), because the API\nsubject embeds the stored subject verbatim and a relative tail matches nothing (the\nstreams capture `cotal.<space>.ep*.>`, \xA713.12).\nThe grep tests the matrix MUST pass: the only `CONSUMER.CREATE` grants below belong to\ntrusted provisioning/infra profiles and each carries a full literal filter tail; every\nconsumer-name token in a grant is a LITERAL (no embedded `*`); every filter or Direct-Get\ntail is fully qualified; **no UNTRUSTED profile (agent/observer/admin) holds any\n`CONSUMER.CREATE`/`MSG.NEXT`/`DIRECT.GET`/`STREAM.MSG.GET` on a control-surface resource** (an\naudit MUST run this over Appendix B too, not only this matrix; the profile tables are\ngenerated from these rows, so a generated grant that contradicts the matrix fails the build);\nand the ONLY `STREAM.MSG.GET` (body-selected) grants that exist at all are the leader-served\nreads of named TRUSTED single-purpose profiles, each granted to no other profile - every one\na FENCING read (read service, below) except where its row names it a CAS-PINNING read, a\nleader-served currency read whose FENCE is the pinned CAS write it feeds (\xA713.1: a read is\nnever a fence): the auth path on `KV_cotal_auth_<space>`, the lifecycle mapping-reader and\nthe provisioner-registration principal on the `cotal_records_<space>` heads, the endpoint's\ncanonicalizer on `EPF_<space>`/`EPW_<space>`, the endpoint's commit principal on its own\n`EPF_<space>` fact families AND on `KV_cotal_records_<space>` (its goal/checkpoint FENCING\nspec-and-currency reads: the terminal-commit's spec read and the epoch/deadline reads the\nread-service clause names), each record kind's spec/status writer principal on\n`KV_cotal_records_<space>` (its fresh lifecycle-mapping `processEpoch` currency read, the\nwriter-table stale-writer fence; per \xA713.1 a mapping yields a current epoch ONLY at\n`state: \"active\"`, and `retiring`/`retired` alike refuse the write), and the space's timer writer on\n`KV_cotal_records_<space>` (its fresh generation/deadline check before arming, a FENCING\nread) and on `EPT_<space>` (`$JS.API.STREAM.MSG.GET.EPT_<space>`, the armed-subject's own\nlast-by-subject sequence read: CAS-PINNING, the leader-served input to the arm's\n`Nats-Expected-Last-Subject-Sequence` publish, whose broker CAS - not the read - is the\nfence, the same \xA713.1 complementarity class as the FIRE handler's status CAS). The timer\nFIRE handler holds no records `STREAM.MSG.GET`: its settlement is a revision-pinned status\nCAS, so a stale read loses the CAS loudly (\xA713.1 complementarity), never mis-fires (the\nmatrix rows below). The body-selected form is not\nsubject-confinable by the broker, so each of these grants trades broker confinement for\nprofile trust; the trade is acceptable exactly because every holder IS a trusted\nsingle-purpose principal for whom read-your-writes is a correctness requirement, not a\nhazard (on the `allow_direct=false` buckets a leader-consistent get is precisely a\n`STREAM.MSG.GET`). Every OTHER subject-scoped read is NON-fencing and uses the\nlast-by-subject `DIRECT.GET.<stream>.<subject>` form, which the broker confines by subject\ntokens. (The pre-v0.4 messaging-surface CHKV/DLVKV reads in Appendix B are the v0.3 binding,\noutside this matrix; their confused-deputy exposure is the \xA79 in-scope-for-v0.4 remediation.)\n\n**Read service (fencing reads are leader-served).** A read is FENCING when its result, a\nvalue, a revision, OR an authoritative ABSENCE, gates a subsequent CAS or authorizes an\neffect; fencing is defined by USE, never by subject family. A CAS loser reading the winner,\na terminal-commit's spec read, and the work-pool re-enqueue predicate (accepted, with the\nauthoritative absence of BOTH a committed terminal and a live `EPW` entry, \xA713.6) are all\nfencing: a stale follower read that misses a committed terminal while the `EPW` entry is\nlegitimately absent re-arms settled work. A fencing read MUST be leader-served, meaning one\nof `STREAM.MSG.GET`, a get against a bucket with `allow_direct=false`, or delivery\nserialized by the authoritative primary stream/consumer (an authoritative `MSG.NEXT`, e.g.\nthe accepted-fact effects row and the auth path's snapshot enumeration below), and it MUST\nbe served against the AUTHORITATIVE stream or bucket for its key, never a mirror, a sourced\nstream, or a cross-space replica (\"leader-served\" means that authoritative primary; a\nmirror's own leader can lag its source). `allow_direct=true` and Direct Get exist for\nNON-fencing, subject-confined reads only; a client MUST NOT let a fencing read silently\nride Direct Get because the bucket allows it. This does not weaken \xA713.1's rule that a read\nis never a fence: the fence itself stays a CAS or create-only write; leader service is what\nkeeps the read's result from silently falsifying the CAS or effect it feeds.\n\n| Transition | Writer profile | Exact namespace (per space/endpoint) | Class |\n| --- | --- | --- | --- |\n| Request publish | capability holder (agent, per capability) | per \xA713.2 form: `ep.{one,all}.<endpoint>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>.*` and `ep.inst.<endpoint>.<instanceId>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>.*`, mode/target tokens literal per the minted capability (`handle`: the full redemption-pinned triple) | direct, untrusted input, broker-confined |\n| Reply subscribe (caller) | capability holder | `ep.reply.*.*.*.<cO>.<cA>.<cUid>.*` (exact arity) | direct read; own rail only |\n| Serve subscribe | the endpoint's serve credential | per registered command: `\"ep.one.<endpoint>.<command>.> <endpoint>\"` (queue-qualified ONLY), `ep.all.<endpoint>.<command>.>` plain, `ep.inst.<endpoint>.<instanceId>.<command>.>` exact (never a cross-command `>` | direct) name/instance/command-pinned; epoch deliberately absent (\xA713.1 barrier is the fence) |\n| Reply publish | the endpoint's serve credential | `ep.reply.<endpoint>.<instanceId>.<epoch>.*.*.*.*` | direct; attribution-pinned; addressing by nonce |\n| Versioned-rail request, reply, serve (\xA713.15) | as the four rows above | the same rows with `ep.v1` for `ep` and one more pinned token: the caller's `<generation>` literal in its request-publish and reply-subscribe rows (`ep.v1.reply.*.*.*.<cO>.<cA>.<cUid>.<generation>.*`), a spanned token in the serve credential's reply-publish row (`ep.v1.reply.<endpoint>.<instanceId>.<epoch>.*.*.*.*.*`) and its three serve-subscribe shapes per command | direct; broker-confined on the generation exactly as on the caller triple |\n| Issuance (\xA713.15) | the `issuer` principal (one-shot, minted per issuance or per lifecycle terminal by the party holding the space signer) | `$KV.cotal_issued_<space>.>` and `$KV.cotal_accepted_<space>.>` publish, `STREAM.INFO`/`STREAM.MSG.GET` on `KV_cotal_issued_<space>`, its own ordered consumers on that store, and ONE leader-served `STREAM.MSG.GET` on `KV_cotal_auth_<space>` for source liveness; NO auth-store write, no rail row | mediated; create-only CAS on evidence, revision-CAS on the attempt row |\n| Run admission (\xA714.8) | the `run-admitter` principal (one-shot, 60 s, minted per run by the hosting endpoint or the local operator) | exactly `$KV.cotal_admission_<space>.admission.v1.<endpoint>.<runId>` and `\u2026.revoked.v1.<endpoint>.<runId>` publish plus `STREAM.MSG.GET` on that store; nothing else | mediated; create-only |\n| Run admission read (\xA714.8) | the `run-mediator` and `run-operator` principals | `STREAM.MSG.GET` on `KV_cotal_admission_<space>` (leader-served; body-selected, stream-wide, the same residual as every records reader); the `run-driver` holds NO row on this store | mediated read; fail-closed |\n| Journal submission append | capability holder | `epj.<endpoint>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>` | direct, explicitly untrusted input |\n| Canonicalizer consume | the endpoint's canonicalizer principal (singleton, \xA713.4) | its durable on `EPJ_<space>`: `$JS.API.CONSUMER.CREATE.EPJ_<space>.<canonD>.cotal.<space>.epj.<endpoint>.>` (full-tail single filter), `$JS.API.CONSUMER.INFO.EPJ_<space>.<canonD>`, `$JS.API.CONSUMER.MSG.NEXT.EPJ_<space>.<canonD>`, plus `$JS.ACK.EPJ_<space>.<canonD>.>` (ack/term after durable decision only, and, for pool-admitted acceptances, after the enqueue, \xA713.4) | mediated |\n| Canonical decisions + quarantine + goal-bind | the endpoint's canonicalizer principal | publish `epf.<endpoint>.dec.>`, `epf.<endpoint>.quar.>`, and `epf.<endpoint>.goal.*.*.*.*.bind` (the per-goal first-wins bind, \xA713.4, create-only CAS per subject; the `.bind` leaf is disjoint from the commit principal's `goal\u2026.result`/status writes, so no writer overlap) | mediated |\n| Canonicalizer CAS-winner + terminal read | the endpoint's canonicalizer principal | leader-served `$JS.API.STREAM.MSG.GET.EPF_<space>` (body-selected `last_by_subj`; these reads are FENCING, read service above, so the follower-served `$JS.API.DIRECT.GET.EPF_<space>.\u2026` form is NOT granted; the body-selected form is the broker-confinement-for-profile-trust trade above) over exactly its families: `epf.<endpoint>.dec.>` + `epf.<endpoint>.quar.>` (observes the winning fact on redelivery, \xA713.4) + `epf.<endpoint>.wrk.>` (READ-ONLY: the reconciliation predicate's terminal probe, \xA713.6; `wrk` writes stay with the commit principal, row below) + `epf.<endpoint>.goal.*.*.*.*.bind` (the goal-bind CAS winner: on a lost `.bind` create the canonicalizer reads the existing bind to decide same-fingerprint retry vs. `conflict`, \xA713.4) | mediated |\n| Caller durable reads (decisions, goal results, receipts, event catch-up, record reads/watches) | the **read mediator** owns the reader consumers; a registered endpoint MAY mediate its own callers' goal results through its separate trusted commit/read connection; the **caller** holds only its own reply rail | **Mediated (normative above).** The caller holds NO consumer/`DIRECT.GET` grant on EPF/EPE/EPC/records. It issues a read command and receives its own caller-scoped facts (`dec`/`goal\u2026result`/`receipt` under its triple, \xA713.2), event catch-up, and record snapshots over its attribution-pinned reply rail `ep.reply.\u2026<cO>.<cA>.<cUid>.<nonce>`; the read mediator re-authorizes each read against the caller's current grants before delivering; registered-endpoint goal reads use the connection-grant authorization and bearer-lifetime bounds specified above. Live progress is the caller's own core subscription to granted `epe` subtrees within `sub.allow` (bytes land only on its own sub). Reader consumers (`decD`/`goalD`/`eveD`/`recD`) are owned and bound by the mediator, never the caller | mediated read; confined to the caller's own rails |\n| Accepted-fact consume (effects) | every instance's serve credential, on the endpoint's ONE shared durable | **bind-only** on the provisioner-pre-created pull durable `effD = eff_<e>` (exact filter `cotal.<space>.epf.<endpoint>.dec.>`, `AckExplicit`): `$JS.API.CONSUMER.INFO.EPF_<space>.<effD>`, `$JS.API.CONSUMER.MSG.NEXT.EPF_<space>.<effD>`, `$JS.ACK.EPF_<space>.<effD>.>`; instances **pull-compete on the shared durable** so each accepted decision is delivered to exactly one live instance (at-least-once): a per-instance consumer over the class-wide decision subtree would be broadcast, and every instance would duplicate the external effect. Effects consume canonical facts, never raw submissions (\xA713.4); a rejected/quarantined decision is ack-skipped, and so is any acceptance whose `route` is a pool (\xA713.4, the pool's worker path executes it; effects MUST NOT). **Ack barrier:** an effecting instance MUST ack a `dec` message ONLY after its effect is durably recorded, for an action command the terminal `goal\u2026.result` fact; for a **non-action `route:\"effects\"` journal command** a generic per-request **effect fact** `epf.<endpoint>.eff.<cO>.<cA>.<cUid>.<id>` (create-only CAS, written by the effecting instance's commit path before ack; every `route:\"effects\"` acceptance has exactly this durable effect-complete marker), never before; an ack-before-effect would let a crash drop journal work the at-least-once contract promised. A crash before the ack redelivers the decision to another competing instance, which observes the existing terminal fact (idempotent) or effects it | direct read, endpoint-scoped, work-shared |\n| Result/receipt/terminal/resume facts | the endpoint's commit principal | enumerated fact families, no subtraction and **never `dec.>`/`quar.>`** (canonicalizer-only): publish `epf.<endpoint>.goal.*.*.*.*.result` (the goal terminal result; the `.bind` leaf under `goal.>` is the canonicalizer's, row above), `epf.<endpoint>.eff.>` (per-request effect-complete fact for non-action `route:\"effects\"` commands, create-only CAS, \xA713.9 ack barrier), `epf.<endpoint>.receipt.>` (caller-scoped subjects, \xA713.2), `epf.<endpoint>.wrk.>` (per-item terminal, create-only CAS), `epf.<endpoint>.cp.>` (one-use resume CAS); read-back is FENCING (read service above: it gates create-only CAS emission and idempotent re-commit decisions), leader-served `$JS.API.STREAM.MSG.GET.EPF_<space>` (body-selected `last_by_subj` over exactly these five families; the follower-served per-family `DIRECT.GET` form is NOT granted) | mediated |\n| Live event progress (caller) | capability holder (per read capability) | a caller-owned **core subscription** to the granted `epe` subtrees (fully-qualified `cotal.<space>.epe.\u2026` in `sub.allow`, Appendix B), incl. per-goal `epe.<endpoint>.*.*.goal.<cO>.<cA>.<cUid>.>`; safe because a core sub delivers only to the caller's own subscription, never a caller-chosen subject; durable catch-up/replay is the mediated read above, not a self-bound consumer | direct read; own subscription only |\n| Claim / action / checkpoint commits | the owning endpoint's commit path | its own record keys (`goal`/`cp`/`lease`/`goaleff`/`epname`/`epmig` grammars, \xA713.7, per the writer table; the three coordination kinds are enumerated HERE because a shared registry profile does not confer a grant; a kind absent from this enumeration is default-denied however it is registered, and that default-deny binds every principal in this table, including the composed profile in the row below) + the enumerated commit fact families of the Result row above, never `dec.>`/`quar.>`; its goal/checkpoint FENCING reads (the terminal-commit's spec read, epoch/deadline currency) are leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` (read service above; the records bucket's Direct Get is NON-fencing only) | mediated (validates fencing, lease clock, lifecycle, epoch) |\n| Goal-writer commits (journal-class actions) | the **goal-writer** principal: the commit principal of the row above, composed with three additions and nothing else | the composed profile is exactly (i) everything the commit row grants, inherited rather than restated, (ii) the per-goal first-wins bind leaf `epf.<endpoint>.goal.*.*.*.*.bind`, (iii) the reconcile index subtree `goalidx.<endpoint>.>` in the records bucket, key-pinned to this endpoint, and (iv) a currency read of its OWN issuance gate `epgate.<endpoint>.<instanceId>` before the first terminal-fact CAS, so a superseded writer declines to commit. That read carries the NAMED RESIDUAL this section requires of every bucket-blind read: the auth store is not Direct-Get enabled, so the read is a leader-served body-selected `STREAM.MSG.GET` that cannot be key-pinned to the single gate key, and the profile can therefore read any row of that bucket's gate and ledger METADATA, never bearer bytes. It is the same residual class the one-shot serve-executor profile carries, here on a standing connection, and it is a fast-fail belt rather than the fence; the durable fence is barrier revocation. `goalidx` is enumerated HERE and NOT on the commit row, because the index is written create-only BEFORE the goal binds, so the principal that writes it is the one that also binds; granting it on the bare commit row would widen every commit principal to a key only this profile needs. This profile holds NO records consumer create: the sweep that enumerates the index runs over the provisioner (row below), never over this standing connection, which is why an index write grant is not an index enumeration grant | mediated (as the commit row, plus the bind's create-only CAS per subject) |\n| Contract-artifact publication | the contract publisher principal | publish `epc.<digest-hex>` (`epc.*`), create-only per subject (`Nats-Expected-Last-Subject-Sequence: 0`; a digest subject is written at most once); read-back via the reader row below | mediated, immutable once published |\n| Contract-artifact read | trusted infra directly (`DIRECT.GET.EPC_<space>.cotal.<space>.epc.>`); untrusted callers via the read mediator | contract artifacts are content-addressed and public (verify-on-read is the tamper boundary, \xA713.7), so exposure is not the risk; the confused-deputy INJECTION is, so an untrusted caller's artifact fetch is mediated onto its own reply rail exactly like any other read; trusted infra fetches directly | mediated for callers / direct for infra |\n| Record write ingress (`epr`) | the owning instance | publish `epr.<endpoint>.<instanceId>.<epoch>.<kind>.<qualifier...>`; the instance's ONLY path to `svc`/`goal`/`cp` status writes; the epoch token is pinned by the serve credential, so the record writer reads the writing epoch from the broker-authenticated subject, never from payload | direct; epoch-pinned ingress to the mediated writer |\n| Record writer consume + `spec`/`status` writes | the kind's separately scoped spec/status writer principal (writer table); **one principal and one consumer PER KIND**, never a single writer draining every kind | consume: `$JS.API.CONSUMER.CREATE.EPR_<space>.<recwD-k>.cotal.<space>.epr.*.*.*.<kind>.>` (full-tail single filter on the `<kind>` token of \xA713.2's `epr` grammar; `recwD-k = recw_<space>-<kind>`) + `$JS.API.CONSUMER.INFO.EPR_<space>.<recwD-k>` + `$JS.API.CONSUMER.MSG.NEXT.EPR_<space>.<recwD-k>` + `$JS.ACK.EPR_<space>.<recwD-k>.>`; write: `$KV.cotal_records_<space>.<that kind's \xA713.7 key grammar>.{spec,status}`; its writer-table stale-writer fence (the FRESH lifecycle-mapping `processEpoch` currency read; current ONLY at `state: \"active\"`, \xA713.1, so a `retiring` or `retired` mapping refuses the write) is leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` (a FENCING read, read service above); the kind token in the ingress subject is what keeps the writer separation the writer table declares | mediated per kind below, no row left open |\n| Reader/pool/effects consumer provisioning (one-shot, at capability mint / endpoint setup) | the provisioner | exact full-tail extended creates for every pre-created durable this matrix names: `$JS.API.CONSUMER.CREATE.EPW_<space>.<poolD>.cotal.<space>.epw.<e>.<pool>.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<effD>.cotal.<space>.epf.<e>.dec.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<decD>.cotal.<space>.epf.<e>.dec.<cO>.<cA>.<cUid>.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<goalD>.cotal.<space>.epf.<e>.goal.<cO>.<cA>.<cUid>.>` (per action capability), `$JS.API.CONSUMER.CREATE.EPE_<space>.<eveD-n>.<granted full-tail subtree>`, `$JS.API.CONSUMER.CREATE.KV_cotal_records_<space>.<recD-n>.$KV.cotal_records_<space>.<granted subtree>` (the reader-config seam is an ALLOWLIST: the `<granted subtree>` kind token MUST be a registered caller-readable record kind, so it REFUSES every authority-control kind (`oblig` above all, plus `govern`/`policy`/`uid`/`frontier`) and every unregistered kind, and for a dual-token kind whose atomic head is authority (`lifecycle`, head `lifecycle.<owner>.<actor>`) it admits only a filter strictly deeper than the head, never one that can match the head key itself; so no reader durable is ever pre-created over the `oblig.` subtree the sealed records scanner owns nor over an authority head, nats-server#8274), every create PULL, every filter a full literal tail; plus matching `CONSUMER.DELETE` for deprovisioning (lifecycle-keyed names, \xA713.1) | mediated, trusted provisioning only |\n| Events | the owning instance | `epe.<endpoint>.<instanceId>.<epoch>.>` | direct; subject-confined, epoch-pinned |\n| Timer schedule request | the owning instance | publish `ept.<endpoint>.<instanceId>.<epoch>.*.schedule` (never `.armed`/`.fire`); a request carrying any scheduling header is rejected by the timer writer (\xA713.2) | direct; epoch-pinned; captured by the schedules-DISABLED request stream |\n| Timer request consume + arm | the space's timer writer principal (singleton infra, like the delivery daemon) | consume: `$JS.API.CONSUMER.CREATE.EPT_REQ_<space>.<timerD>.cotal.<space>.ept.*.*.*.*.schedule` (full-tail single filter) + `$JS.API.CONSUMER.INFO.EPT_REQ_<space>.<timerD>` + `$JS.API.CONSUMER.MSG.NEXT.EPT_REQ_<space>.<timerD>` + `$JS.ACK.EPT_REQ_<space>.<timerD>.>`; arm: publish `ept.*.*.*.*.armed`, deriving `Nats-Schedule-Target` = the sibling `.fire` from the authenticated request subject tokens ONLY, stripping/rejecting every client scheduling header, and **fresh-checking the authoritative timer generation/deadline before arming** (a FENCING read: leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` on the checkpoint record, read service above); the arm also reads the armed-subject's own last sequence via `$JS.API.STREAM.MSG.GET.EPT_<space>` and publishes with `Nats-Expected-Last-Subject-Sequence` pinned to it - that read is CAS-PINNING, not fencing: the broker CAS is the fence and a delayed writer's stale read loses it loudly (\xA713.1 complementarity, the FIRE handler's class); a redelivered or delayed stale-generation request is discarded, never armed, so it cannot overwrite the current schedule and silently lose the live deadline (\xA713.2, \xA713.6, \xA713.12) | mediated |\n| Timer fire consume | the owning instance | its own `ept.<endpoint>.<instanceId>.<epoch>.*.fire` (fired messages validated against its authoritative schedule state AND the broker-authored scheduler-origin header = its exact sibling `.armed`, \xA713.12); no client credential holds `.armed` or `.fire` publish | direct read |\n| Session `.in` publish | the session's caller (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.in` exact | direct |\n| Session `.in` subscribe | the serving instance (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.in` exact | direct read |\n| Session `.out` publish | the serving instance (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.out` exact | direct |\n| Session `.out` subscribe | the session's caller (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.out` exact | direct read |\n| Session ledger (one-use redemption, credential ids, revocation state, authenticated close) | the trusted auth path (\xA79/\xA710) | `$KV.cotal_auth_<space>.session.<sessionId>`, create-only CAS per `sessionId`, monotonic state (\xA713.6) | mediated |\n| Credential ledger (issuance gate, descendant enumeration, lineage index, revocation) | the trusted auth path (\xA79/\xA710) | writes: `$KV.cotal_auth_<space>.cred.<lifecycleUid>.<credentialId>` + `\u2026.gate.<lifecycleUid>` (the issuance gate, revision-pinned CAS is the mint fence, \xA713.1) + `\u2026.epgate.<endpoint>.<instanceId>` + `\u2026.epcred.<endpoint>.<instanceId>.<credentialId>` + the exact `\u2026.eprepair.<endpoint>.<instanceId>` interrupted-repair cursor (the disjoint endpoint families, \xA713.1: same protocol, explicit prefixes, never arity; the repair executor is pinned to one exact cursor key) + `\u2026.stage.>` (implementation staging/tombstone fences; NEVER under `cred.`/`epcred.`, \xA713.1) + `\u2026.srcgate.<issuerKeyId>.<id>` (per-handle source gate, \xA713.1) + `\u2026.bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>` (the per-ancestor lineage index) + `\u2026.session.<sessionId>` (create-CAS `issuing`, finalize-CAS `active`, \xA713.6) + `\u2026.plane` (the ONE plane-ownership claim row, \xA713.13: create/revision-CAS by the barrier profile only, exact arity, never `plane.>`); reads: **leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_auth_<space>`** (with `allow_direct=false` a KV get is exactly this body-selected `last_by_subj` call against the stream LEADER; read-your-writes, not a follower-served `DIRECT.GET`; the body-selection is safe here because this profile IS the trusted auth path, and it is granted to no other profile) for gate/session/row state, which is why the mint and session fences are revision-pinned CAS *writes* rather than reads (a read is never a fence, \xA713.1); and **fence-free prefix enumeration through the SEALED auth-ledger scanner, never a runtime consumer create**: no standing or runtime-reachable auth credential (the takeover/retirement/handle-revocation barrier, the session sweep, any replayable executor) holds `$JS.API.CONSUMER.CREATE` on `cotal_auth_<space>`, because a consumer-create request BODY is not subject-ACL confinable: an extended `CONSUMER.CREATE.<stream>.<name>.<filter>` grant still admits a body with `durable_name` (equal to the subject name token) and a push `deliver_subject`, a DURABLE exporter of every current and future row that SURVIVES the credential's connection close and revocation; a subject ACL cannot constrain that body, so the only safe runtime grant is none. The dynamic-enumeration `CONSUMER.CREATE` lives in exactly ONE profile, a SEALED scanner the trusted auth process opens for itself and NEVER hands out: its credential, connection, and identity seed reach no caller, child, log, or persistence (a process-memory compromise reaches it, the SAME residual class as the account signing seed the process already holds; never broker confinement, never a network-reachable JWT). The scanner is pinned to ONE literal consumer name under a FORCED config: pull (no `deliver_subject`), ephemeral (no `durable_name`), `AckPolicy.None`, `DeliverPolicy.LastPerSubject`, memory storage, bounded inactivity; re-read and bind-verified before use and unconditionally deleted after, with every scan over the stream serialized on that one name, and the injected scanner bonded to its exact space so a hand-assembled or foreign-space scanner never enumerates. The scan is FENCE-FREE by construction: under the history=1 store a same-subject `active\u2192revoked` overwrite EVICTS the pre-scan revision, so a sequence/`STREAM.INFO` cutoff would DROP that subject and leave its holder un-revoked; a LastPerSubject read carries no upper cutoff and, draining to a freshly re-observed zero pending (never a stale local count), returns each subject's CURRENT last, so a concurrent overwrite is SEEN, never dropped. It enumerates exactly `cred.<lifecycleUid>.>`, `bysrc.<issuerKeyId>.<id>.>`, `stage.>` (operation-intent discovery), or `session.>`. The barrier's family enumeration and the expiry sweep are executable reads, not prose. No profile OTHER than the sealed scanner and this trusted write path holds ANY grant on `cotal_auth_<space>` | mediated |\n| Remote manager-service registration and renewal (\xA713.1/\xA713.6) | the trusted auth path is the sole gate/ledger writer and host JWT issuer; a user manager presents only the server-authored closed view | exactly one staged `{ owner, managerActor, lifecycleUid, instanceId }` family: `svc.manager.<instanceId>`, the stage-pinned contract artifacts, `epgate.manager.<instanceId>`, and `epcred.manager.<instanceId>.<credentialId>`. `prepare` freezes/stages; `activate` creates the matching service record and releases host-signed material only after ledger + gate finalization; `renew` is bounded, rechecks the live ledger scope, and can replace material only inside that family. Descendant provisioning is a mediated same-owner request revalidated by the host. No row grants signer material, generic stream/KV/consumer authority, another instance, or a public/managed-agent exchange path | mediated, closed family; revocation/renewal failure denies new authority and unsafe restarts while retaining live agents only within their independently valid lifetimes |\n| Auth-ledger enumeration (the SEALED scanner profile, the credential-ledger row's enumeration seam) | the trusted auth process's DEDICATED self-minted scanner principal; opened for the process itself, NEVER handed out (full rationale in the credential-ledger row above) | exactly `$JS.API.INFO` + `$JS.API.STREAM.INFO.KV_cotal_auth_<space>` + `$JS.API.CONSUMER.CREATE.KV_cotal_auth_<space>.cotal-ledger-scan.$KV.cotal_auth_<space>.>` + `$JS.API.CONSUMER.INFO.KV_cotal_auth_<space>.cotal-ledger-scan` + `$JS.API.CONSUMER.MSG.NEXT.KV_cotal_auth_<space>.cotal-ledger-scan` + `$JS.API.CONSUMER.DELETE.KV_cotal_auth_<space>.cotal-ledger-scan` + its connection-scoped `_INBOX_<connId>.>` subscribe, and NOTHING else (no records-stream grant, no KV write, no `DIRECT.GET`, no `$JS.ACK`: an `AckPolicy.None` scan acks nothing); `cotal-ledger-scan` is the ONE pinned literal consumer name every auth-stream scan serializes on, and this profile plus the records scanner below are the ONLY DYNAMIC-ENUMERATION `CONSUMER.CREATE` holders on the two authority streams (the provisioning row's pre-created full-tail reader durables, CREATE+DELETE by the provisioner and INFO/MSG.NEXT/ACK bind by the read mediator, are the one other records-stream consumer authority, and the reader-config seam REFUSES an authority-control record kind so no reader durable can target the `oblig.` subtree the records scanner owns), re-audited mechanically per this section's closing clause | mediated |\n| Obligation enumeration (the SEALED records scanner profile, the acceptance-obligation row's enumeration seam, ONE instance per space) | the trusted process's DEDICATED self-minted records-scanner principal; opened for the process itself, NEVER handed out (full rationale in the acceptance-obligation row below; every scan over the literal name serializes process-wide per space, so a second instance can never interleave with a live scan and hand back a partial result, and the scanner handle is immutable once branded) | exactly `$JS.API.INFO` + `$JS.API.STREAM.INFO.KV_cotal_records_<space>` + `$JS.API.CONSUMER.CREATE.KV_cotal_records_<space>.cotal-records-scan.$KV.cotal_records_<space>.oblig.>` (the CREATE filter is confined to the `oblig.` subtree) + `$JS.API.CONSUMER.INFO.KV_cotal_records_<space>.cotal-records-scan` + `$JS.API.CONSUMER.MSG.NEXT.KV_cotal_records_<space>.cotal-records-scan` + `$JS.API.CONSUMER.DELETE.KV_cotal_records_<space>.cotal-records-scan` + its connection-scoped `_INBOX_<connId>.>` subscribe, and NOTHING else; `cotal-records-scan` is the ONE pinned literal consumer name, disjoint from the auth scanner's (one scanner instance, lock, and literal name PER STREAM) | mediated |\n| Work-pool enqueue | the endpoint's canonicalizer (from accepted decisions only) | `epw.<endpoint>.>` publish, create-per-subject (`Nats-Expected-Last-Subject-Sequence: 0`; the acceptance identity is the subject, \xA713.2) | mediated |\n| Work-pool reconciliation probe | the endpoint's canonicalizer | leader-served `$JS.API.STREAM.MSG.GET.EPW_<space>` (body-selected `last_by_subj` on the exact item subject; the probe is FENCING, read service above: a follower-served `DIRECT.GET` that misses the live entry re-arms settled work, so that form is NOT granted) + the CAS-winner read row above (`dec` + `wrk` last-by-subject), together they decide the \xA713.6 predicate: accepted, **`now < workExpiry`** (an expired item is never re-enqueued; it is terminally settled `expired` with its `wrk` fact and acked without effect), no terminal, no live entry \u21D2 re-enqueue for the item's REMAINING TTL; a worker likewise MUST check `now < workExpiry` before lease/effect and refuse expired work | mediated |\n| Virtual-endpoint activation watch | the endpoint's activator principal (holder of its activation capability, \xA713.6) | exactly `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>` (the per-pool occupancy snapshot; request/reply, so watching is bounded polling) PLUS its own connection-scoped reply inbox `_INBOX_<connId>.>` (never the account-wide default); the instance START is a mediated, target-bound seam resolved by the supervisor's own authority, never a broker grant; NOTHING else: no `CONSUMER.MSG.NEXT`/`$JS.ACK` (watching is never draining), no `STREAM.MSG.GET.EPW_<space>` (no reconciliation authority), no consumer create/update/delete, no `epw.>` publish | mediated |\n| Work-pool consume + ack | the pool's owning endpoint ONLY (workers hold NO pool grant, \xA713.5) | **bind-only** on the provisioner-pre-created exact-filter `poolD` (grammar above): `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>`, `$JS.API.CONSUMER.MSG.NEXT.EPW_<space>.<poolD>`, `$JS.ACK.EPW_<space>.<poolD>.>` (ack only after committed terminal state); NO consumer create, NO stream-wide read | mediated |\n| Lease issue / fencing advance | the pool's owning endpoint (`lease` command) | its `lease` record keys (\xA713.7 grammar), via the record-writer seam | mediated |\n| Lifecycle mapping / teardown | minting manager's commit path; lifecycle-pinned deprovisioner | the **unsplit** alias CAS head `$KV.cotal_records_<space>.lifecycle.<owner>.<actor>` (one atomic key, NOT `.spec`/`.status`-split; the authoritative current mapping and the only `mappingRevision` source, activation/retirement serialize here by CAS, \xA713.7; NEVER-DELETED, three states `active | retiring | retired`, transitions only inside the \xA713.1 operations) + the create-only space-global UID reservation `$KV.cotal_records_<space>.uid.<lifecycleUid>` (\xA713.1: won BEFORE any gate or head write; NEVER-DELETED); leader-consistent current-mapping read `$JS.API.DIRECT.GET` is NOT used for authority reads of this key (the records bucket may follower-serve; a fresh mapping read is a leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` last-by-subject get on the head key; leader-served for read-your-writes, granted to the trusted mapping-reader/mediator profile, not a follower-served `DIRECT.GET`; that reader profile ALSO holds exactly `$JS.API.STREAM.INFO.KV_cotal_records_<space>` so it can shape-prove at bind time that the stream it leader-reads is the primary, un-mirrored, non-evicting records store (\xA713.12); a reader that cannot prove its store's shape MUST refuse to serve authority reads); optional append-only per-UID audit `$KV.cotal_records_<space>.lifecycle.<owner>.<actor>.<lifecycleUid>`; teardown: exact lifecycle-keyed names only | mediated / broker-pinned delete |\n| Acceptance obligation (reservation/drain, \xA713.8) | the admission mediator (per endpoint; the canonicalizer holds NO raw `oblig.` grant) | create-only winner + monotonic revision-pinned CAS on `$KV.cotal_records_<space>.oblig.<targetUid>.<endpoint>.<cO>.<cA>.<cUid>.<id>` (\xA713.7; the key derives from the broker-authenticated request subject plus the create-fence currency reads of \xA713.8, never from a body field; proof issuance only after the post-create recheck); its winner/settle reads are FENCING, leader-served `$JS.API.STREAM.MSG.GET` on the obligation key and on the EPF decision subject; its currency reads are FENCING, leader-served `$JS.API.STREAM.MSG.GET` on the target's `lifecycle` head AND on the endpoint's `govern` head (\xA713.6: the govern head read is what surfaces both a staged `pendingPolicyKey` (which pauses policy-admitted proof issuance) and the enforced policy selector the mediator follows to the immutable `policy.<endpoint>.<digest-hex>` version; the mediator reads govern and policy for its OWN endpoint only, the confined-reader identity bind) PLUS the immutable `policy.<endpoint>.>` version it names; PLUS create-only publish on the endpoint's EPF decision subjects for the TERMINAL REJECTION settle only (\xA713.8: its own recheck refusals and the retirement/policy drains, which settle through it); the broker cannot distinguish a rejection payload from an acceptance, and rejection-only is NOT subject-expressible (both decisions MUST share the create-only decision subject for first-wins settlement), so this grant's residual is explicit per D32: a compromised mediator can forge a decision for ITS endpoint INCLUDING AN ACCEPTANCE, an escalation to injecting executed work, never merely reject/stall (the same class of trust already placed in that endpoint's canonicalizer), and never beyond its endpoint (the decision-publish row is endpoint-literal); obligation enumeration (the \xA713.1 retirement barrier's `oblig.<targetUid>.>` discovery + quiescence recheck, and the mediator's own `oblig.*.<endpoint>.>` policy-movement drain, \xA713.6) runs through a SEALED records scanner, the same seal as the auth-ledger scanner above: this profile holds NO `$JS.API.CONSUMER.CREATE` (nor INFO/MSG.NEXT/DELETE) on `cotal_records_<space>`, because a consumer-create request BODY is not subject-ACL confinable: an extended `CONSUMER.CREATE.<records>.<name>.<oblig filter>` grant still admits a body with `durable_name` and a push `deliver_subject`, a DURABLE exporter of the whole `oblig.` subtree that SURVIVES the credential's connection close and revocation (nats-server#8274; reproduced live against the prior grant). The fence-free `LastPerSubject` enumeration `CONSUMER.CREATE` lives in exactly ONE profile: a sealed records scanner the trusted process opens for itself and NEVER hands out (its credential, connection, and seed reach no caller; the same process-memory residual class as the auth-ledger scanner), pinned to ONE literal consumer name under a FORCED pull/ephemeral/`AckPolicy.None`/`DeliverPolicy.LastPerSubject`/memory config, bind-verified before use and unconditionally deleted after, its CREATE filter confined to the `oblig.` subtree, and the injected scanner bonded to its exact space so a hand-assembled or foreign-space scanner never enumerates; its fencing `STREAM.MSG.GET` rows are stream-level grants whose read exposure is space-wide, explicit per D32 (the terminal-cleanup row's same read residual); its reply inbox is connection-scoped (`_INBOX_<connId>.>`, never the account-wide default); the rows are NEVER-DELETED, a WRITER discipline the broker cannot fully enforce: the raw KV publish grant is operation/header-blind, so a compromised mediator can overwrite its own endpoint's row to a valid `terminal` value (hiding cleanup debt) or emit DEL/PURGE markers, where every reader refuses a deletion marker loud as corruption (\xA713.12 retention floor) and the records stream denies stream-API message-delete/purge, leaving the valid-row overwrite as a second explicit D32 residual, exactly parallel to the decision-forge residual and confined the same way (its own endpoint's rows only) | mediated |\n| Terminal pool cleanup (\xA713.1 barrier) | the retirement cleaner profile: minted per (retirement `op` \xD7 endpoint), its grant listing the EXACT pools of this operation's EFFECTIVE INVENTORY, DISCOVERY-ONLY: the target's accepted `oblig.<lifecycleUid>.>` pool routes (the barrier takes no caller-supplied hint, so every listed pool is one the target holds accepted work on), never a pool wildcard, never space-wide EPW rights, DISTINCT from every owner/agent/endpoint profile (never the revoked owner's credential), bounded-lived and, once the pool is proven quiescent (every prior owner ACK drained through `AckWait`, and a fresh consumer read shows zero `num_pending`/`ack_pending`; a fire-and-forget ACK confirmed with `AckSync`, never assumed), REVOKED and cluster-verified-EVICTED (its own principal) BEFORE any frontier records (\xA713.1 order), so no in-flight cleaner can ACK a redelivery after the alias is reused | runs only AFTER the target's obligation drain reached quiescence (\xA713.1 order) and BEFORE the frontiers; bind-only on each named pool's provisioner-pre-created durable: `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>`, `$JS.API.CONSUMER.MSG.NEXT.EPW_<space>.<poolD>`, `$JS.ACK.EPW_<space>.<poolD>.>` (re-proving at bind, per the work-pool row, that the durable's filter is exactly the named pool's subtree, pull mode, unlimited delivery ceiling), plus its own connection-scoped reply inbox `_INBOX_<connId>.>` (never the account-wide default) and leader-served terminal-observe reads `$JS.API.STREAM.MSG.GET.EPF_<space>` on `wrk.>`/`dec.>` item subjects, a STREAM-level grant whose read exposure is space-wide, explicit per D32; the cleaner holds NO lease or records authority, NO `wrk` (or any EPF/EPW) publish, NO consumer create/update/delete, NO raw stream DELETE: for each delivered message it hands the item's coordinates and requested disposition to the retirement settlement executor (next row; cleaner-supplied coordinates never authorize, the executor re-derives them from the durable acceptance), then re-reads and codec-validates the executor's lease-derived terminal, and ACKs ONLY a message whose item is durably terminal (a live, unexpired, foreign-target item is NEVER settled or ACKed, and the barrier refuses to close frontiers while one remains unsettled); this profile's explicit D32 residuals are terminal-free ACK suppression across its WHOLE EFFECTIVE INVENTORY (every discovered pool: a raw `$JS.ACK` cannot be broker-conditioned on a prior terminal, so compromise can silently drop effective-inventory-pool deliveries without settlement) and the space-wide `STREAM.MSG.GET` read exposure; it can forge NO terminal and mutate NO lease (it holds no write grant at all) | mediated |\n| Retirement settlement (\xA713.1 barrier executor) | the retirement barrier's op-bounded executor: a DISTINCT per-operation principal (`local.epexe_<opId-hash>`, CONNZ principal-tagged) minted per (op \xD7 endpoint) over this operation's EFFECTIVE INVENTORY bound to the durable intent (`opId`, target lifecycle; the pools are the target's accepted `oblig.<uid>.>` routes, DISCOVERY-ONLY (no caller-supplied hint)), its settlement code running on ITS OWN connection, live only for that operation and revoked + cluster-verified-evicted by the barrier at the same fence as the cleaner, BEFORE any frontier records; never the cleaner profile, never the barrier's standing connection, never a standing grant | the settlement seam is EFFECTIVE-INVENTORY-CLOSED: for every item the cleaner hands it, the executor re-derives the authority coordinates from the item's durable acceptance decision (a FENCING leader-served read; cleaner-supplied coordinates never authorize) and refuses a ref whose endpoint or pool is outside its EFFECTIVE-INVENTORY spec (the discovered pools), a decision that is not an accepted pool admission, an `expired` request before the item's OWN `workExpiry`, and a `retired` request for an accepted target that is not the intent's lifecycle (the confused-deputy closure: a cleaner chooses refs but can never borrow this authority beyond that effective inventory or the retirement lifecycle); it settles by CASing the item's `lease.<endpoint>.<pool>.<acceptance>.spec` record to a settled state, where the ONLY settlements it may INITIATE are `expired` (bound to the item's own horizon) and `retired` (re-bound to ITS operation's retiring target through the acceptance) and an ALREADY-settled lease DOMINATES (a crashed owner's `committed` lease is derived and its terminal published verbatim, never overwritten, never contradicted), then publishes/observes the exact lease-derived `wrk` terminal create-only (first terminal wins, \xA713.8 cancellation ordering) for the cleaner to validate; its authority is lease-record CAS plus `epf.<endpoint>.wrk.<pool>.>` publish on its effective-inventory pools plus the leader-served fencing reads its own code path performs (`STREAM.MSG.GET` on the facts stream and on the records store, plus the records store's bind-probe `STREAM.INFO` and `$JS.API.INFO`; NO work-stream read: the settlement path always settles or expires through the lease key before any EPW live-entry probe, so that read is unreachable and ungranted) and its connection-scoped reply inbox, and NOTHING else (no consumer authority anywhere, no work-enqueue publish, no auth-store access), and it carries the write residual the bounded cleaner does NOT: KV subject permissions cannot distinguish CAS from overwrite or DEL/PURGE markers, and the `wrk` publish is payload-blind, so a compromised executor can forge a lease settlement or work terminal within its WHOLE EFFECTIVE INVENTORY (every discovered pool; the per-item checks above bind honest execution, not a compromised bearer), explicit per D32, op-bounded and effective-inventory-confined, never standing, never beyond that inventory | mediated |\n| Drain commit applier (\xA713.8 accepted-self recovery) | a per-op, per-repair principal (`local.epapl_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints ONLY after the commit key passes the CLOSED self-commit class: the key's kind must resolve in the canonical frozen kind registry to a NON-authority definition whose targeted `spec`/`status` half is registered to the \xA713.8 commit-path writer, at exact arity (which structurally excludes every authority HEAD, including the 3-token lifecycle head) with every qualifier token validated; a key outside the class refuses BEFORE any credential exists (the confused-deputy closure: a forged accepted-self row cannot turn `oblig.`/`govern.`/`policy.`/`uid.`/`frontier.`/a lifecycle head/an unregistered kind into a granted coordinate) | exactly ONE `$KV.cotal_records_<space>.<commitKey>` publish row plus its connection-scoped reply inbox; NO reads, NO wildcards. It executes the mediator-validated command verbatim: the resolved, canonically digest-verified intent bytes at the pinned base revision, written by guarded CAS; a CAS loss reports the another-writer conflict and the drain's re-enumeration re-classifies (landed / superseded), never a blind retry. NAMED residual: KV subject permissions cannot distinguish CAS from overwrite or DEL/PURGE, so within its one granted key a compromised applier can overwrite or delete for the credential's short life \u2014 the confinement is the exact key, the closed class, and the op-bounded lifetime, never write semantics. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Drain route reconciler (\xA713.8 accepted-pool repair) | a per-op, per-repair principal (`local.eprec_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints only to execute a MEDIATOR-DERIVED closed repair command: the mediator reads the item's durable acceptance decision itself (a leader-served fencing read), binds it to the obligation row (fingerprint/sourceSeq/route/horizon), and derives the exact EPW item subject plus the canonical acceptance item bytes (\xA713.6); the executor re-validates the exact six-token item shape for its own space and holds NO derivation authority (row-supplied coordinates or bytes never reach a grant) | exactly ONE `cotal.<space>.epw.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` create-only publish row plus its connection-scoped reply inbox; a lost create is benign (a concurrent enqueue won; the drain re-reads establishment either way, so a no-op executor still fails closed); the payload-blind enqueue residual is confined to the one item subject for the credential's short life. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Drain effects canceller (\xA713.8 option-(i) retirement cancel) | a per-op, per-repair principal (`local.epcan_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints only to execute a MEDIATOR-DERIVED effects-cancel repair: the mediator reads and row-binds the acceptance decision itself and derives the exact completion subject (the `eff` marker or the goal `result` coordinate; the executor re-validates that exact shape for its own space); the cancelled terminal is built by the CORE validated builders, which refuse a foreign or absent target \u2014 a retirement cancels only ITS OWN target's accepted work \u2014 and never fabricate success (the effects union's `cancelled` member, or the goal union's first-class `cancelled` state with the digest-bound retirement attribution) | exactly ONE completion-subject create-publish row plus its connection-scoped reply inbox; CREATE-ONLY, so first-terminal-wins is structural (a racing real completion that landed first wins and the cancel loses its create harmlessly; the drain re-reads the winner either way, so a no-op executor still fails closed); the payload-blind single-subject create residual is confined to the one marker for the credential's short life. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Auth endpoint rail (the `auth` listener, \xA713.2) | the auth service's dedicated LISTENER credential: serve + derived replies on the `ep.one.auth` class rail, standing with the plane. The surface is GENERIC \u2014 \"retire a lifecycle (owner, actor, lifecycleUid)\" \u2014 never caller-specific; the TARGET rides the subject as the `handle` triple (`ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.<nonce>`) and caller attribution is the SUBJECT-derived, broker-ACL-enforced caller triple. The reply target is DERIVED from the parsed request (responder instance + caller triple + nonce), so no caller- or payload-supplied reply target can arrive at all \u2014 the bound-reply rule became structural rather than a check. Serve-time authz is the RAIL-TIME serve-issuance-gate check, fresh per request: ONE leader-served `STREAM.MSG.GET` of `epgate.<serveEndpoint>.<serveInstanceId>` \u2014 coordinates the caller NAMES but which do NOT authorize \u2014 requiring (a) the row is present and not `retired`, (b) `row.principal == principalKey(callerOwner, callerActor)` (THE PRINCIPAL CROSS-CHECK: a caller may only be authorized by its OWN serve registration; naming a foreign row buys a refusal, never an authorization), and (c) `row.processEpoch == serveEpoch` (a superseded predecessor after a restart is refused). An absent or TTL-expunged row reads ABSENT and refuses fail-closed. This binding is ALIAS-LEVEL, not incarnation-level: the gate is keyed by the PERSISTED `instanceId` and its row carries no lifecycle uid, so a same-principal predecessor presenting the current epoch still passes \u2014 binding the publishing incarnation would require a gate-row schema change. The four-outcome idempotence table answers in operator vocabulary (already-retired = success; the same stable opId resumes; a foreign operation refuses naming it; a stale incarnation refuses naming the current one), and every refusal is a COMPLETE no-op stated as such | subscribe `ep.one.auth.>` QUEUE-QUALIFIED (queue group `auth`; \xA713.9 forbids a plain subscribe of the class rail) + publish `ep.reply.auth.<instanceId>.<epoch>.*.*.*.*` (REPLY PLANE ONLY: the request and reply planes are disjoint in the grammar, so the listener credential cannot express a request subject at all \u2014 the self-forge is closed structurally, not by carving replies out of a shared subtree) (replies ONLY: the handler only ever responds on the DERIVED reply subject, and the reply plane cannot express a request subject at all, so a request is unpublishable by the listener credential, closing the self-forge where a compromised listener publishes a request as an authorized caller and passes its own subject-derived check) + `$JS.API.INFO` + the ONE serve-issuance-gate read row + its connection-scoped inbox; NO store writes, NO consumer authority, NO scanner/plane reach \u2014 every executing right stays with the plane's own registry and retirement deps (the drain rides the plane's ONE sealed records scanner) | mediated **NOW A CONFORMING ENDPOINT (Cotal #399, closed): the plane registers `svc.auth.<instanceId>`, publishes contract artifacts, and serves the reserved `describe`, so a generic client discovers and invokes this command the way it would any other registered endpoint (the two rows immediately below). The rail answers the v1 envelope; a legacy `{op,args}`/`{ok,data,error}` body is refused `unsupported-version`.** |\n| Retirement requester (per-despawn, \xA713.2) | an EPHEMERAL one-shot credential the space manager mints per despawn (`retirement-requester` profile, five-minute window): request + reply ONLY, for exactly ITS OWN caller triple AND exactly ONE grant-pinned TARGET incarnation (the `handle` triple is literal in the grant; the per-request nonce is the only wildcard token), so a leaked requester cannot be re-aimed at another lifecycle. The manager derives a STABLE opId from the retiring lifecycleUid, so a despawn retry, a same-name-spawn nudge, and the auth service's boot resume all drive the SAME operation. The requester holds no executing right \u2014 a leaked credential can only ask the rail to retire a lifecycle, and the rail's fresh serve-issuance-gate check (including the principal cross-check) + idempotence table bound what that ask can do | publish exactly `ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.*` (its minting manager's own caller triple, its one target) + subscribe its own reply-plane filter `ep.reply.*.*.*.<cO>.<cA>.<cUid>.*` and its connection-scoped inbox; nothing else | mediated **`handle`-MODE DEVIATION, stated explicitly (Cotal #399): this row is NOT redemption-minted.** `handle` is normatively redemption-minted only - its triple pinned at redemption from an issuer-signed capability artifact, carrying attenuation, conferral through the trusted auth service, and ledgered `sourceChain` lineage. **This path has NO issuer-signed artifact, NO redemption step and NO `sourceChain`**: the row is built directly from the minting manager's own coordinates under root authority. `handle` is used because it is the ONLY mode with arity 3 (every other mode resolves against the CURRENT mapping, the wrong semantics for retiring a NAMED incarnation), and the reader-facing invariant - the validator re-checks only currency - IS honoured by the serve-time mapping check. What is absent is delegation lineage and artifact revocation; there is no independent issuer/holder boundary on this one-shot path whose revocation would change this requester's authority. Genuine redemption-shaping is tracked at #399. |\n| Registered auth instance (Cotal #399, the M4 conformance closure) | the auth service's own boot registration, over the plane's registration credential (\xA713.1) | the plane registers `svc.auth.<instanceId>` through the standard `registerServiceInstance` path (the same record shape and registration barrier every other endpoint uses), publishes its `retire-lifecycle` contract artifacts to the content-addressed contract store, and serves the reserved `describe` alongside the command: a generic client's `resolveService` now discovers this endpoint, its closure digests, and its current instance/epoch the way it would any other registered service, closing the round-8 `#399` gap named in the two preceding rows | subscribe `ep.one.auth.>` QUEUE-QUALIFIED (queue group `auth`) + describe reply on the same reply-plane rows as any other registered endpoint + the registration-barrier and contract-artifact publish rows shared by every `registerServiceInstance` caller; no additional store authority beyond that shared registration path | mediated |\n| Retirement requester, describe + registered-endpoint call (Cotal #399, the M4 conformance closure) | the same `retirement-requester` profile above, now calling through the generic client (`resolveService` + `invokeCommand`) instead of a hand-built subject | in addition to the exact-mode `retire-lifecycle` request row already granted above, the profile carries the baseline wildcard-endpoint `describe` row (`epDescribeAllGrantRow`, pinned to this caller's own triple) and a bounded contract-store direct-get row (`$JS.API.DIRECT.GET.<EPC stream>.<space>.epc.>`) so the requester can resolve the endpoint's registered contract digests before it calls; the request itself is still minted in `exact` mode, target-pinned to the one incarnation named at mint time | publish the same exact-mode request row as above + the describe wildcard row + the contract-store direct-get row; subscribe its own reply-plane filter and connection-scoped inbox; nothing else | mediated |\n| Governance head (registration linearization) | the provisioner-registration principal | the **unsplit** governance head `$KV.cotal_records_<space>.govern.<endpoint>` (\xA713.7): it reads the head FRESH under the frozen registration gate (a FENCING read, read service above: leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` last-by-subject on the head key, never the follower-served `DIRECT.GET` the records bucket would allow) and is the head's ONLY writer (slot-take CAS in phase 1, promote CAS after the spec publish); the SAME principal holds the write on `$KV.cotal_records_<space>.policy.<endpoint>.>` (each immutable policy version is published exactly once, before the stage CAS that names it). The immutability of a policy version is a TRUSTED-WRITER INVARIANT, not a broker-enforced subtraction: KV create/update/delete all publish to the one `$KV.\u2026policy.<endpoint>.<digest>` subject, and NATS subject permissions cannot distinguish the create-CAS header or the `KV-Operation` header, so a subject grant cannot forbid an overwrite or DEL. The invariant is upheld by the writer's create-only CAS plus every reader's SELF-CERTIFICATION (\xA713.7: the value must digest to the key), so a changed-byte overwrite is REFUSED on read; the residual, confined to this prefix, is that a buggy or compromised provisioner could still DEL or same-byte-overwrite an enforced version and (history 1) destroy its availability, at which point admission pauses fail-closed rather than admitting under a lost policy. No agent, endpoint, observer, admin, or host profile holds any grant. The head is NEVER-DELETED (the `lifecycle`-head discipline): no grant permits DEL/PURGE on `govern.>`; a reader treats only TRUE ABSENCE as a virgin head, and a deletion marker refuses loudly as corruption (\xA713.12 retention floor), never as absence | mediated |\n\nTerminal pool cleanup settlement is lease-fenced across the two profiles above: the executor\nCASes the item's lease (or observes the winning settled lease), publishes/observes the exact\nlease-derived `wrk` terminal, and only then does the cleaner, after re-reading and\ncodec-validating that terminal, ACK the delivery. A `wrk` create that bypasses the lease CAS is\nnon-conformant: it can contradict a racing commit.\n\nAn `eff` completion fact `epf.<endpoint>.eff.<cO>.<cA>.<cUid>.<id>` is a CLOSED two-member\nunion carrying a REQUIRED `outcome` discriminant on EVERY member (the goal union's `state`\nbar, applied to effects: a member is never structurally assignable to the other, and every\nreader is forced to read the outcome). The RAN member is\n`{ v: 1, id, fingerprint, caller, sourceSeq, ts, outcome: \"ran\" }`; the RETIREMENT-CANCELLED\nmember is `outcome: \"cancelled\"` plus exactly `cancelled: { opId, target }` \u2014 the same\nidentity spine, plus the binding to the retiring target's lifecycle and the retirement\noperation that cancelled it. A fact missing the discriminant, or claiming one outcome while\ncarrying the other's fields, refuses. A reader that sees `cancelled` KNOWS the effect did not run; the member is never\na forged success. Both members' caller triple and `id` are bound by the subject, and their\n`fingerprint` and `sourceSeq` MUST equal the accepted decision's. The cancelled member may be\nwritten ONLY for an acceptance whose own `target` names the retiring lifecycle (a retirement\nnever cancels a foreign target's work), publishes CREATE-ONLY on the SAME subject the real\nmarker would use \u2014 so first-terminal-wins is structural: a racing real completion that lands\nfirst wins and the cancel loses its create harmlessly, and vice versa \u2014 and is produced by\nthe drain's per-op canceller profile (\xA713.9). An ACTION needs no new member: the `goal\u2026.result`\nunion already carries the first-class `cancelled` outcome state, and a retirement-cancelled\ngoal terminalizes through it with the same acceptance-fingerprint binding and the retirement\nattribution in its digest-bound payload (`data.cancelledBy = { opId, target }`). An\neffects-route drain compares the PARSED fact against the acceptance and treats EITHER bound\nmember as established; an action's drain instead requires the parsed `goal\u2026.result` fact whose\n`fingerprint` matches the acceptance. Subject presence alone never proves completion: a bare,\nmalformed, or mismatched fact refuses the drain loud (\xA713.8).\n\nRaw `STREAM.MSG.GET` and `CONSUMER.MSG.NEXT` authority carries a caller-selected reply subject.\nFor every trusted profile holding those APIs, D32 includes confused-deputy response injection:\ncompromise can direct fetched API/message bytes onto a foreign subject even though its\nconnection-scoped inbox prevents subscribing there. This is injection, not foreign read access,\nand requires a future fixed-destination mediation boundary to remove.\n\nDeletes beyond these rows: only the lifecycle-keyed deprovisioner (exact names, \xA713.1) and\nstream retention.\n\nA **mediated** row means the raw storage grant is held only by a narrowly scoped writer\nprincipal (per endpoint, never a universal writer), with authenticated caller binding,\nidempotent request semantics, and bounded failure/backpressure; CAS headers, fingerprint\nrules, schema validity, and digest-correct bytes are *enforced* there. A **direct** row means\nthe broker guarantees writer/key containment only, and the row **explicitly downgrades**\nCAS/schema/header/byte correctness to a conforming-client guarantee; readers of direct-row\nstate fail loud on invalid content. No profile (agent, observer, admin, host) holds generic\n`$JS.API.>`/`$KV.>`/`$O.>` authority over control-surface state, for the contract store that\nmeans the REAL subjects and APIs: **write** on `cotal.<space>.epc.>` belongs\nto the contract publisher alone (create-only per digest subject); **read** is the\nsubject-scoped last-by-subject Direct Get of the reader row above, never a body-selected\nform and never a consumer, because there is nothing to replay: one message per digest\nsubject IS the store, with verify-on-read as the tamper\nboundary; and the **stream-management surface** of `EPC_<space>`\n(`$JS.API.STREAM.{UPDATE,DELETE,PURGE,MSG.DELETE}.\u2026`) is held by NO profile, publisher\nincluded, stream lifecycle belongs to space setup under operator provisioning authority\nonly, which is what \"immutable once published\" rests on (a `$OBJ.>` deny matches no NATS\nsubject and audits nothing).\nThe matrix is re-audited mechanically (decoded-credential fixture + live positive/negative\nprobes, with predicates over the real `$O.`/`$JS.API` subject forms) at every phase that\nadds a resource or changes ownership.\n\n**Writer table (core kinds, mediation decided, D7: authoritative CAS/schema record writes\nare mediated by separately scoped spec/status writer principals; an endpoint holds no raw\noverwrite grant on its own record keys).** `svc`, spec: the provisioner/registration path,\n**mediated** (CAS + schema enforced at registration); status: the owning instance's commit\npath, **mediated** with **epoch currency enforced at the writer**: the writing epoch is\nread from the broker-authenticated `epr` ingress subject (\xA713.2, the instance's serve\ncredential pins the epoch token there, so a stale process CANNOT claim the successor's\nepoch: the value is attested by the grant, never by payload), and the writer validates it\nagainst a FRESH read of the authoritative lifecycle mapping's `processEpoch`,\nrejecting a non-current epoch (`expired`), monotonicity against the stored status epoch\nalone is NOT sufficient, because between the takeover CAS (mapping N\u2192N+1) and the completed\nrevoke/evict barrier the superseded N would still equal the stored status epoch and pass a\nbelow-stored check, and additionally rejects a below-stored epoch (`conflict`). The record\nkey is restart-stable and\ncannot carry the epoch (\xA713.1), so this epoch-pinned-ingress-plus-fresh-equality mediation\nis the record's only stale-writer fence.\n`signer`, spec+status: the space operator's registry tooling as the scoped writer\nprincipal, **mediated**. `handle`; keys are **issuer-namespaced**,\n`handle.<issuerKeyId>.<id>`, so two issuers can never collide or cross-revoke; spec: the\nissuer through the record-writer seam, create-only; status/revocation: issuer or space\noperator, **mediated and monotonic** (revoked never un-revokes; the signature stays the\ncontent authority; mediation enforces key grammar, CAS, and schema). `contracts` index, the instance, **direct** (explicitly advisory and\nnon-authoritative; `describe` is authoritative; readers fail loud on invalid state).\n`goal`/`cp` projections, status: the owning instance's commit path, **mediated**. Lifecycle\nmapping records (\xA713.1), the minting manager's commit path, **mediated**, CAS-only. The\n`govern` head (\xA713.7), the provisioner-registration principal, **mediated**, CAS-only (the\nmatrix row above).\nCanonical acceptance, work-pool enqueue, lease state, and contract-artifact publication,\n**mediated** per the matrix above.\n\n**Trait seam.** Core owns the fail-closed pre-effect verification interfaces (guard call,\npriced-proof verification, governed-attachment verification); policy engines, token formats,\nand payment rails remain extensions behind those seams.\n\n### 13.10 Receipts and signing trust anchors\n\n**Receipts.** A receipt binds a request to its outcome, signed and non-repudiable, for\nmetering, disputes, and pipeline causality; payment semantics stay opaque to core.\n\n`Receipt` = `{ v: 1, requestId, sourceSeq (the accepted submission's sequence, the\nexecution identity its subject carries, \xA713.2), space, endpoint, command, instance: { id, instanceId, epoch },\ncaller: { id, lifecycleUid }, schemaDigests: { input, output }, argsDigest, outcome: { ok,\ncode? }, resultDigest?, ts, signer: { keyId }, sig }`, canonical JSON, Ed25519-signed\n(`space` per the unconditional artifact rule below).\nLifecycle and epoch are recorded as **evidence**, never redemption authority. A command\ncarrying `ai.cotal.priced` MUST verify an independently verifiable payment proof in the\n`auth` slot before effect (never a bare \"settled\" assertion) and emit a receipt fact\n(`epf\u2026.receipt.<cOwner>.<cActor>.<cUid>.<id>.<sourceSeq>`, the caller- and\nexecution-scoped subject of \xA713.2; receipts are create-only per subject). A priced command\nis therefore journal-class: its receipt derives its identity from the accepted submission's\ndecision fact and its outcome from the committed terminal, never from emitter-supplied\nparameters, so a command with no acceptance fact has no receipt to emit; a conforming\nimplementation refuses to serve `ai.cotal.priced` on an ephemeral command (an\nadmission-time refusal at serve construction, never a first-request surprise). Receipt\nretention: default 90 d, \u2265 the idempotency horizon (outcome-stated by the \xA713.12 retention\nfloor).\nVerification: signature against the anchor registry + digest recomputation; forged or\nrequest-mismatched receipts fail loud. Receipts MAY be emitted for unpriced commands.\n\n**Trust anchors.** One per-space registry covers every signed artifact of this section,\nauthorization slots, capability handles, checkpoint resumes, trait definitions and\nattachments, session grants, receipts. Anchors are `signer.<keyId>` records: spec =\n`{ keyId, publicKey (Ed25519), owner (the principal or reverse-DNS domain the key belongs\nto), roles \u2286 [handles, traits, receipts, resume, sessions, authz-slots, obligations,\npayments], scope: per-role structured ceilings, for a `handles`-role key the **full grant\ndimensions**, in the handle-grant shape itself: the endpoints/domains, and per entry the\nmaximal commands, authorization modes, target patterns, instance ids, and read subtrees the\nkey may issue for (a handles- or receipts-role key without a dimension ceiling has that\ndimension closed, not open); for other roles the endpoints/domains it may attest for,\nvalidFrom, validTo }`, status = revocation. `issuer-authority` is defined by exactly this\nrecord: a verifier resolves the artifact's keyId FRESH at verification and enforces the role\nAND its scope under the \xA713.6 containment order (`handle.grants \u2286 anchor.scope`), a\nhandles-role key scoped to `com.acme.>` cannot issue for `manager`, a receipts-role key\nscoped to one endpoint cannot attest as another, and a handles-role key whose scope names no\n`handle`-mode targets cannot issue actor-pinned grants. Verification (fail closed): resolve the key,\nreject unknown keys, out-of-window use, role mismatch, or revocation (immediate for new\nverifications; effected work is not retroactively unwound). Rotation registers a successor\nand closes the predecessor's window; overlap is permitted for handoff. Third-party trait\nauthorities register under their reverse-DNS domain claim. Trust roots never merge across\nspaces.\n\n**Signature encoding (normative, D28).** For every signed artifact: the signature input is\nthe UTF-8 bytes of the RFC 8785 canonical JSON of the artifact **with its `sig` field\nabsent**; the signature is Ed25519 (nkeys); `sig` carries it base64url-encoded (unpadded).\nVerification recomputes the canonical form, resolves `signer.keyId`/`issuer.keyId` in the\nanchor registry, and fails closed on any mismatch.\n\n**Replay and claims matrix (normative, per artifact type).** Every row below additionally\nand unconditionally requires `space`, the signing `keyId` (`issuer`/`signer` per shape), and\n`sig` (the \xA713.10 encoding): an artifact missing any of the three is invalid before its\nreplay rule is ever consulted, and each artifact type is a discriminated schema, a verifier\ndispatches on the type, never duck-types the claims.\n\n| Artifact | Required claims | Replay rule |\n| --- | --- | --- |\n| Capability handle | id, space, issuer, holder (principal+UID), structured grants, iat, exp (nbf, parentDigest, epoch as applicable) | reusable within TTL, holder-bound; revocable if sturdy |\n| Checkpoint resume | checkpoint token, goal id, holder (principal+UID), iat, exp, nonce | **one-use** (journaled by create-only CAS); duplicate = `conflict` |\n| Session grant | sessionId, subjects, holder (principal+UID+processEpoch), serving instance+epoch, window, iat, exp, nonce | **one-use** redemption (holder epoch fresh-checked), then live; dies with either side's epoch |\n| Guard obligation | goal/request id, attenuations, iat, exp | bound to its goal/request; reusable within it |\n| Payment proof | per the priced contract's declared policy | default one-use per request id |\n| Trait attachment | endpoint, command, contractDigest, traitUrn, value, signer, ts | revision-bound evidence; replaced only by an authorized contract revision |\n| Receipt | per \xA713.10 shape (ts, signer; no exp/nonce) | evidence, never authority; replay-irrelevant |\n\nEvery verifier rejects out-of-window use (where `exp` applies), wrong-holder presentation,\nand unknown/revoked keys.\n\n### 13.11 The hard cut\n\nThis section is an intentional hard cut on the pre-1.0 line per \xA711. The version marker is\nthe grammar itself: the `ep`/`epe`/`epf`/`epj`/`ept`/`epw`/`eps` subject kinds and the\nversioned envelope are disjoint from every v0.3 control subject and shape, and the old rails\nare removed, subjects, envelopes,\nhandlers, credential grants, minting paths. No compatibility adapter, dual serving, or\ntranslation window exists. A credential minted before the cut can publish only into dead v0\nsubjects: nothing subscribes them, no post-cut handler is reachable from them, no trusted\nreply can be elicited (a pre-cut grant matches no endpoint-surface subject by construction,\nverified adversarially with captured pre-cut credentials from every old profile). The one\nstructural exception is the pre-cut `admin` profile, whose space-wide `P.>` subscribe\npredates and therefore MATCHES the new rails: **admin credentials MUST be re-minted at the\ncutover** to the post-cut admin shape (Appendix B: messaging-plane subjects only, no\n`ep*`/`eps`/`epc` subscribe), and the pre-cut admin credential is revoked with the cut;\nthe hard-cut guarantee is not honest without it. The wire\n`protocolVersion` (\xA76, \xA711) targets `0.4` at the completion of this revision's migration, per\nthe \xA711 convention that the advertised version is the migration's normative target, and a\nv0.4-conformant participant MUST advertise it (the optional-field era ends at the marker\nboundary); `1.0` is a separate, later stability declaration (\xA711).\n\n### 13.12 NATS + JetStream binding\n\n**Broker floor.** The control surface REQUIRES NATS server \u2265 2.12 (message schedules, atomic\ncreate-CAS, counters) AND a `max_control_line` large enough for the deployment's\nmaximum-capability CONNECT line. The two floors are checked at the tier that can see them:\n\n- **Clients** check the server version from the pre-auth INFO and fail loud below 2.12 or\n  when schedules are unavailable (including the offline-assets downgrade mode). The\n  control-line limit is NOT discoverable pre-auth; an oversized CONNECT is silently dropped\n  and looks like a network fault, so a client's obligation is bounded reconnect attempts\n  plus the named diagnostic on a repeated pre-auth drop (\"CONNECT may exceed the broker's\n  max_control_line; have the operator verify it\"), never an infinite retry loop.\n- **Operator tooling** (doctor/setup) asserts the cause before any credential is minted:\n  read `max_control_line` over the system account (`$SYS.REQ.SERVER.PING.VARZ`) from\n  **every server of the cluster the credential may connect to**; the ping is fanned out,\n  the response set is checked complete against the expected server count, and a partial\n  response set is a FAILED assertion, never a pass, and require, on each server,\n  `max_control_line \u2265 (largest encoded CONNECT line of the \xA713.9 fixture set) + margin`.\n  The fixtures are **byte-reproducible** (concrete maximum-length identities, the full\n  grant set at the policy ceiling, the maximum-capability agent credential and the\n  maximum-command serve credential, the encoded credentials, the resulting CONNECT\n  lengths), so the floor is a measured quantity; the reference deployment's configured value\n  is 65536; a derived number, not an assertion. The 16 KiB policy gate remains a distinct\n  mint-time cap on credential authority, refused loudly at minting. The same assertion pass\n  checks `max_payload \u2265` the largest serialized **bounded decision fact** fixture (the\n  maximum `RejectionFact`/`QuarantineFact` under the token and detail bounds, \xA713.4) AND\n  `max_payload \u2265` the 256 KiB contract-artifact document bound plus envelope margin\n  (\xA713.7; a contract artifact is one message on its digest subject), so\n  \"the rejection fact always fits by construction\" and \"an artifact is a single message\"\n  are measured floors, not assumptions.\n\nNo sweeper fallback exists. Only 2.12 schedule semantics are assumed (same-subject\nreplacement; NOT the 2.14 stop-plus-publish path).\n\nPer-space resources, created at space setup (`STREAM.CREATE` remains denied to agents):\n\n| Resource | Captures / holds | Retention notes |\n| --- | --- | --- |\n| `EPJ_<space>` stream | `cotal.<space>.epj.>` (submissions, untrusted) | Limits; **native dedupe not relied upon**; submitters never set `Nats-Msg-Id` (\xA713.4; stream-wide header dedupe is a cross-caller suppression vector on a shared untrusted stream). A zero duplicate window is NOT server-accepted (`0` normalizes to the 120 s default; the minimum is 100 ms), so the config sets the server minimum and the guarantee is the header rule: a hostile header suppresses only another non-conformant header-bearing write; retention \u2265 recovery/redelivery lag |\n| `EPF_<space>` stream | `cotal.<space>.epf.>` (canonical facts) | Limits; acceptance via create-only CAS (`Nats-Expected-Last-Subject-Sequence: 0`); `allow_direct=true` (NON-fencing subject-confined reads only: every \xA713.9 matrix fact read is FENCING and leader-served `STREAM.MSG.GET`, \xA713.9 read service); retention \u2265 horizons, outcome-stated by the retention floor below |\n| `EPE_<space>` stream | `cotal.<space>.epe.>` (events, progress) | Limits; space policy |\n| `EPT_REQ_<space>` stream | `cotal.<space>.ept.*.*.*.*.schedule` (instance schedule REQUESTS, \xA713.2) | Limits; message schedules **DISABLED**; client-set scheduling headers are inert bytes here; retention \u2265 writer recovery lag |\n| `EPR_<space>` stream | `cotal.<space>.epr.>` (record-write ingress, \xA713.2) | Limits; epoch-pinned publish grants (\xA713.9); consumed only by the record writer; retention \u2265 writer recovery lag |\n| `EPT_<space>` stream | `cotal.<space>.ept.*.*.*.*.armed` + `\u2026.fire` (authoritative schedules + fires, \xA713.2) | `AllowMsgSchedules`; only the timer writer publishes `.armed` (\xA713.9); each schedule targets its sibling `.fire` subject (ADR-51 forbids target = publish subject); retention \u2265 max deadline + margin |\n| `EPW_<space>` stream | `cotal.<space>.epw.>` (work pools; one item per subject, \xA713.2) | WorkQueue; provisioner-pre-created non-overlapping exact-filter per-pool consumers (\xA713.9) with **`max_deliver=-1` pinned** (a finite delivery ceiling strands exhausted items outside `num_pending`/`num_ack_pending` and falsifies the \xA713.6 admission occupancy; the occupancy reader re-checks the pin at every read because MaxDeliver is editable post-create); **`allow_direct=false`**: EPW has NO non-fencing subject-confined reader (pool workers drain the WorkQueue via `CONSUMER.MSG.NEXT`, never a subject read), and its ONLY subject read is the reconciliation probe, which is FENCING and MUST be leader-served `STREAM.MSG.GET` (\xA713.9 read service; an acked item leaves the WorkQueue, an in-flight one remains readable, which is exactly the \xA713.6 predicate, and a stale follower miss would re-arm settled work). Disabling Direct Get on EPW makes that leader-served requirement STRUCTURAL: no reader (including virtual-endpoint activation reconciliation, \xA713.6) can take the follower path even by mistake. This differs from EPF, which keeps `allow_direct=true` because it DOES have non-fencing subject readers (the \xA713.9 last-by-subject fact reads); EPF's fencing CAS-winner read opts into the leader by caller choice |\n| `WFJ_<space>` stream | `cotal.<space>.wfj.*` (the workflow STEP JOURNAL, \xA714.4: **one subject per RUN, `cotal.<space>.wfj.<runId>`, not one per entry**) | Limits, file storage, **no `max_age`** and no finite count/byte limit that evicts (an evicted prefix is not a shorter journal, it is a run that re-performs effects it already performed, and a run that sleeps for a month resumes by re-reading it; retirement is by subject purge, deliberately); **`allow_direct=false`** (a resume must read its own predecessor's last appends, and Direct Get is follower-servable, so a stale miss there reads as \"this step never ran\"). Deliberately outside the `ep*` plane letters: the journal is a runtime layer over the control surface, not part of the endpoint contract. Every append is fenced by `Nats-Expected-Last-Subject-Sequence` on the run's own subject (\xA714.4); a run's driver holds publish on exactly its own run's subject plus a per-takeover replay durable filtered to it, and there is no space-wide `wfj.>` publish grant |\n| (sessions: core-only, no stream) | `cotal.<space>.eps.>` | never captured; bounded in-memory window |\n| `cotal_records_<space>` KV | records: the \xA713.7 core-kind key grammars (`svc`, `signer`, `handle`, `contracts`, `goal`, `cp`, `lease`, `lifecycle`, `govern`, `uid`, `policy`, `oblig`, and the \xA714 kinds `run`, `answer`, `notice`, `migration`) | per-key CAS; `.spec`/`.status`-split keys EXCEPT the unsplit atomic keys `lifecycle.<owner>.<actor>`, `govern.<endpoint>`, `uid.<lifecycleUid>`, `policy.<endpoint>.<digest-hex>`, and `oblig.>` (\xA713.1/\xA713.7/\xA713.8/\xA713.9); `allow_direct=true`, but the heads and every fencing read are leader-served `STREAM.MSG.GET` (\xA713.9 read service). **No age retention on authority keys:** `lifecycle` heads, `govern`, `uid` reservations, `policy` versions, and `oblig` rows are NEVER-DELETED (no grant permits DEL/PURGE; an age-evicted reservation would reopen UID reuse, an evicted obligation would orphan accepted work); a deletion marker on any of them refuses loudly as corruption, never as absence. **Shape is proved at bind, not assumed:** the stream MUST be primary (never a mirror/sourced copy) and MUST carry no bucket-wide silent-eviction limit (no `max_age`, no finite `max_msgs`/`max_bytes`: under `DiscardOld` a finite global limit evicts a prior authority key's latest row the moment an unrelated key is written); every trusted consumer of this store (the minting authority, the mapping reader, the mediator) verifies exactly this via `STREAM.INFO` when it binds and refuses to serve otherwise |\n| `cotal_auth_<space>` KV | the credential ledger (`cred.<lifecycleUid>.<credentialId>` + issuance gates `gate.<lifecycleUid>` + the disjoint endpoint families `epgate.<endpoint>.<instanceId>` / `epcred.<endpoint>.<instanceId>.<credentialId>` + the staging family `stage.>` + source gates `srcgate.<issuerKeyId>.<id>` + lineage index `bysrc.\u2026`, \xA713.1) + session ledger (`session.<sessionId>`, \xA713.6) | trusted auth path ONLY; no agent, endpoint, observer, admin, or host profile holds any grant (\xA713.9 matrix); **`allow_direct=false`** (every fence is a leader-served revision-pinned CAS write; Direct Get's follower/mirror reads would defeat read-your-writes, \xA713.1); CAS + monotonic states. **No bucket-wide age retention:** `gate.`, `epgate.`, `srcgate.`, and `session.` authority keys persist until their lifecycle/handle/session is explicitly terminal (an age-evicted `open` gate would silently reopen minting, or drop a `frozen`/`retired` fence); only `cred.`/`epcred.`/`bysrc.` rows carry a per-key TTL bounded by the credential TTL (NATS per-key message TTL, \u2265 2.12), never a bucket MaxAge; `stage.` rows follow their operation's retention, never a ledger row's. **Shape is proved at bind** (the records-store rule above, plus `allow_direct=false`): primary, un-mirrored, no bucket `max_age`, no finite `max_msgs`/`max_bytes`; the trusted auth path verifies this via `STREAM.INFO` when it binds and refuses to serve otherwise |\n| `cotal_issued_<space>` KV | issued-authority evidence (\xA713.15): `v1.<owner>.<actor>.<uid>.<generation>` (immutable evidence), `attempt.v1.\u2026` (the one-field attempt row), `bysource.v1.<sha256>.\u2026` (the reverse index from a source gate to the issuances depending on it) | Limits, file storage, no age eviction, **`allow_direct=false`** (every read is a fence); create-only evidence, revision-CAS attempt; never deleted while the issuance or anything admitted under it is resumable. Immutability is BROKER-ENFORCED the way the EPC store's is: `allow_rollup_hdrs=false, deny_delete=true, deny_purge=true`, set once at creation and verified by every provisioner that binds, so a holder of the issuer's own key row cannot replace evidence or empty the bucket with a `Nats-Rollup` header, a message delete, or a purge |\n| `cotal_accepted_<space>` KV | accepted rows (\xA713.15): `accepted.v1.<acceptedToken>`, one per issuance, written by the issuer at release | Limits, file storage, `allow_direct=true`: the client's per-key `DIRECT.GET` is the discovery read; create-only, with the same three broker-enforced flags as the evidence store |\n| `cotal_admission_<space>` KV | run admissions and revocations (\xA714.8): `admission.v1.<endpoint>.<runId>`, `revoked.v1.<endpoint>.<runId>` | Limits, file storage, no age eviction, `allow_direct=false`; both keys create-only and the marker permanent, BROKER-ENFORCED by `allow_rollup_hdrs=false, deny_delete=true, deny_purge=true` (a run-admitter's own key row admits no `Nats-Rollup` replacement of the admission, and no purge empties another run's row); retained while the run, its program, its journal or its lineage is resumable |\n| `EPC_<space>` stream | `cotal.<space>.epc.>` (content-addressed contract artifacts, one per digest subject, \xA713.7) | Limits, no age eviction (artifacts are permanent); create-only mediated publication (`Nats-Expected-Last-Subject-Sequence: 0`); `allow_direct=true` (the subject-scoped last-by-subject read IS the fetch path; non-fencing, verify-on-read); permanence is BROKER-ENFORCED: `deny_delete=true, deny_purge=true` (the broker rejects the message-delete and purge APIs even from a stream-API-holding principal). Permanence is the COMBINATION of these flags, the retention floor's no-early-removal rule (below: the flags alone stop delete/purge but not age eviction or a whole-stream teardown), verify-on-read pinning WHAT a subject carries, and the stream-management surface held by no profile (\xA713.9); no single flag makes deletion structurally impossible |\n\n**Retention floor (one-use-identity facts).** A stream or bucket whose messages carry\none-use identity, that is decision facts realizing the \xA713.4 idempotency horizon, goal\nterminal facts and tombstones (\xA713.6), receipt facts (\xA713.10), and the never-deleted\nauthority heads (`lifecycle`, `govern`, the auth-bucket gates), MUST retain every protected\nmessage until its governing horizon, stated by OUTCOME: NO removal cause may drop a\nprotected fact early. That forbids not only age eviction below the horizon but every\nconforming alternative that erases it while `MaxAge` still passes: a finite\n`MaxMsgs`/`MaxBytes`/`MaxMsgsPerSubject` with `DiscardOld`, a per-message TTL,\nrollup/compaction, or a retention-policy change; for these families finite count/byte\nlimits MUST fail loud or `DiscardNew` rather than evict protected history, and message TTL\nand rollup MUST be disabled on protected subjects (a per-key TTL is permitted only on\nnon-protected keys, e.g. the auth bucket's `cred.`/`bysrc.` index rows above, never on a\nprotected fact, head, or gate). NO principal, including operator, setup, and system tooling,\nnot only \xA713.9 profiles, may `MSG.DELETE`/`PURGE`, `STREAM.DELETE`, or issue a\n`STREAM.UPDATE` that weakens any of these limits; the never-deleted heads and gates carry\nan UNBOUNDED horizon. A KV writer MUST NOT publish a DEL/PURGE marker for a never-deleted\nkey, and a reader that encounters one treats it as corruption, never as absence. (Root can\nalways destroy a broker; such an act is explicitly non-conformant, not outside this\nclause.) `CONSUMER.DELETE` is distinct and permitted: it removes a reader cursor and can\nnever mutate stored facts. Concretely: `EPF_<space>` retention \u2265 max(idempotency horizon,\nresult retention, receipt retention), because the acceptance fact is the durable\nreconstruction source for receipts, while the raw submission stream is age-evicted by\ndesign.\n\nClaim pools are pull consumers on `EPW` with `AckExplicit`, held **only by the pool's owning\nendpoint** (\xA713.5): `ack_wait` is the broker's redelivery-to-owner timer and nothing more;\nthe authoritative lease token and deadline live in the owner's lease record, never in the\nitem value (stored bytes are work identity and input only), and the owner acks only after\nthe committed terminal state. Filtered replay of events/facts uses pinned single-filter\nconsumer creates (the CHAT-history containment mechanism, \xA78/\xA79). Timer scheduling is\n**mediated** (\xA713.2, \xA713.9): instances publish only `.schedule` REQUESTS into the\nschedules-disabled `EPT_REQ` stream, where a client-set `Nats-Schedule-Target` (or any\nscheduling header) is inert bytes and the timer writer rejects a request carrying one, this\ncloses the ADR-51 confused deputy, in which a direct publisher confined only to \"some\nsubject the schedules stream captures\" could target ANOTHER instance's `.schedule` (installing\nor replacing its schedule state, since schedule headers are copied to the target verbatim) or\nits `.fire`. The timer writer alone publishes the authoritative schedule on `.armed`, with\n`Nats-Schedule-Target` = the sibling `\u2026.fire` subject derived from the authenticated request\nsubject's own tokens; and **fire handling is the trusted seam** behind it, a `.fire`\nconsumer acts only on a fired message matching a current authoritative\nschedule it owns (`timerId` + generation + deadline, \xA713.2) AND whose broker-authored\nscheduler-origin header (`Nats-Scheduler`, the schedule's subject, set by the server on\nfire) equals its own exact sibling `.armed` subject, discarding anything else as\nforged. Replacement is the writer's same-subject publish on `.armed` (server rollup); fired\nmessages appear on `.fire` carrying `(timerId, generation)`.\n\n### 13.13 Plane ownership (the sealed-scanner claim)\n\nAt most ONE authority plane per space may hold the sealed scanners (\xA713.9's seventh-round\nseal). The scanners' serialization is process-local, so two same-space auth processes would\ninterleave the literal enumeration consumers' critical sections and return PARTIAL\nenumerations: a drain declares quiescence over undrained obligations and the retirement\nfrontiers close over live work. The exclusion is broker-visible, not host-local:\n\n- **The claim row.** One exact, never-deleted auth-KV key (`plane`, subject\n  `$KV.cotal_auth_<space>.plane`) holds `{ v, generation, claimId, state: held | released,\n  ledger, records, openedAt }`, where `ledger`/`records` are the two ownership-bearing sealed\n  scanner connections' broker identities `(serverId, cid, userNkey)`. The barrier profile is\n  the row's SOLE writer, at exact arity (never `plane.>`); reads are leader-served. The\n  barrier's own identity is deliberately NOT in the row: barrier liveness is irrelevant to the\n  literal consumers and could only falsely block a reclaim.\n- **Open order.** Ensure stores; open BOTH candidate scanner connections NON-RECONNECTING (the\n  tuples must be stable and disappearance must be final) and keep them INERT (no scan\n  capability exists or escapes); take the claim by broker-atomic create (virgin key) or\n  revision-CAS (a `released` row, or a `held` row proven dead as below). Only the WINNER\n  constructs the branded scanners; a loser closes both candidates and refuses with\n  operator-legible copy. The brief dual connected-credential window before the CAS is inside\n  the trusted signing-seed residual; there is no dual SCAN authority because the capability\n  does not exist before the win.\n- **Plane credentials.** The two plane-owned scanner connections authenticate with\n  NON-EXPIRING user JWTs, for exactly these two connections and no other profile: an expiring\n  credential would have the broker hard-disconnect at expiry, and a renewal cannot be\n  presented without the reconnect the non-reconnecting shape forbids \u2014 an expiry would fence\n  the plane on a timer. The credentials never leave process memory, and the account signing\n  seed co-resident in the same memory is strictly stronger authority, so the marginal\n  exposure is the existing trusted-process residual class; revocation remains service-stop +\n  seed rotation. Every other authority credential keeps the short-expiry + in-process-renewal\n  boundary.\n- **Reclaim is liveness-only.** A `held` row is reclaimed only when BOTH claimed tuples are\n  conclusively ABSENT under a COMPLETE connection sweep, adjudicated by the delivery daemon's\n  read-only oracle over the privileged delivery-admin rail (the auth process holds no `$SYS`;\n  the D5 rail split). The closed oracle verb takes exactly the two claimed tuples and returns\n  two bound verdicts (`live | gone | unknown`) plus sweep completeness, echoing the queried\n  identities; any live, unknown, incomplete, malformed, or foreign-echo answer REFUSES the\n  takeover (at most one plane: dual-refuse is safe, dual-proceed is not). There is NO TTL, NO\n  heartbeat, and NO \"did the last sealed scan finish\" bit: a mid-scan crash drops the\n  non-reconnecting connections, a complete sweep proves them gone, and the successor's\n  fail-closed pre-clean (\xA713.9) makes its full re-scan safe. A paused-but-live process still\n  holds its TCP connections and therefore still holds the plane (no pause hazard).\n- **The single-server proof.** Connection absence alone cannot distinguish a RESTARTED\n  claimed server (`server_id` is per-broker-run; genuinely gone, and requiring its reply\n  forever would turn every whole-stack crash into a permanent reclaim wedge) from a\n  PARTITIONED one (live, unreachable; treating its absence as death authorizes a split-brain\n  steal). A `gone` verdict is therefore valid ONLY under the single-nats-server-process\n  boundary, proven per observation from the responding server's OWN topology declaration in\n  the `$SYS` reply envelope \u2014 never inferred from which servers happened to reply: every\n  reply must declare NO cluster membership and exactly one distinct server may have replied.\n  Any cluster self-report, multi-server observation, or reply without the declaration reads\n  `unknown` and refuses. Only a SUCCESSFUL, well-formed page counts toward the sweep: a reply\n  carrying an API error, a malformed or empty server envelope, a non-string cluster\n  declaration, an envelope/data server-id mismatch, or a structurally incomplete data page\n  poisons the whole observation (every verdict `unknown`). Each sweep's reply inbox carries a\n  per-call collision-resistant nonce, so concurrent sweeps can never satisfy or falsely\n  complete each other's rounds; and the auth plane closed-parses the oracle's result (exact\n  keys at every level) before reasoning over it. NAMED residuals: a leafnode- or\n  gateway-extended account is outside the cluster self-report, so such topologies are out of\n  contract for the space's account; a backup restored onto a fresh broker can present a\n  still-running foreign predecessor's `serverId` as dead. A clustered/multi-server deployment\n  requires an authoritative server incarnation/roster authority in place of this proof.\n- **Holding invariant.** The winner re-validates the claim (state `held`, its `claimId`, its\n  `generation`, AND both pinned scanner tuples \u2014 a row rewrite preserving the identifiers but\n  swapping a tuple is a lost claim, never \"still ours\") BEFORE every sealed scan (refuse to\n  enumerate) and AFTER it (discard the enumeration), inside the serialized critical section.\n  An owned scanner disconnect is a FENCING event, and the fence is FATAL to the WHOLE\n  authority plane: scan exposure is invalidated immediately, the sibling closes, every\n  authority operation (connect authorization, credential mint) refuses from that moment, and\n  the service goes DOWN loud rather than serving from a half-dead plane a successor may be\n  reclaiming; a still-live sibling correctly blocks a successor until it is closed or proven\n  absent.\n- **Clean close.** Scan-capable clients close FIRST, then the row CASes `held \u2192 released`\n  (never released while either scanner can still act), then the barrier. A crash leaves\n  `held`; the successor reclaims through the oracle. A `released` row is claimed without an\n  oracle round.\n- **Operator faces.** The three refusal states carry DISTINCT copy: a live peer (\"stop the\n  other auth process\", with the space and connection identities), an inconclusive observation\n  (fail-safe wait/retry wording that never says \"stop the other process\"; when the oracle rail\n  is down it names the delivery daemon and the restart order), and a mid-life scanner death\n  (a deliberate fail-closed stop naming the restart path). An unparseable claim row refuses\n  loudly and is never overwritten automatically.\n- **Host belt.** Launchers additionally claim an exclusive per-space pidfile, published\n  ATOMICALLY and PRE-POPULATED: the claimant writes its pid to a unique temp inode, then\n  publishes it as the slot with an atomic no-overwrite `link(2)` \u2014 no create-then-write window\n  exists for a sibling to misread, and an empty slot is impossible to publish. A live holder\n  is yielded to; a provably dead holder's slot \u2014 and an empty (pre-protocol crash shape) one \u2014\n  is reclaimed exactly once; unattributable content is never stolen. A cheap belt only, never\n  the exclusion.\n\n### 13.14 Conformance (control surface)\n\nA conformant endpoint (v0.4) MUST:\n\n1. Serve only under a credential whose serve grants match its registered name, stable\n   instance id, and registered command set (publish-side grants pinned to the current\n   epoch); register its service record before serving; advance the epoch by CAS on takeover\n   and stop serving when superseded; a takeover is complete only after the \xA713.1 barrier\n   (revoke + cluster-verified eviction of the superseded credential).\n2. Answer `describe` authoritatively, intersected only against the trusted authorization view\n   (or declared-public), failing closed when that view is unavailable.\n3. Publish contract artifacts content-addressed and immutable; validate args/replies at\n   runtime within the schema profile and budgets.\n4. Reply only on the reply rail derived from the authenticated request subject; ignore\n   payload/transport reply targets; let attribution ride the reply subject.\n5. Enforce the envelope invariants (version/op/class/target/sender, catalog codes, monotonic\n   attenuation); treat the subject, never the body, as the authorization boundary; resolve\n   targets by `(alias, lifecycleUid)` against current mappings immediately before effect.\n6. Route effects by delivery class; journaled effects only from canonical accepted facts\n   through the mediated writer; fingerprint-bind ids first-wins; hold the declared horizons,\n   retentions, and floors.\n7. Validate every Cotal-owned commit through the mediated path (fencing token + unexpired\n   lease + lifecycle + epoch as applicable); lose CAS loudly.\n8. Implement advertised composites per \xA713.6: the single action vocabulary, authorization\n   linearized at acceptance, one-use resumes, generation- and scheduler-origin-validated\n   timers (a fire counts only against its own sibling `.armed`, \xA713.12) with durable\n   reconciliation, fail-closed governed traits, bounded sessions.\n9. Fail loud below the broker version floor (from the pre-auth INFO), with bounded\n   reconnects and the named pre-auth-drop diagnostic (\xA713.12); the `max_control_line` floor\n   is asserted by operator tooling (\xA713.12), never by the client, which cannot inspect it.\n10. Connect successfully while presenting the normative maximum-capability credential\n    fixture for its profile (\xA713.9), the only test that exercises the control-line bound.\n\nA conformant caller (v0.4) MUST: hold a lifecycle-pinned credential and never present another\nlifecycle's artifacts; choose ids/goalIds/nonces within the token grammar and the 1024-byte\nsubject bound and reuse ids only per the idempotency rules; declare `class` and\n`replyExpected` and honor `contract-mismatch`/`conflict`; freeze scatter expectations from the\nregistry and classify partial results; verify digests of fetched artifacts and signed\nartifacts against the anchor registry, failing closed; refuse to resolve a **describe descriptor**\nwhose `protocol.v` it does not implement (the marker rides the descriptor and the service record,\nnever the cluster document, which carries no `protocol`), and never automatically repeat a `write`\ncommand (\xA713.7) \u2014 whatever `id` the re-issue carries \u2014 except on an outcome that proves\nnon-execution (\xA713.3).\n\n### 13.15 Issued authority\n\nThe caller triple (\xA713.1) says WHO is calling. It does not say what the credential they are\ncalling with was granted, and a host that performs an effect on a caller's behalf needs that:\nthe ceiling as the issuer accepted it, immutable, and bound to the request by the broker rather\nthan by anything the caller or a mutable ledger says. This section defines that binding.\n\n**The reference.** An issued authority is `{ space, owner, actor, uid, generation }`: the\ncaller triple plus a **generation**, 32 lowercase hex characters of issuer-chosen entropy (at\nleast 128 bits). A generation is an identifier, never a bearer secret. It is chosen by the\nissuer, never by the client, and is never reused: a reference is created once or refused.\n\n**The rail.** An issued credential's request-publish and reply-subscribe rows ride the\nversioned rail (\xA713.2), with its generation pinned literally beside its triple. A request\narriving on `ep.v1` therefore carries a broker-confined generation, and a request arriving on\nthe legacy rail carries none. A body field, a header, or a policy reference supplied by the\ncaller establishes no binding.\n\n**Issuance.** Before an issued credential's material is returned, the issuer MUST persist its\n**evidence** in `cotal_issued_<space>`: `{ version: 1, ref, sources, permissions, expiresAt? }`,\nwhere `permissions` is the credential's final effective permission ceiling (publish and\nsubscribe, each an explicit `all`, `none` or `patterns` allow plus a deny list, imported from the\nnative permission fragment so an omitted list can never read as a narrow one) and `sources` are\nthe gate coordinates the issuance depends on. Issuance is `prepare \u2192 release`: the evidence and\na `prepared` attempt row are written create-only, the issuer performs its own finalization, and\nthe attempt row is CAS-advanced to `active` at the revision the prepare observed. A prepare that\nloses its create is refused; a release whose CAS loses is `aborted`. The evidence store is\nappend-only at the broker (\xA713.12: unlimited per-key history, no rollup header, no message delete,\nno purge), and the evidence and source-index rows are read as the FIRST message on their key, so a\nlater write on the same key by a holder of the issuer's bucket-wide row is inert to every\nresolver; only the attempt row advances, by CAS. The issuer also writes the\n**accepted row** (`cotal_accepted_<space>`, keyed by a token the launching party chose) naming the\nreference, create-only. A client learns which generation it was bound under by reading that one\nrow over a per-key `DIRECT.GET` grant its ceiling carries; it never trusts what it proposed or\nwhat a file says, and it refuses a row naming another owner, actor or lifecycle.\n\n**Renewal.** A renewal of an issued credential keeps its generation only when the ceiling being\nminted is byte-identical (RFC 8785) to the recorded evidence; a changed ceiling is refused as a\nrenewal and is a fresh issuance on a fresh generation, which the client adopts only through a\nnew connection. Refreshing a credential file never switches the generation of an already\nconnected transport.\n\n**Resolution.** A host that admits an effect under an issued authority resolves it: the\nevidence exists, the attempt row is `active`, the evidence is unexpired, every source is live,\nand a second read of the attempt row returns the same revision. Any other outcome refuses. The\none source shape this revision issues against is a static incarnation's credential ledger family\n(`cred.<lifecycleUid>` on `cotal_auth_<space>`), whose liveness is its issuance gate not being\n`retired`; a lifecycle terminal retires every issuance indexed to that family\n(`bysource.v1.\u2026`), so a retired incarnation's generations refuse to resolve afterwards.\n\n**User-auth issuance.** On a user-auth space the issuer of an interactive actor's `manager-caller`\nview connection is the auth service, at its callout, and the material is the user JWT the callout\nreturns. The callout issues that view when the bearer's actor-ledger row is an interactive row, and\nthe issued view carries the per-key accepted-row read beside its instance-pinned rows. It chooses\nthe generation, persists evidence whose permissions are the set it signs and whose one source is\nthat row, `{ space, bucket: \"cotal_actors_<space>\", key: \"actor.<owner>.<actor>.<lifecycleUid>\" }`,\nreleases it, and writes the accepted row, all before it returns the JWT. The accepted token is the\nfirst 32 lowercase hex characters of SHA-256 over `\"cotal.accepted.v1\\0\"` followed by the\nconnection's inbox nonce: the client chose the nonce and derives the token from it, and no token is\nread from a request body. The source is live while the auth service's actor ledger holds a row for\nthat owner and actor carrying that lifecycle UID; a revoked row, or a re-grant under another UID, is\na dead source at the next resolution. Only the auth service attests this shape; every other host\nrefuses it as a coordinate it cannot attest. A reconnect under the same nonce finds the existing\naccepted row. When the row names the same triple and the ceiling being minted is byte-identical to\nthe recorded evidence, the callout renews that generation; otherwise it refuses the connect, and the\nclient adopts a fresh generation only through a new connection under a new nonce. A managed row's\nview, the `agent` profile and every other view keep the legacy rail.\n\n**Compatibility.** A command whose semantics require the binding (this revision: `run-start`,\n\xA714.8) MUST refuse a legacy-rail request with `permission-denied` carrying the detail kind\n`ai.cotal.ep.unbound-caller-authority` naming the caller triple, never route it through the\nhost's own authority. Every other command serves both rails unchanged. Origin (that a request on\na generation-pinned subject was published by the grant holder) is a property of the grant set,\nnot of this section: no peer-held profile pairs a write with a raw stream read on one stream, and\nmediated reads remain the remedy.\n\n### 13.16 Delegated user intent\n\nA host platform that runs a `platform-control` service view MAY let that view's manager (the\nholder) execute one launch or one retirement that a signed-in user asked for, while the intent and\nthe resulting agent stay the user's. This subsection adds no exchange view, profile, holder grant or\nstanding delegation, and changes no other clause. A host that does not implement the\n`platform-control` service view, or holds no intent store, MUST refuse both requests below as\n`unimplemented`, and stock dispatch MUST refuse both kinds as `unimplemented`.\n\n**Admission.** A user admits an intent with one closed `delegated-user-intent` request on the host's\nauthenticated human route, the transport the `manager-service` typed requests use. The host MUST\nverify the user's IdP token, derive the owner from the verified subject as it does for a signed-in\nhuman, and read the named actor's ledger row fresh; the row MUST carry `spawn`. The host MUST NOT\nstore, forward or record the token, and MUST NOT read, require, synthesize or write `supervise`. The\nrequest carries the space, the assigned account public key, the user's actor, one platform control\ninstance id, a request id, and one operation: `launch` with one managed-agent enrollment target\nminus its token digest, or `retire` with one `{ owner, actor, lifecycleUid }`. An unknown field,\nincluding an owner, IdP token, scope, serve epoch or token digest, MUST be refused as `bad-request`\nwith no effect. For a launch, the host MUST read the account's platform-control assignment and that\ninstance's manager gate fresh and refuse unless the assignment is `assigned` for this account and\nnames that instance and the gate is open under the platform serve principal, and the requested scope and channel lists MUST lie within\nthe user's actor row under the managed-agent envelope rule. For a retirement, the target owner MUST\nequal the derived owner, and the target lifecycle MUST be one that the host's own record shows a\ndelegated launch on that instance produced and enrolled, for a launch target whose actor equals the\nretirement target's actor; the host MUST compare the launch's target actor, never the user actor\nthat admitted the launch. Any other lifecycle MUST be refused. The host generates\nthe intent id from at least 128 bits of entropy, never from caller input. It binds the account, the\ninstance id, the assignment's lifecycle UID and revision, the gate's process epoch (null for a\nretirement whose launching holder is gone), the one target, the user's principal `<owner>.<actor>`\nas parent, and an expiry at most 300 seconds ahead, and creates the record create-only.\n\n**Execution.** The holder executes an intent with one closed\n`manager-delegated-user-intent-execution` request on the host platform's own route for that holder;\nthe `platform-control` envelope does not carry this kind and refuses it as an unknown kind. The\nrequest names the intent id, the space, the fixed `cli` actor constant that keys the registration\nproof, the account, the assignment revision, the instance id, the manager lifecycle UID, the serve\nepoch, the registration proof, the identities, and one target: the launch target's actor with the\nSHA-256 digest of an actor token the holder generated, or the retirement's `{ owner, actor,\nlifecycleUid }`. The host MUST read the record fresh and refuse as `failed-precondition` an absent\nrecord, an admitted record past its expiry, and a consumed record unless the request is a retry of\nthe execution that consumed it (below). It MUST refuse as `permission-denied` any difference from\nthe record in account, instance id, manager lifecycle UID, assignment revision, operation, serve\nepoch or target. It MUST re-read the assignment and refuse as `permission-denied` one that is\nabsent, revoked, or differs from the record in space, account, instance id, manager lifecycle UID or\nassignment revision. It MUST re-read the gate, refuse a gate whose principal is not the platform\nserve principal, refuse a gate epoch other than the request's as `conflict`, and require the\nhost-keyed current registration proof. Every check completes before any effect. The host then MUST\nCAS the record from `admitted` to `consumed` at the revision it read, and that same write MUST pin\nthe execution: the request id, the serve epoch, the lifecycle UID (host-selected before the CAS for\na launch, the target's for a retirement), the launch's token digest or the retirement's\noperation id, and the host incarnation `{ instanceId, processEpoch }` that executes it. A lost CAS is `conflict` and nothing is enrolled or retired. Because the reads are not\nfences (\xA713.1), the host MUST repeat the assignment and gate checks for a launch after the CAS and\nbefore any effect, and on a refusal MUST compensate the launch (below) before it ends the record\n`aborted`; a change that lands after that second read is ordered after the execution. An intent\nexecutes at most once and confers nothing after it executes.\n\n**Recovery.** From the CAS on, the host owns the pinned execution, whoever presented it. It MUST\ndrive every consumed record to one outcome, `enrolled`, `retired` or `aborted`, at the pinned\nlifecycle UID, including after a restart or a lost answer. For a launch, the host's first effect\nafter the post-CAS checks MUST be the issuance activation of the alias at the pinned lifecycle UID\n(\xA713.1), before any ledger row or durable, so that UID has an active head and an open issuance gate\nbefore anything is granted under it. Every launch that ends without `enrolled` after its consuming\nCAS MUST be compensated before it is marked `aborted`, whichever flight observed the refusal,\nbecause a flight that resumes the execution cannot tell whether an earlier flight began the\nactivation: the retirement sequence below at that UID, with that UID's activation completed or\nadopted immediately before the terminal barrier. Before that activation the compensator MUST read\nthe head and the issuance gate at that UID. Once a retirement there has begun, because the head is\nretiring or retired at that UID or the gate is frozen or retired by `managedRetirementOpId` of that\nUID, the compensator MUST NOT run or adopt an activation and MUST go to the terminal barrier, which\nresumes that operation from its durable intent.\nOnly the barrier's answer that the lifecycle is retired at that UID is terminal confirmation; a\nnot-started answer MUST NOT be read as one. When that activation is refused because the alias is\nactive or retiring at another UID, the record MUST keep no outcome and the compensation MUST be\nretried. A request\nwhose request id and serve epoch, and a launch's token digest, equal the pin is a retry of that\nexecution: it passes the same checks except the consumed state, writes no second CAS, and MUST\nreceive that execution's answer. The alias stays held until the record has an outcome, and after a\nsweeper's claim until the release below.\nThe host MUST run each execution in one in-process flight keyed by the intent id, and a retry MUST\njoin that flight or read the record's outcome; a retry MUST NOT run the post-CAS checks, the\nenrollment writer or the retirement sequence itself. Every record write after the consuming CAS\nMUST be a revision-pinned CAS, and a flight MUST answer only from an outcome its own write set or\nfrom the outcome it reads after that write lost, never with material it did not commit. Recovery\nfollows the executor and sweeper roles of \xA713.7. Only the pinned incarnation is the executor, and\nonly the executor MAY run the enrollment writer for the record. Any other incarnation, including\nthe same instance after a restart advanced its process epoch, is a sweeper. A sweeper MAY act only\non a consumed record with no outcome whose executor it believes gone, because that instance's\nserving issuance gate is absent, not open or at another process epoch. It MUST first claim the\nrecord with a revision-pinned CAS that names its own incarnation and changes nothing else, and\nMAY then take only the terminal edge that removes authority: the compensation above, then\n`aborted`, for a launch, or the retirement sequence below, then `retired`, for a retirement. The\nsequence's terminal barrier freezes the issuance gate at that UID before it retires the lifecycle\n(\xA713.1), so an executor that a wrong belief left running can mint nothing there and cannot set the\noutcome. A consumed record holds its target alias `(owner, actor)` from the consuming CAS, and an\noutcome its executor writes releases it. After a sweeper's claim the alias MUST stay held after the\noutcome until the executor's own flight, having stopped before any further effect and revoked any\ngrant at the pinned UID, records the release, or until an operator releases it by hand; no door\nreleases it. Before each effect and before its outcome write, the executor MUST re-read the record\nand stop on a claim it did not write. While an alias is held, the host MUST refuse a launch\nadmission for it and MUST refuse, from either enrollment door, any enrollment of it other than the\nholding execution's own, as `failed-precondition` with no write.\n\n**Ownership.** A delegated launch MUST be enrolled under the record's owner with the record's\nparent, through the same writer, managed-agent envelope walk, lifecycle-keyed durables and\nmembership the host uses for that user's own managed-agent enrollment, with the host selecting the\nlifecycle UID. It MUST NOT be enrolled under a platform owner token or any owner other than the\nrecord's, and the manager MUST refuse material naming another owner. The holder is not on the\nagent's delegation chain and gains no ledger row, scope or grant from the launch.\n\n**Retirement.** A delegated retirement runs in order: revoke the managed grant at the target\nlifecycle UID only and complete the resumable release with that UID unchanged; close the provider\nhandle the host's runtime record holds for that UID, holding the alias while that record is\n`create-unknown`; run the auth-owned terminal barrier with `managedRetirementOpId(lifecycleUid)`\nthrough the same operation the host's managed retirement door runs; free the alias only after\nterminal confirmation. The launching holder is gone when its assignment is absent, revoked or at\nanother revision, its gate is not open, or its gate epoch is not the launch's. A retirement admitted\nwhile the launching holder is gone is bound to no live epoch, and the host MUST execute it itself\nthrough the same sequence; a retirement bound to a holder that is gone before it executes expires\nunexecuted. Once a holder's execution has consumed a record, the host MUST finish the sequence\nwhether or not the holder remains. A failed or uncertain step keeps the alias held, and a retry is\nthe same operation.\n\n**What stays.** Under the `platform-control` view itself the holder still enrolls, retires,\nvalidates and authorizes only same-owner descendants, and a `u_` principal's spawn request or admin\nauthorization against a platform manager is refused as before. A spawn the holder starts without a\nconsumed intent is not delegated and gains nothing from this subsection. A delegated agent is not\npreserved across a holder restart and is never restarted, because a restart would re-present a\nconsumed intent.\n\n### 13.17 Managed lifecycle handoff\n\nThis section is additive. It covers one case: a managed\nagent already enrolled through the \xA713.1 managed-agent enrollment operation, whose child runs where\nthe enrolling manager's filesystem is not visible (a sandbox, a container, another host).\n\n**One enrollment.** The child MUST NOT request enrollment, agent provisioning, or an enrollment\nredeem, and MUST NOT mint an actor token or a lifecycle UID. It presents the lifecycle UID the host\nselected at enrollment. A launch that needs any other UID or token is a new enrollment, not a\nhandoff.\n\n**Custody.** The raw actor token stays in the custody of the manager that generated it until that\nmanager releases it to the lifecycle's own child, and only to that child. The manager MUST NOT send\nit to the host or to any party other than the runtime transport that delivers it into that child,\nand the host's ledger keeps only its SHA-256 digest. The manager MUST NOT copy, link, or name any\nfile from its own workspace, secret store, launch material, or temporary directory into the child.\n\n**The handoff.** The manager releases one closed handoff document, `kind`\n`cotal-managed-handoff/v1`, carrying by value: `space`, `owner`, `actor`, `lifecycleUid`, `server`,\n`tlsRequired`, `authProvider`, `idp { url, issuer, audience }`, `exchangeUrl` (the enrollment's pinned\nexchange base), `sentinelCreds`, `actorToken`, `subscribe`, `allowSubscribe`, `allowPublish`, and an\noptional `policy { events: \"required\" }`. It MUST NOT carry a signing seed or key, an issuer or\ncallout record, the auth service's loopback capability, the owner-derivation secret, a provisioner,\ndeprovisioner, delivery, membership, supervisor, or other manager credential, a control token, or a\npath on the manager's filesystem. A reader MUST refuse an unknown field. The runtime delivers the\ndocument into the child as one private (0600) file named by `COTAL_MANAGED_HANDOFF_FILE`, never in\nargv or in an inherited environment value. The child's entry point MUST read the file into memory,\nremove it, and drop the variable before it does anything else, including parsing or refusing its\nown arguments, printing help, loading extensions, or refusing an unsupported runtime version, so\nevery outcome leaves no file. It MUST NOT forward the variable or the file into any process it starts.\n\n**Refusal before any plane.** The runtime passes the expected `space`, `owner`, `actor`, and\n`lifecycleUid` beside the file. The child MUST refuse, before any broker connection and before any\nexchange request, when the handoff's values differ from them or the document is malformed. A\nrefusal MUST NOT echo the document's contents.\n\n**Launch choices.** The manager MUST refuse, before enrollment, a spawn choice that only its own host\ncan honour, such as resuming a session held on that host, a working directory on its filesystem, or\na tool server it runs. Such a choice is never dropped silently.\n\n**Exchange.** The child obtains bearers only through the existing pinned HTTPS agent-bearer exchange\nat `exchangeUrl`, presenting the raw actor token. The service matches its SHA-256 digest against the\nledger as for any managed agent. Nothing about the exchange changes.\n\n**Readiness.** Readiness is observed from mesh presence of the exact principal and incarnation, as\nfor any managed launch. A runtime create whose acknowledgement is lost or ambiguous MUST leave the\nlaunch held and reported as uncertain. It MUST NOT be reported as exited without an observed exit or\nclose, and MUST NOT be retried into a second create, enrollment, or handoff for that lifecycle. A\nprovider answer that no resource exists is not an observed exit or close. A lifecycle is handed off\nat most once.\n\n**Fenced close.** The child's runtime resource is keyed by lifecycle: `cotal-` followed by the first\n32 lowercase hex characters of the SHA-256 of the UTF-8 bytes of the compact JSON array\n`[\"<space>\",\"<owner>\",\"<actor>\",\"<lifecycleUid>\"]`, with no whitespace. For space `s2420`, owner\n`u_aaaaaaaaaaaaaaaaaaaaaaaaaa`, actor `probe` and lifecycle UID `aaaaaaaaaaaaaaaaaaaaaaaaaa` the key is\n`cotal-ffa44aae523faeee4ab7689a699b392e`. A close by that key completes only when no create for that\nlifecycle can still materialize: the create was answered before the close, or the close fences the\nkey so a later create is refused. Until then the close stays pending and the launch is not exited.\nA runtime MAY issue the create as a durable provider operation keyed by that key and close the\nresource through the identifier the provider returned in its authenticated response to that create,\nkept in a durable record the host can read without the enrolling manager. Only that response binds\nan identifier to the key: an identifier derived from the key, or found by name or by listing\nresources, MUST NOT be closed or adopted as the lifecycle's resource. While the create's response is\nunknown, no identifier is bound, the launch stays held as under Readiness, and a close completes only\nas above.\n\n**Retirement.** A handed-off lifecycle retires only through the existing managed path, in this order:\nthe host-owned prepare-retirement for the UID-exact target with the operation id\n`managedRetirementOpId(lifecycleUid)`; the fenced close of the child's runtime resource through the\nhandle known for that lifecycle; then the auth-owned terminal barrier with the same operation id.\nAfter the enrolling manager is gone, the host runs the same three steps itself, ending at the managed\nretirement door. There is no participant stop kind and no second retirement protocol, and no runtime\nclose or adopt may be keyed on the agent name alone. A runtime MAY host a handed-off child only where\nthe host can perform the fenced close by lifecycle without the enrolling manager. A failed or\nuncertain step keeps the alias held. A manager preservation cut that holds a handed-off lifecycle is\nrefused before any child stops, because a later manager never resumes it, and a manager stop after\na refused cut retires that lifecycle through these steps.\n\n**Owner form.** A handoff serves whatever owner the enrollment returned. It neither requires nor\nexcludes any owner form.\n\n---\n\n## 14. Workflow runs (v0.5)\n\nA **workflow run** is one execution of a program in the Cotal workflow language, hosted by a\n**driver** (an endpoint, in the reference deployment the manager daemon) that performs the\nprogram's effects against the mesh and records every one of them in a per-run **step journal**.\nThis section defines the run's wire footprint: the record it is described by, the stream its\njournal travels on, the records its effects file, and the grants its driver holds. The\nlanguage, the journal entry, and the rules of resume, migration and fork are defined in\n[`spec/cotal-lang.md`](spec/cotal-lang.md), which this section incorporates by reference: an\nimplementation of this section MUST implement that document.\n\n### 14.1 Roles and identity\n\nThe **driver** is the one principal that executes a run: it validates and runs the program, calls\nthe effect handler, appends to the journal, and writes the run's records. It is hosted by an\nendpoint, and every \xA714 key leads with that `<endpoint>` token so a per-endpoint enumeration and a\nretirement drain (\xA713.1) both work by prefix. A **run id** (`<runId>`, an id token, \xA713.2) is minted\nby the driver when the run starts, is never caller-supplied, and is **never reused**: re-running a\nprogram from part of a run's history is a **fork**, and a fork is a new run under a new id whose\nrecord names its parent (\xA714.3). A run has exactly one **authoritative appender** at a time; \xA714.4\nis what makes that true.\n\nA user-auth run's durable actions MUST use the owner established by its authenticated admission.\nThe trusted host derives the run-stable actor and lifecycle uid from the run id and retains that\nowner on resume. Grant construction and effect dispatch MUST use the same triple. A supplied\nowner token is not admission evidence. The existing static/local path retains its `local` owner.\nThese identity rules do not authorize exporting host mediator or operator credentials to a driver.\n\n### 14.2 The language and its version\n\nPrograms, values, primitives, the step key grammar, the input hash, the request id and the entry\nschema are those of [`spec/cotal-lang.md`](spec/cotal-lang.md). The language carries a\n**`languageVersion`**, bumped when a revision changes what a program means (its PRNG, a builtin,\nnumeric behaviour, walker scheduling) and deliberately not the package or wire version; a run pins\nthe version it started under (\xA714.3) and a resume under another version is refused\n(`spec/cotal-lang.md` \xA78.4). A wire revision of this document therefore never invalidates an open\nrun, and a language revision never requires one here.\n\n### 14.3 The run record\n\nA run is described by the `run` record kind (\xA713.7): `run.<endpoint>.<runId>`, `.spec`/`.status`\nsplit, mediated, written by the driver's commit path only.\n\n- **Spec** (create-only, decided once): `{ v: 1, run, pins, createdAt, forkedFrom? }`. `pins` is\n  the **resolved pin set** the run started under, `{ seed, startedAt, yieldEvery, stepBudget,\n  effectCeiling, languageVersion }` (`spec/cotal-lang.md` \xA78.3): every one selects which effects run,\n  so a resume MUST read them back and bind to them, and MUST refuse a caller value that differs.\n  `startedAt` is the run's **logical epoch**, and a resuming host's own clock never moves a\n  replayed program. The RESOLVED value is pinned, never the default: a default is a property of the\n  interpreter, and the interpreter is the thing that may have changed between attempts. A spec that\n  already exists MUST refuse a second start under the same id. A fork (`spec/cotal-lang.md` \xA711.3)\n  is a new run with its own id and its own spec, and the child's spec names its lineage:\n  `forkedFrom` is `{ run, step }`, the parent run and the step key the cut excluded, written with\n  the spec and absent on a run started fresh. Absence reads as \"lineage unknown\" (a child recorded\n  before the field existed), never as \"not a fork\". A later revision that adds a field to the spec\n  half does so as its own binding revision, never by rewriting a spec that exists.\n- **Status** (last-value-wins, CAS-written): `{ v: 1, observedSpecRevision, state, holder, epoch,\n  fencingToken, journalHigh, at }`. `state` is one of `running`, `released`, `completed`, `failed`,\n  and `released` and `failed` are different facts: a failed program has a result and the journal has\n  it, a released run has none, because its driver stopped holding it (`spec/cotal-lang.md` \xA79.2,\n  L5012). `holder`, `epoch` and `fencingToken` name the driver that holds the run and the lease\n  (\xA713.6 work pool) it holds it under. `journalHigh` is the highest journal ordinal (\xA714.4) the run\n  is KNOWN to have reached, written at each activation and after each append the driver makes\n  while the run is `running`, before that append resolves to the interpreter: it is the one anchor\n  OUTSIDE the journal, so a replay whose last ordinal is below it has lost records from the\n  journal's tail, which nothing inside the journal can see, and the driver MUST refuse to resume it.\n  Interior loss is the journal's own ordinal chain's.\n\n### 14.4 The step journal on the wire\n\nThe journal of a run is carried by the per-space **`WFJ_<space>` stream** (\xA713.12) on **one subject\nper run**, `cotal.<space>.wfj.<runId>`. An implementation MUST create the stream with limits\nretention, file storage, no `max_age`, and `allow_direct=false`, and MUST NOT let any removal cause\nevict a live run's prefix (\xA713.12 retention floor). Retirement of a run's journal is by subject\npurge.\n\nEvery message on the subject is one **journal record**, JSON, one of two kinds. Both envelopes are\nCLOSED: a reader MUST refuse a record that carries a field outside the shape below, and MUST refuse\nan unknown `kind`, because a journal is replayed by whoever holds the run next and a field one\nwriter meant and another ignores is a divergence nothing would name:\n\n- **activation**: `{ v: 1, kind: \"activation\", run, n, holder, fencingToken, epoch, replayedTo, at }`,\n  the successor's first act, and the only record the runtime layer writes that is not a step.\n- **step**: `{ v: 1, kind: \"step\", run, n, at, entry }`, where `entry` is a language journal entry\n  (`spec/cotal-lang.md` \xA710.1) carried verbatim: the wire layer MUST NOT read inside it. A step is\n  appended TWICE, once `pending` before its effect is dispatched and once settled after; a reader\n  folds by the entry's key and the last record wins.\n\n`n` is the record's **ordinal** in the run's journal, from 0, and a replay MUST require\n`records[i].n === i`: the chain is the only check that sees a record removed from the middle of a\nsubject, since counting cannot and no anchor at the front can. A writer MUST stamp `run` with the run\nthe subject names; its grant covers exactly one subject (\xA714.6), which is what enforces it. A reader\nSHOULD refuse a record whose `run` names another run; the reference reader relies on the grant and\ndoes not re-check it.\n\n**The activation barrier.** A run has exactly one authoritative appender at a time, and the STREAM\nis the acceptor: every append MUST carry `Nats-Expected-Last-Subject-Sequence` for the run's own\nsubject, so a publish lands only if the subject is exactly where the publisher believed it was, and\nthere is no read-then-publish window because there is no read. Takeover is replay-then-activate:\n\n1. The successor replays the run subject from the beginning, through a **per-takeover replay\n   durable** it creates on the stream (`wfj_<runId>_<takeoverId>`, filtered to the run's subject,\n   explicit ack, deliver-all) and deletes when done. `<takeoverId>` is an id token (\xA713.2) minted by\n   whoever hands the driver its lease and its journal grant (\xA714.6), one per takeover of a run and\n   never reused for that run; the driver does not choose it, because a consumer name is one subject\n   token that no grant pattern covers in part, so it has to be known when the grant is minted. The\n   last replayed record's stream sequence is the only authoritative head there is (`STREAM.INFO`'s\n   `last_seq` is stream-wide, and its subject filter answers counts, not sequences).\n2. Its first act is an **activation record** appended at that expected sequence, and it drives\n   nothing before that record lands. Its authority is checked against the activation the journal\n   already holds: a lower `fencingToken` is refused (stale lease); an equal token is refused unless\n   `holder` AND `epoch` are the same (one process picking its own run back up); a higher token\n   activates.\n3. Once the activation lands the subject has advanced, so any append still in flight from the\n   superseded driver carries a stale expectation and the server rejects it.\n\nTwo CAS refusals are two different states and MUST NOT be conflated. A refused ACTIVATION means \"my\nreplay is stale\": the successor has driven nothing, the records that beat it are more prefix, and it\nMAY re-replay and activate again while it still holds the lease. A refused APPEND after an\nactivation that won means \"someone else activated\": that driver IS superseded, MUST stop, and MUST\nNOT refresh the sequence and retry, because a retry at the new head is the defect the barrier\nexists to prevent. A driver publishes one entry at a time from one serial queue per run and\nadvances its head only from each acknowledgement; once the bytes have gone out, any outcome without\none poisons the queue and nothing behind it reaches the wire (a record refused before it is sent,\nfor example one that cannot be serialized, fails only itself).\n\nThe journal is a language artifact, and its contents are decided by the language: a driver MUST\nawait the durable append of a `pending` entry before dispatching the effect it names, MUST settle\nthe entry from the handler's outcome, and MUST keep the settling append outside the handler's\nfailure domain, so a refused append is a durability failure (L5010) that stops the run and is never\nrecorded as the effect's failure (`spec/cotal-lang.md` \xA710.5). A cancelling scope's `cancel.issued`\nrecords whether the driver has discharged the intent against the world; the record states the\nintent and its discharge, and how a driver disposes of a losing arm's live work is a driver policy\nthis revision does not fix.\n\n### 14.5 Answers, notices, migrations\n\nThree record kinds carry the payloads a run's effects file (\xA713.7 for the grammar and the\nsentences that defend each shape). Their derived id tokens all take one form: **the unpadded\nbase64url of the SHA-256 over the strict RFC 8785 canonical JSON of the named object, 43\ncharacters**, which is an id token by construction. The reference implementation's canonicalizer is the one\n\xA713.7's `*Digest` fields use.\n\n- **`answer`**, `answer.<endpoint>.<token>.<answerId>`, atomic, create-only: `{ v: 1, token,\n  answerId, value?, artifact?, by, at }`, filed BEFORE the checkpoint token is presented; the\n  one-use settle fact (\xA713.6) then NAMES the id it accepted. For a checkpoint a run performed the\n  `answerId` on a `resumed` settle is REQUIRED (\xA713.6 leaves it optional for other checkpoints): a\n  run's handler reads the answer under the id the settle names, never by looking for \"the answer to\n  this token\", and refuses a resumed settle that names none. `answerId` = the digest id of\n  `{ token, by, value: value ?? null, artifact: artifact ?? null }`, so a retry of the same answer\n  lands on the same key with the same bytes and two different answers race on the settle, which is\n  what the settle is for. `by` is the answerer as the run's own authorization knows them, never the\n  presenting principal (the driver, for every answer) and never a field in the answer request. A\n  baseline managed seat reaches the answer door only through the self-targeted row above, after the\n  manager has matched its exact caller incarnation to the pending relay for this open pause.\n  An **amendment** is an answer filed after the pause settled: same key grammar under the token\n  the pause settled under, with `supersedes` naming the `answerId` the settle accepted. It is filed\n  through the same door and credential pinning as an answer, and nothing is presented, so the pause\n  stays settled, the one-use settle is untouched, and the run never reads the record. Its\n  `answerId` is minted fresh for each filing (32 random bytes, base64url, the first 43 characters)\n  and is never derived from its content: a participant who returns to an earlier position files\n  what an earlier filing said, and a content id would make the create-only write take it for a\n  retry of that filing and record nothing. A step that is still open, or that settled\n  without accepting an answer, has nothing to amend and is refused. The run surface lists a settled\n  step's amendments beside its accepted answer in the order the records bucket committed them (each\n  record's revision); `at` is the filer's clock and never decides the order. The last one listed is\n  the step's current recorded position, and the accepted answer remains what the program acted on.\n- A held `once` step (`spec/cotal-lang.md` \xA77.8) is answered like a checkpoint, addressed by its\n  step key; the driver presents the hold id (`spec/cotal-lang.md` \xA77.8) as the token, whatever kind\n  the step is, and reads the step's accepted answer and amendments under the same id once it\n  settles. The run's pause authority covers that id only while the step is pending with its hold\n  bound.\n- **`notice`**, `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>`, split: spec `{ v: 1, run,\n  step, addressee, fact, at }` (create-only; `fact` is the language's bounded decision record and\n  is checked against its bound BEFORE any record is written), status `{ v: 1, consumedAt, by,\n  observedSpecRevision }` (create-only: the consumption is established once, by the turn that\n  carried it). `addresseeId` = the digest id of `{ agent }` (the addressee's name); `noticeId` = the\n  digest id of `{ requestId, addressee }`, where `requestId` is the `notify` step's request id, so\n  one call to N agents files N notices and a re-run after a crash lands on the same ones. A driver\n  that performs the addressee's turns MUST render an unconsumed notice ahead of its next turn and\n  MUST NOT deliver it as a channel message. The reference driver performs that rendering: its turn\n  plane is durable (`spec/cotal-lang.md` \xA76.5), and a relayed turn carries the addressee's\n  unconsumed notices as its rendered context and marks them consumed with the turn's outcome.\n- **`migration`**, `migration.<endpoint>.<runId>.<migrationId>`, split: spec `{ v: 1, run,\n  fromHash?, toHash, at, consumedThrough, orphans[], overrides[], actor }` (create-only), status\n  `{ v: 1, appliedAt, by, observedSpecRevision }` (create-only). `migrationId` = the digest id of the\n  spec without `at`, so a dry walk re-run after a crash files no second migration for one decision.\n  `orphans[]` is `{ step, kind, verdict, code? }` per journal entry the new source no longer reaches,\n  with the verdicts and refusals of `spec/cotal-lang.md` \xA711.2; `fromHash` is the caller's claim\n  and is absent when not supplied, because the run record carries no program hash to verify it\n  against. A migration never rewrites a journal.\n\n### 14.6 Driver grants\n\nGrants are DERIVED (\xA713.7, \xA713.9), and a run driver's are minted **per run and per takeover\nattempt**, never per space:\n\n- publish on exactly `cotal.<space>.wfj.<runId>`;\n- create, bind (info, next, ack) and **delete** its own replay durable `wfj_<runId>_<takeoverId>`\n  on `WFJ_<space>`, named per takeover because a durable remembers how far it delivered and a\n  successor needs the prefix from the top, and because a consumer name is one subject token that no\n  pattern covers in part, so the takeover id belongs to the credential;\n- and, as the standing per-kind mediated writer path of \xA713.9 rather than anything minted per run,\n  the commit path for the `run`, `answer`, `notice` and `migration` keys of its own endpoint.\n\nThere is no wildcard form of any of these, on purpose: a space-wide `wfj.>` publish would let one\nrun's driver append to another run's journal, which is not a read leak but a corruption (the other\nrun would replay a step it never took), and the barrier's premise is exactly one authoritative\nappender per subject. The provisioner holds `STREAM.CREATE`/`STREAM.INFO` on `WFJ_<space>` and\ncreates it at space setup; agents never hold `STREAM.CREATE` (\xA713.12).\n\n### 14.7 Conformance (workflow runs)\n\nA conformant driver (v0.5) MUST:\n\n1. Validate a program against `spec/cotal-lang.md` before running it, and run it with the language\n   semantics that document defines, under a pin set resolved once and read back on every resume.\n2. Mint run ids itself and never reuse one; a fork is a new run under a new id.\n3. Append every journal record on the run's own subject under the subject-sequence fence, replay\n   before activating, activate under an authorized lease tuple, stop on a refused append after\n   activation, and never retry an append at a refreshed head.\n4. Write a `pending` entry durably before dispatching its effect, settle from the handler's outcome,\n   and treat a refused append as a durability failure that stops the run rather than as the effect's\n   outcome.\n5. Require the ordinal chain and the run id on replay, refuse a replay below the recorded\n   `journalHigh`, and refuse to resume without the recorded pins or under a different language\n   version.\n6. File answers, notices and migrations under their derived ids, create-only, and render notices\n   ahead of the addressee's next turn rather than as channel messages.\n7. Hold only the per-run, per-takeover grant family of \xA714.6.\n8. Admit every run under \xA714.8 before launching it, check every channel effect against the\n   admitted ceiling and the current revocation state, and never continue a run whose admission is\n   missing, unreadable, mismatched or revoked.\n\n### 14.8 Run admission\n\nA hosted run performs channel effects on a caller's behalf. What it may do in channels is the\n**admitted ceiling**: the caller's issued permission ceiling (\xA713.15) as resolved at admission,\nrecorded once per run, and never widened afterwards.\n\n**The record.** Before the driver is launched and before a successful start reply, the hosting\nendpoint writes `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>`, create-only,\nunder a one-shot `run-admitter` credential pinned to that one run:\n`{ version: 1, space, endpoint, runId, instanceId, caller, ceiling, provenance, admittedAt }`.\nThe store is write-once per key at the broker (\xA713.12: one message per subject under `discard:\nnew`, no rollup header, no message delete, no purge), so the admitter's own key row can neither\nreplace the admission nor remove it once written, and a marker, once written, stays.\n`caller` is the admitting request's broker-authenticated caller, generation included; `ceiling`\nis the resolved evidence's `permissions`, verbatim; `provenance` is\n`{ kind: \"issued\", ref, resolvedRevision }` for a hosted admission or\n`{ kind: \"operator\", by, reason }` for a local one (below). A run-start arriving on the legacy\nrail is refused as \xA713.15 says. On an open mesh, which issues no authority, the endpoint hosts no\nrun. The driver holds no row on this store; the mediator and operator profiles hold its leader-\nserved read only.\n\n**Enforcement.** The trusted host re-reads the admission, leader-served, before every channel\neffect: opening a wait, each fetch on it, each re-read of a recorded match, and a conclave's\nchannel writes. A concrete channel is checked against the ceiling with the \xA73 matcher: a\npublish requires `chat.<owner>.<actor>.<channel>` under the caller's own triple to be allowed by\n`ceiling.publish`; a read requires every subject `chat.*.*.<channel>` matches to be covered by\n`ceiling.subscribe`. Deny wins; an explicit `none` is deny-all; a generated channel name is\nchecked after it is derived and no wildcard is invented to admit it. `notify` writes agent-\naddressed notices and is not channel publication; spawn and turn keep their separately checked\ndelegated authority.\n\n**Revocation.** `revoked.v1.<endpoint>.<runId>` is the run's revocation marker: create-only,\nidempotent, written under the same `run-admitter` profile, never removed. A revoked run performs\nno further channel effect, its open waits refuse at their next fetch (the linearization point is\nthe leader-served read the host makes before returning any channel bytes), and no resume,\ntakeover or boot reconcile continues it. Revocation authorizes no new resource and no cleanup\nbeyond what the run's own journal already justifies. Caller disconnect or credential expiry after\nadmission does not revoke a run.\n\n**Resume, fork, local, restore.** A resume, takeover or reconcile continues under the ORIGINAL\nadmission and the current marker; the resuming caller's own authority is not consulted and cannot\nwiden it; a run with no admission stays parked, named in the host's log. A fork is a new run and\nneeds its own admission under the forking caller. A local drive (`cotal run start --local`) is\nadmitted from operator evidence named on the command line (the read and publish channel sets, or\n`none`), never from the host's own scope. The admission and revocation stores are retained with\nthe run, program and journal state they authorize; a restore that lacks them recreates them empty,\nand no run is taken back under authority the host cannot read.\n\n**User-auth runs.** A user-auth run is hosted by a signerless participant manager, and its issuing\nhost writes the admission. The issuing host admits a run-start whose caller has a derived user owner\nonly when that owner is the manager's registered owner, the owner whose `supervise` grant registered\nthe instance, so every user-admitted run on a participant manager belongs to that one owner. A\ncaller-requested resume and every principal answer or amendment ride the versioned rail. The manager\nforwards the request subject it served with the attempt or operator issuance it asks for, and the\nissuing host re-parses that subject, requires a user caller's owner to be the run's admitted owner\nfor a resume and the registered owner for an answer, resolves the caller's own issuance as live, and\nrequires its publish ceiling to permit that subject. The issuing host subscribes to those resume and\nanswer request subjects itself and never replies on them, and it issues for a forwarded subject only\nwhen it observed a caller publish that request and has not issued for it before, so a manager cannot\nforward a request its caller never sent. It reads what that request's envelope asked for and issues\nonly that: a resume attempt for the run its `runId` names, and an answering issuance for the\nendpoint the answer names, the manager's own when it names none, that amends when the request set\n`amend: true` and answers when it did not. When the request carries a `bind` (\xA713.2) naming\nanother instance or epoch than the manager's current registration, it issues nothing, since that\nmanager refuses the request unrun. It issues nothing either for a request whose `class` or pinned\n`inputDigest` and `outputDigest` differ from the command's declaration in the manager's registered\ncluster (\xA713.7), which that manager also refuses unrun. An answering operator issuance always carries\nthe served subject. An amendment's issuance marks its pause with `amend: true`, and the issuing host\nthen requires that pause settled `resumed` with an accepted answer instead of waiting. A legacy-rail\nanswer is accepted only from a\nmanaged seat of that owner whose actor-ledger row is live, on the relay path of \xA714.5. A boot\nreconcile forwards no subject and continues under the original admission. This revision hosts no\nuser-auth run on the signer-holding host's own manager.\n\n---\n\n## Appendix A: Reference implementation map\n\n| Spec section | Source |\n| --- | --- |\n| \xA72 Identity | `packages/core/src/identity.ts` |\n| \xA73 Subjects | `packages/core/src/subjects.ts` |\n| \xA75 Envelopes, \xA76 Presence, \xA77 Channels | `packages/core/src/types.ts` |\n| \xA78 Streams | `packages/core/src/streams.ts`, `packages/core/src/endpoint.ts` |\n| \xA79 Security | `packages/core/src/provision.ts` |\n| \xA710 Join link | `packages/core/src/link.ts` |\n| \xA713 Endpoint control surface | `packages/core/src/` (endpoint rails, envelope, contracts; lands with the control-surface campaign) |\n| \xA713.15 Issued authority | `packages/core/src/issued-authority.ts` (reference, evidence store, accepted row), `issuer-session.ts`, `endpoint-subjects.ts` / `endpoint-grants.ts` (the versioned rail) |\n| \xA714 Workflow runs, [`spec/cotal-lang.md`](spec/cotal-lang.md) | `packages/lang/src/` (the language, journal, keys, pins), `packages/core/src/run-record.ts`, `run-journal.ts`, `checkpoint-answer.ts`, `run-notice.ts`, `run-migration.ts`, `endpoint-binding.ts` (WFJ, grants), `run-admission.ts` (\xA714.8), `implementations/runtime/src/` (driver, migrate, fork), `implementations/manager/src/run-hosting.ts` (admission) |\n\n## Appendix B: Profile ACLs\n\nThis appendix is normative for the NATS binding. *(The operator-facing summary of these\ngrants is [docs/identity-and-auth.md](docs/identity-and-auth.md).)* Names below use these\nplaceholders:\n\n- `P = cotal.<space>`\n- `CHAT = CHAT_<space>`, `DM = DM_<space>`, `TASK = TASK_<space>`\n- `DLV = <Plane-3 per-member delivery stream>`; `INBOX = <mixed pre-auth fan-out stream>` (the durable-backstop handoff, \xA78): fan-out writes `INBOX` (`dinbox.<owner>.<actor>.<uid>`; lifecycle-bound from v0.4, so an inactive-gap or predecessor entry can never migrate to a same-name successor), the trusted reader re-authorizes and transfers to `DLV` (`dlv.<owner>.<actor>.<uid>`, same binding), and the agent binds its own `DLV` DELIVER consumer (filter pinned to its own triple). An agent gets **no** grant on `INBOX` (the mixed pre-auth store).\n- `KV = KV_cotal_presence_<space>`\n- `CHKV = KV_cotal_channels_<space>`; `DLVKV = <delivery lease/readiness KV>`\n- `MEMKV = KV_cotal_membership_<space>` (the derived channel-membership feed, \xA78)\n- `<owner>.<actor> = the authenticated principal` (\xA72): `<owner>` and `<actor>` are its two tokens; the dot-form is the wire/KV form, the dash-form `<owner>-<actor>` is the durable-name form\n- `connId = the authenticated connection id` (the connection nkey in static mode; the client-chosen nonce in user mode); distinct from the principal, and keys ONLY the reply inbox\n- `role = authenticated agent role`\n- `chatHistD = chathist_<owner>-<actor>-<uid>`, `dmD = dm_<owner>-<actor>-<uid>`, `dlvD = dlv_<owner>-<actor>-<uid>`, `svcD = svc_<role>` (per-instance durables are lifecycle-scoped from v0.4: keyed on the dash-form + lifecycle UID, \xA78/\xA713.1; `svcD` stays role-scoped)\n- `inbox = _INBOX_<connId>.>`\n\nGrouped placeholders such as `<CHAT|DM|TASK>` mean one concrete subject per listed token.\n\n### Agent\n\n`sub.allow`:\n\n- `inbox`\n- `P.live.<manager|delivery>.<owner>.<actor>.>` (replies to its own plane liveness probes, \xA76.1)\n- `P.ep.reply.*.*.*.<owner>.<actor>.<uid>.*` (exact arity; the agent's own endpoint reply rail: every endpoint's replies to THIS caller triple + nonce, \xA713.2; replies never ride the per-connection `inbox`)\n- `P.epe.\u2026`; the exact fully-qualified event subtrees of every minted read capability\n  (\xA713.9 event-read row), incl. the caller's own per-goal subtree\n  `P.epe.*.*.*.goal.<owner>.<actor>.<uid>.>`; the live tail of watch, granted per\n  capability, none by default\n- `P.chat.*.*.<ch>` for every `allowSubscribe` channel, the **live read boundary**: native core-sub join/leave is a `sub.allow`-bounded subscribe to this subject (wildcard sender owner+actor), so an agent whose ACL permits a channel joins it alone with no manager. Wildcards preserved (e.g. `P.chat.*.*.team.>` for `allowSubscribe: team.>`); a `team.>` grant matches strictly deeper channels, not the bare `team`; a `>` grant is read-all chat in the space on credential compromise\n\n`pub.allow`:\n\n- `P.chat.<owner>.<actor>.<ch>` for every `allowPublish` channel (post ACL; none by default)\n- `P.inst.*.*.<owner>.<actor>` (DM any recipient, forge-locked to me as sender)\n- `P.svc.*.<owner>.<actor>` (anycast any role, as me)\n- `P.live.<manager|delivery>.<owner>.<actor>` (plane liveness probe, as me, \xA76.1; the agent holds no `live` serve filter)\n- endpoint request forms per minted capability (\xA713.9): every agent gets the baseline set\n  (`describe` on all endpoints; the delivery endpoint's durable join/leave/list commands;\n  self-targeted manager commands with authz-mode `self`, including `run-answer`, which the manager\n  narrows to an ask or escalation pending on that exact seat incarnation); the `spawn` capability adds the\n  manager endpoint's lifecycle commands with authz-mode `owner`; `child`/`ledger` forms and\n  wider target patterns only per explicitly minted capability. The caller triple\n  `<owner>.<actor>.<uid>` is pinned in every granted form\n- control-surface durable reads (contract artifacts, decisions, goal results, receipts,\n  event catch-up, record reads): **NO raw JetStream read grant of any kind**, no\n  `DIRECT.GET`, no consumer `CREATE`, no bind-only `MSG.NEXT`/`ACK`, on `EPC`/`EPF`/`EPE`/the\n  records KV. Per \xA713.9 \"Mediated reads\", every JetStream read delivers stored bytes to a\n  caller-chosen destination the broker does not confine (push `deliver_subject`, pull\n  `MSG.NEXT` reply, `DIRECT.GET` reply are the same vector), so an untrusted caller holds none\n  of them. The caller reads through the trusted read mediator via a read command (an endpoint\n  request form, above) and receives its own caller-scoped facts over its reply rail\n  `P.ep.reply.*.*.*.<owner>.<actor>.<uid>.*` (already in `sub.allow`); the mediator owns the\n  reader consumers and re-authorizes each read. Live event progress is the caller's own core\n  subscription to granted `P.epe.\u2026` subtrees within `allowSubscribe` (bytes land only on its\n  own subscription, never a caller-chosen subject)\n- `$JS.API.INFO`\n- `$JS.API.STREAM.INFO.<CHAT|KV|CHKV|DLVKV>`: CHAT plus the world-readable presence/registry/lease KVs only; **not** DM/DLV/EPC (an agent reaches those by name \u2014 its own pre-created `dmD`/`dlvD`, or a subject-scoped `DIRECT.GET` on EPC \u2014 and `subjects_filter` is a request-body field, so INFO there would only leak inbox/delivery subject metadata). `TASK` rides the `role` gate below, not this row.\n- `$JS.API.CONSUMER.CREATE.<CHAT>.<chatHistD>.<P.chat.*.*.<ch>>` for every `allowSubscribe` channel (history reads; the single filter the server pins to the body, the agent's only CHAT consumer create. The live tail is the core `sub.allow` subscription above, not a JetStream consumer)\n- `$JS.API.CONSUMER.INFO.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.DELETE.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.INFO.<DM>.<dmD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DM>.<dmD>`\n- `$JS.ACK.<DM>.<dmD>.>` (DM inbox: BIND-ONLY its own pre-created `dmD`, never create)\n- `$JS.API.CONSUMER.INFO.<DLV>.<dlvD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DLV>.<dlvD>`\n- `$JS.ACK.<DLV>.<dlvD>.>`, the **durable backstop**: BIND-ONLY its own pre-created per-member DELIVER consumer `dlvD` (the trusted reader's re-authorized handoff, \xA78). The agent holds NO grant on the mixed pre-auth `INBOX` fan-out stream.\n- `$JS.API.CONSUMER.CREATE.<KV>.>`\n- `$JS.API.CONSUMER.INFO.<KV>.>`\n- `$JS.FC.>`\n- `$KV.cotal_presence_<space>.<owner>.<actor>`\n- `$JS.API.STREAM.MSG.GET.<CHKV>`\n- `$JS.API.CONSUMER.CREATE.<CHKV>.>`\n- `$JS.API.CONSUMER.INFO.<CHKV>.>`\n- `$JS.API.STREAM.MSG.GET.<DLVKV>` (delivery lease/readiness; read-only, non-gating)\n- if `role` is set: `$JS.API.STREAM.INFO.<TASK>`, `$JS.API.CONSUMER.INFO.<TASK>.<svcD>`,\n  `$JS.API.CONSUMER.MSG.NEXT.<TASK>.<svcD>`, `$JS.ACK.<TASK>.<svcD>.>` (stream-level state is\n  gated with the bind grants, so a role-less agent holds nothing at all on `TASK`)\n\n`pub.deny` (the agent binds these consumers, never creates them; its only consumer-create grant is the pinned per-channel `chatHistD` history create):\n\n- `$JS.API.CONSUMER.CREATE.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.CREATE.<TASK>`\n- `$JS.API.CONSUMER.CREATE.<TASK>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<TASK>.>`\n- `$JS.API.CONSUMER.CREATE.<DLV>`\n- `$JS.API.CONSUMER.CREATE.<DLV>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<DLV>.>`\n\nA bare/multi-filter consumer create on `CHAT` is **not** explicitly denied (that would also deny the\npinned `chatHistD` create the agent needs), so it is default-denied (the agent holds no such allow),\nleaving the single-filter history consumer above as the agent's only CHAT consumer.\n\n### Observer\n\n`sub.allow`:\n\n- `P.chat.>`\n- `inbox`\n\nApplication publish is denied. `pub.allow` contains only read/control verbs needed to read\nCHAT history, presence, and channel registry:\n\n- `$JS.API.INFO`\n- `$JS.API.STREAM.INFO.<CHAT>`\n- `$JS.API.STREAM.INFO.<KV>`\n- `$JS.API.CONSUMER.CREATE.<CHAT>`\n- `$JS.API.CONSUMER.CREATE.<CHAT>.>`\n- `$JS.API.CONSUMER.INFO.<CHAT>.>`\n- `$JS.API.CONSUMER.MSG.NEXT.<CHAT>.>`\n- `$JS.ACK.<CHAT>.>`\n- `$JS.API.CONSUMER.CREATE.<KV>.>`\n- `$JS.API.CONSUMER.INFO.<KV>.>`\n- `$JS.API.STREAM.INFO.<CHKV>`\n- `$JS.API.STREAM.MSG.GET.<CHKV>`\n- `$JS.API.CONSUMER.CREATE.<CHKV>.>`\n- `$JS.API.CONSUMER.INFO.<CHKV>.>`\n- `$JS.API.STREAM.INFO.<MEMKV>`\n- `$JS.API.STREAM.MSG.GET.<MEMKV>`\n- `$JS.API.CONSUMER.CREATE.<MEMKV>.>`\n- `$JS.API.CONSUMER.INFO.<MEMKV>.>`\n- `$JS.API.STREAM.INFO.<DLVKV>`\n- `$JS.API.STREAM.MSG.GET.<DLVKV>`\n- `$JS.FC.>`\n\nThe membership feed (`MEMKV`) is read-only for this profile and, per \xA78's membership-feed\nparagraph, display-only and not part of the contract a client must implement.\n\nThe profile holds **no** `CONSUMER.DELETE` on any of these streams. Its consumers are client-named\nordered consumers (`oc_<nuid>_<serial>`, renamed on every rebuild), so the only expressible delete\ngrant is stream-wide, and a stream-wide grant lets one holder delete another principal's watch\ncursors and the delivery daemon's `fanout` durable. The broker removes these consumers at their\ninactive threshold (five minutes after the last interest), and a client MUST treat a refused delete\nof its own ephemeral consumer as that outcome rather than as a failure.\n\n### Admin\n\nAdmin has observer grants, with `sub.allow = [P.chat.>, P.inst.>, P.svc.>, inbox]`, the\ngod-view is the **messaging plane only**, enumerated: it deliberately excludes `P.ep.>`,\n`P.epe.>`, `P.epf.>`, `P.epj.>`, `P.ept.>`, `P.epr.>`, `P.epw.>`, `P.eps.>`, and `P.epc.>`\n(a space-wide `P.>` would plain-subscribe every `ep.one` request rail, collecting reply\nnonces the queue-qualified-only rule exists to protect, and every core-only session\nframe; \xA713.2, \xA713.11). Plus DM history read grants:\n\n- `$JS.API.STREAM.INFO.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.INFO.<DM>.>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DM>.>`\n- `$JS.ACK.<DM>.>`\n\nAdmin still has no application publish grants.\n\n### Scoped host profiles (formerly `manager`)\n\nThere is **no allow-all credential**. The privileged host duties are split into scoped,\nsingle-function profiles, each granting only the verbs its function needs and none other:\n\n- `provisioner`: pre-creates the per-instance lifecycle-scoped durables (`dm_\u2026-<uid>`,\n  `svc_\u2026`, the per-member `dlv_\u2026-<uid>` handoff) AND the trusted control-surface consumers of\n  the \xA713.9 matrix; `poolD`, `effD`, and the read mediator's reader durables\n  (`decD`/`goalD`/`eveD-n`/`recD-n`, owned by the mediator, never by callers, \xA713.9\n  \"Mediated reads\"), all PULL with exact full-tail filters; and mints scoped credentials;\n  ephemeral onboarding authority.\n- `deprovisioner`: target-pinned teardown of ONE retired lifecycle's footprint, minted per\n  teardown with the target's `(principal, lifecycleUid)` in every exact-name grant; it can\n  delete only lifecycle-keyed names, so it structurally cannot reach a same-name successor\n  (\xA713.1). The footprint is the `dm_`/`dlv_` durables, the read-ACL row, and the durable\n  membership row for each concrete channel the teardown names (one exact `memberKey` grant per\n  channel). A wildcard channel is refused at mint. The manager names the launch's concrete read\n  channels plus the channels the delivery daemon's read-only `lifecycleMemberships` admin verb\n  lists for that exact `(principal, lifecycleUid)`. When that inventory cannot be read, rows on\n  other channels stay retained, the teardown logs the inventory as incomplete, and retirement\n  remains held pending retry rather than releasing the alias.\n- `supervisor`: the always-on agent-lifecycle daemon (the manager process's own connection). It\n  is the manager endpoint's serve credential (\xA713.9) and the ONLY holder of the capabilities for\n  the delivery endpoint's admin commands (below).\n- `delivery`: the server-side Plane-3 infra: fan-out, trusted-reader re-authorization, and the\n  membership/ACL records the durable backstop authorizes against (\xA77). It is the `delivery`\n  endpoint's serve credential (\xA713.9); its admin commands, `reloadCreds`, the explicit adoption\n  step of standing credential renewal (the daemon re-reads its re-signed creds file, pins the\n  identity, swaps its connection, and reconnects the membership feed's rw connection, replying\n  with the adopted JWT windows); `reloadStoreIdentity`, the store-identity challenge that\n  names the SecretStore the daemon reloads from (the workstation root only when `--creds` is\n  `<root>/.cotal/<spaceSegment(space)>/delivery.creds`; the file's own directory otherwise, an injected coordinate,\n  the declared identity of an injected adapter, or the workstation root of the canonical arm; never a\n  `findCotalRoot` ancestor walk). The first-party workspace filesystem adapter declares its workstation\n  root, so passing that store explicitly names the real operator layout without an ambient coordinate. Uninjected `--creds`\n  that names one real workstation while process cwd resolves another is refused at start, because\n  membership-rw still uses `findCotalRoot`; a `--creds` path that is not under any `.cotal` tree is not that\n  case. A manager whose remint store diverges is not that daemon's renewal owner: it starts and\n  serves the space and skips the remint rather than being refused, including a daemon that bound\n  after manager start. Matching that store identity is necessary but NOT sufficient to own the\n  renewal, since the comparison carries no holder and no tiebreak and every manager sharing one\n  store satisfies it; the owner is the manager that also holds the space's renewal lease, so a\n  daemon's credentials have exactly one renewal owner at a time. And `evictPrincipal`, force-drop of a denied principal's live\n  connections (system-account CONNZ scan \u2192 per-server KICK \u2192 re-scan verify, fail-closed on\n  partial scans and on owners outside the principal namespace); carry a capability requirement\n  minted to the `supervisor` profile **and to the trusted auth path** (\xA79/\xA710), which is the\n  executor of the \xA713.1 takeover / terminal-retirement / handle-revocation barriers and calls\n  `evictPrincipal` on each revoked credential's `holderPrincipal` (\xA713.1) as their eviction\n  step; agents are broker-denied. `evictPrincipal` is\n  wired into those barriers, not\n  a standalone admin convenience. `evictPrincipals` is the same eviction for a set of at most 256\n  distinct principals in ONE shared sweep: one CONNZ scan for the set, a KICK for every matching\n  connection with at most 16 KICK requests in flight, and one re-scan per verify round covering\n  every principal still pending. Every KICK settles before the re-scan that verifies it. Its reply\n  is one `EvictionResult` per principal in request order, each read as `evictPrincipal`'s\n  (an under-reported scan leaves every principal it would have decided `verifiedGone:false,\n  scanComplete:false`). Frozen-gate reconciliation and an endpoint re-registration (\xA713.1) each\n  verify-evict their whole holder set through it, so neither costs one sweep per family holder,\n  and KICKing a live family costs one broker round trip per 16 live connections. A\n  daemon that does not serve it refuses the verb, and the repair or re-registration then leaves\n  the gate frozen. Its READ-ONLY twin `principalLiveness` answers whether one\n  principal still holds a live connection (the same CONNZ sweep, observer credential only \u2014 the\n  KICK credential is never opened on that path), reporting `live` / `gone` / `unknown` with scan\n  completeness as a separate field and a reply bound to the exact principal queried. It exists\n  because eviction cannot serve as its own precondition: a repair that must REFUSE while a holder\n  is alive would, using `evictPrincipal` to find out, kill the holder before it could refuse.\n  `gone` requires a complete, single-server-proven sweep (\xA713.13); an under-reporting sweep is\n  `unknown`, which never authorizes. The former\n  `delivery-admin` control tier is deleted with the v0 rail (\xA713.11).\n- `membership-rw`: the derived channel-membership graph feed reader/writer.\n- `operator`, `purger`, `teardown`, `channel-writer`, `control-caller-*`, `deployer`, `probe`: the\n  human-CLI and maintenance surfaces, each scoped to its verbs.\n- `issuer`: one issuance window (\xA713.15), minted per mint or per lifecycle terminal by the party\n  holding the space signer; the issued and accepted stores plus one auth-store liveness read.\n- `run-admitter`: one run's admission record or revocation marker (\xA714.8), minted per run for\n  60 seconds; two exact keys and nothing else.\n- `manager-service` is NOT a generic host profile: on a per-user-auth space only the\n  loopback/operator exchange may issue this closed, one-owner/one-fixed-manager-actor/one-instance\n  view to a signed-in user with ledger scope `supervise` (\xA713.1/\xA713.6). It reaches exactly the\n  staged manager registration, contract, status, gate, credential, and same-owner descendant\n  provisioning family; public exchange, managed-agent secret exchange, plain user bearers, and all\n  other instances are refused.\n- `platform-control` is NOT a generic host profile either. It is the \xA713.1 service view a host\n  issues, through its authority context's in-process door only, to one platform-run control\n  manager per assigned account, under a `p_` platform owner and the host's current assignment. It\n  reaches the same one-instance family as `manager-service` and same-owner descendants only. It\n  never carries a human identity, never reads or implies `supervise`, and every exchange refuses it.\n\nStanding host credentials are **bounded and renewed**: one-shot profiles carry minutes-scale\nexpiry; `supervisor`/`delivery`/`membership-rw` carry a 24h expiry with the manager as the named\nrenewal owner (self-remint for its own credential; same-nkey re-sign + explicit `reloadCreds`\nadoption for the seed-less daemons); the two system-account credentials (`membership-observer`,\n`connection-evictor`) carry a 30d expiry and are renewable ONLY by a system-account rotation +\nbroker restart; no persisted system-account minting secret exists, by design. On per-user-auth\nspaces, static `agent`/`observer`/`admin` minting is retired entirely (the flip): agent identities\nexist only as owner+actor principals under a logged-in user, and the elevated profiles of this\nappendix are reached per-connection via the exchange-authored view claim instead (\xA710). The flip is\ndeny-new: a static\ncredential signed before it (or minted out-of-band with the account signing key) remains\nbroker-valid until signing-key rotation, which is the revocation lever for static material; the\nguarantee therefore applies to spaces that never issued static user-facing credentials.\n\nThe live channel subscribe depends on none of these; it is broker-enforced via `sub.allow`, so\nself-serve live join works with no host present; only the durable backstop and its membership writes\nrequire a privileged host. None of these profiles is ever issued to ordinary agents. On the v0.4\nendpoint surface, every host profile's grant rows are **generated from the \xA713.9 ownership matrix**\n(matrix \u2192 grants, never the reverse): a profile with no matrix row holds no `ep*`, `$O.`, or\ncontrol-surface `$JS.API` authority, and `provision.ts` (`permissionsFor`) is the generated artifact\nthis appendix summarizes, not an independent authority. This appendix spells out the `agent`,\n`observer`, and `admin` profiles that make up the wire-facing security claim.\n\n## Appendix C: Normative references\n\n| Reference | Used for |\n| --- | --- |\n| RFC 2119, RFC 8174 | requirement keywords |\n| RFC 8259 | UTF-8 JSON envelopes (\xA75) |\n| RFC 4648 | base32 instance-id encoding (\xA72) |\n| RFC 8032 | Ed25519 keypairs behind nkeys (\xA72) |\n| RFC 8785 | JSON Canonicalization Scheme: every `*Digest` (\xA713.7), the program hash, input hashes and derived ids (\xA714, [`spec/cotal-lang.md`](spec/cotal-lang.md)) |\n| [ECMA-262, 14th edition (ECMAScript 2023)](https://262.ecma-international.org/14.0/) | the syntax and pure semantics the workflow language is a subset of ([`spec/cotal-lang.md`](spec/cotal-lang.md) \xA72) |\n| [NATS client protocol](https://docs.nats.io/reference/reference-protocols/nats-protocol) + [JetStream](https://docs.nats.io/nats-concepts/jetstream) | the v0 transport binding (\xA78) |\n| [NATS decentralized JWT auth](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt) + nkeys | identity and authorization (\xA72, \xA79) |\n\n## Appendix D: Change log\n\nNormative revisions of this document, newest first. Dated snapshots per \xA711; the wire\n`protocolVersion` is the compatibility signal, not these dates.\n\n| Date | Revision |\n| --- | --- |\n| 2026-10-04 | **Managed lifecycle handoff (\xA713.17), additive.** A managed agent already enrolled through \xA713.1 may run where the enrolling manager's filesystem is not visible. The manager releases one closed `cotal-managed-handoff/v1` document by value into that one child, carrying the issued owner, actor, lifecycle UID, sentinel, pinned exchange base, and the raw actor token, which the host never receives. The child's entry point removes the handoff file and its variable before it parses its arguments or does anything else, refuses a mismatched owner, actor, or lifecycle UID before any plane opens, never enrolls or mints, and uses the existing agent-bearer exchange unchanged. The manager refuses a spawn choice only its own host can honour before enrolling. Readiness stays presence-observed, a lost create acknowledgement stays held as uncertain and is never retried, a provider's answer that no resource exists is not an exit, and a close by the lifecycle-derived key is fenced against a create that could still land. A provider resource is bound to that key only by the provider's authenticated answer to its create, never by a derived identifier, a name or a listing. Retirement reuses prepare-retirement, then the known runtime handle's fenced close, then the terminal barrier, including after the manager is gone. A preservation cut that holds a handed-off lifecycle is refused, and a manager stop after a refused cut retires it. |\n| 2026-10-04 | **Platform control authority (\xA713.1, \xA713.6, \xA713.9), additive.** A closed server-authored `platform-control` view, beside the unchanged human `manager-service` view, lets a host run one pooled control manager per assigned account. Its holder's owner is a host-derived `p_` platform owner token, disjoint from every `u_` owner. The host's fresh platform-control assignment authorizes it in place of a ledger `supervise` scope. One closed envelope carries the existing typed manager requests through an in-process door of the host's authority context, served on no listener. The unchanged registration proof, process epoch, and all-duty renewal renew and fence it. Its host-owned maintenance reaches only the assigned instance under its own gate. An account has one assignment and so one control instance, which keeps its instance id and lifecycle UID across restarts and enters a deployment only after the assignment's named predecessor manager has left through its own path, read and never written by the host. It refuses human tokens, takeover of another owner's instance, local or custodial runtime, generic signing, exchange issuance, and cross-owner descendants. The reference host is `startAuthService` in `@cotal-ai/auth`. |\n| 2026-10-02 | **Plane liveness (\xA76.1), additive.** A credentialed peer can ask whether the manager or delivery plane has a bound responder, on `live.<plane>.<owner>.<actor>` with the reply under `<request>.reply.<nonce>`. The reply is `LivenessAnswer`: `plane`, a `ResponderState` verdict, and an optional opaque per-bind `instance` token that distinguishes responders without identifying them. Only the broker's no-responders answer grades `unbound`; every other failure to get a readable reply grades `unknown`. Agents gain the per-plane request and reply rows; the `delivery`, `supervisor` and remote-manager supervisor credentials gain their plane's serve filter and bounded reply grant. A responder binds again on every connection that replaces the one it bound on, and the manager is not `bound` while its service connection is closed or disconnected. |\n| 2026-09-28 | **The `auth` endpoint becomes a conforming registered endpoint (Cotal #399), closing the two gaps the prior two rounds named.** The plane's boot registers `svc.auth.<instanceId>` through the standard `registerServiceInstance` path and publishes its `retire-lifecycle` contract artifacts to the content-addressed contract store, so the endpoint now serves the reserved `describe` and answers the v1 envelope (`ep.v1`) instead of the legacy `{op,args}`/`{ok,data,error}` body this document states are deleted; a legacy body is refused `unsupported-version` as envelope validation, never an ACL denial. The requester side moves from a hand-built subject to the generic client (`resolveService` + `invokeCommand`), still minted in `exact` mode target-pinned to one incarnation at mint time, and gains the baseline `describe` row plus a bounded contract-store direct-get row so it can resolve the endpoint's registered digests before it calls; a body target that disagrees with the exact subject triple is refused `target-mismatch`. Two new \xA713.9 rows record the registered instance and the requester's describe/store-read grants. |\n| 2026-09-27 | **Id-less messages are not publish-deduplicated on the durable plane (\xA78).** The reference Plane-3 fan-out writer and membership-transfer frame publish carry no `Nats-Msg-Id` for a message whose `id` is `\"\"`, so two distinct id-less posts on a durable channel both reach a member and a redelivery of one id-less post may surface twice; a message with a real id keeps its idempotent publish key unchanged. Classification: reference-binding behaviour, no wire-envelope or schema change, protocolVersion unchanged. |\n| 2026-09-09 | **Issued authority and run admission (\xA713.15, \xA714.8).** A caller's request may ride a versioned rail (`ep.v1`) that pins the credential's issuer-accepted **generation** beside its triple; the issuer persists the generation's immutable permission ceiling as evidence before returning material, and a client learns its generation from an issuer-written accepted row. A hosted workflow run is admitted under the caller's resolved ceiling, recorded once per run in a dedicated store the driver cannot write, checked before every channel effect, and revoked by an independent marker; resume, takeover and reconcile continue under the original admission, a fork is a new admission, and a local run is admitted from operator evidence named on the command line. `run-start` on the legacy rail is refused by name. Three new per-space stores, two new one-shot profiles (`issuer`, `run-admitter`), and an admission read on the run mediator and operator profiles. **Breaking pre-1.0 authority change: minor.** |\n| 2026-08-24 | **Remote user manager authority.** A closed server-authored `manager-service` view permits one registered user-auth participant to operate one opaque manager instance only when their live actor-ledger row carries the dedicated `supervise` scope. `supervise` is distinct from `spawn` and `admin`; public and managed-agent exchanges refuse the view, and plain user bearers remain unprivileged. The host, never the participant, issues public-nkey JWT material through a lifecycle- and instance-bound, typed, replay-safe `prepare \u2192 activate \u2192 renew` protocol. The family is confined to one derived owner, fixed server-selected manager actor, lifecycle UID, instance registration/contracts/status, gate, and credential rows; descendant provisioning is host-validated for the same owner only. Revocation and renewal deny new material and unsafe restarts fail-closed while retaining live agents only within their independently valid authority. **Breaking pre-1.0 authority change: minor.** |\n| 2026-08-19 | **Receiver deduplication MUST NOT use the empty string as a key (\xA74), and id-less deliveries are individually addressable (\xA78).** Two distinct received messages MUST NOT be treated as one logical delivery solely because both carry `id: \"\"`; each remains independently deliverable, and copies that cannot be correlated by wire identity may surface more than once on an at-least-once path. The publisher's \xA75 obligation to supply a unique string id is unchanged; an absent or non-string id remains a malformed envelope, now enforced at each delivery pump (durable terminate, live drop, history and recall skip). \xA78 adds that the absence of a usable receiver dedup key does not relax acknowledgement ownership: a JetStream-consumed copy with `id: \"\"` that is surfaced or handled MUST be acknowledged independently, and the reference implementation realizes that through a per-delivery receive key (never wire identity, never dedup authority) at its drain and in-flight seams. Plane-3 durable fan-out still derives its publish msgID from `CotalMessage.id`, so distinct `id: \"\"` messages can be collapsed inside the broker's duplicate window on a durable channel before the receiver sees them; that path is its own tracked change and this revision's guarantee is scoped to the receiver. Classification: normative receive-side semantics, no wire-envelope or schema change, `protocolVersion` unchanged. |\n| 2026-08-18 | **v0.5 binding revision: workflow runs (\xA714), additive.** A deployment MAY host durable workflow runs: programs in the Cotal workflow language, defined by the new normative reference [`spec/cotal-lang.md`](spec/cotal-lang.md) (language version `1`: the syntax table, values and the boundary rule, the library, the effect primitives with their hashed projections, the four concurrency scopes and the clock-decided `race`, the step key grammar, journal entry schema, input hash and request id, resume, migrate and fork), whose every effect is recorded in a per-run step journal on the new per-space `WFJ_<space>` stream (one subject per run, no age eviction, no Direct Get, every append fenced by the run subject's own sequence, replay-then-activate takeover with a fencing-token authorization tuple, an ordinal chain and a `journalHigh` anchor). Four core record kinds join \xA713.7: `run` (split; the resolved pin set on the spec half, holder/lease/`journalHigh` on the status half; driver-minted, never-reused ids), `answer` (atomic, content-derived id, keyed per answer because every presenter is the driver), `notice` (split; addressee keyed by a digest of the name; consumption as status), `migration` (split; content-derived id; application as a create-only status). Driver grants are per run and per takeover, with no wildcard form. `languageVersion` is pinned per run and moves independently of the wire version. No existing kind, subject, grant row or shipped datum changes. |\n| 2026-08-16 | **A caller declares the incarnation it resolved against, and a responder that is not it refuses before any effect.** A class-addressed request is delivered to one member of a queue group, and the member that answers need not be the one the caller's `describe` resolved against. The caller could only detect that AFTERWARDS, from the reply subject, by which point the command had run: the split was observable but never preventable, and the reference client's recovery repeated the command. `bind` (\xA713.3) is the caller's declaration of `{ instanceId, epoch }`, checked by the responder against its own identity at the pre-effect seam, ahead of the governed gate and every handler. A mismatch is `failed-precondition` for a different instance and `expired` for another epoch of the same one, both carrying `details[].kind = ai.cotal.ep.bind-refused` and, per \xA713.3, `outcome: not-executed`. **ADDITIVE**: `bind` is MAY, a responder that does not implement the fence ignores it under \xA75 and executes, so the caller-side check remains the only protection in a skewed pair and `protocolVersion` stays 0.4. It confers nothing and narrows only, so it satisfies monotonic attenuation: a request carrying it reaches exactly the instances the subject already routes it to, and can only make one of them refuse. Absent on `describe` (the bootstrap that produces the bind) and on the scatter rail (which addresses every incarnation by construction); on the `inst` rail it MUST name the subject's instance and adds the epoch the subject grammar has no token for. Attribution still comes from the reply subject, never from this block: it is what the caller bound, not a claim about who answered. |\n| 2026-08-16 | **A command declares whether repeating it is safe, a responder reports whether a refusal already executed, and the two are separated from idempotency by `id`.** Three gaps that only bite together. **(1) `effect` (\xA713.7).** Nothing in a resolved command distinguished a read from a mutation \u2014 every manager command declares `class: \"ephemeral\"`, and `traits` carries no repeat-safety \u2014 so a client deciding whether to retry had nothing to consult, and the reference client repeats a mutation on a split. Precisely: the automatic repeat belongs to the high-level helper, not to the primitive \u2014 `invokeCommand` raises the post-reply currency refusal and stops, and the `invokeService` wrapper around it catches exactly that code, re-resolves, and invokes a second time. Measured on a live broker under a forced instance split, counting at the handler rather than on the wire, the repeated command executes TWICE. `effect` is `read` or `write`, with `read` defined OPERATIONALLY \u2014 repeating it changes nothing the command is TRYING to change, and the only excluded difference is the incidental trace of having been called (request ids, spans, logs, metrics, timing) \u2014 because the intuitive definition, indistinguishable to every observer, is satisfiable by no real command and would make the field decorative. The state in question is not only the endpoint's own: a command whose intended effect lands elsewhere is still a `write`, and `evictPrincipal` fixes that boundary, since dropping live broker connections while leaving the endpoint's own records untouched is the point of calling it. **(2) `error.outcome` (\xA713.3).** A refusal code cannot say whether the effect happened: the same code is correct for a request that ran and one that never left. `outcome` is emitted by the RESPONDER, which is the only party that knows \u2014 `not-executed` when it refuses before the handler, `executed` when it refuses after, `unknown` when it cannot tell. It describes a reply and only a reply \u2014 a caller-side refusal is not an `EndpointReply` and carries no `outcome` field \u2014 but it does NOT follow that the caller knows nothing, and the first cut of this amendment wrongly collapsed four distinguishable local cases into `unknown`. A refusal raised BEFORE publication is `not-executed`: the request never left, and calling that `unknown` suppresses a retry that is provably safe even for a `write`. A refusal raised while HOLDING a reply \u2014 the \xA713.2 post-reply currency check is the case in this document \u2014 takes what it knows from that reply: `ok:true` means the handler ran, and an `ok:false` reply carries the responder's own `outcome`, which the caller adopts rather than overwrites. A **broker-attested no-responders answer** on the reserved sentinel is also `not-executed`: it is positive evidence that the subject had zero subscribers, trusted only on that sentinel because the same status on an ordinary reply subject is a responder's own claim. Only \"no reply observed at all\" (deadline, transport failure after publication) is `unknown`. And **a reply proves the request was HANDLED, never that it was EXECUTED** \u2014 the version, class, target, sender, authz, contract, and guard checks all publish `ok:false` having executed nothing. It is also not a goal's terminal state (\xA713.6 owns that) and must not be used as one. **(3) Repeat versus resubmission (\xA713.8).** `effect` and \"idempotent by `id`\" are different axes and were unreconciled. They are now separated by CONVERGENCE rather than by token: a **resubmission** is a re-send the responder converges onto the decision it already recorded, a **repeat** is one it accepts as new work, and `effect` governs repeats whatever `id` they carry. Defining the split by the token instead left a hole \u2014 a post-horizon re-send under a reused `id` is accepted as new work, so it executes, while formally escaping a prohibition written as \"under a fresh `id`\". Reusing the token is how a caller ASKS for convergence; it is not the answer. Within the horizon `id` is what convergence is keyed on \u2014 and `id` is the whole key on the ephemeral rail but only ONE of the effect-defining dimensions the journal fingerprint binds \u2014 endpoint, command, `id`, `goalId`, `class`, args, both contract digests, the authorization mode, the target, `auth`, and the caller \u2014 where same id + different args is neither dedup nor a fresh call but a loud `conflict`. **Both rails are bounded by a horizon**, realized by decision-fact and result retention rather than by a clock, and outside it neither rule applies: the `id` carries no history, a re-send under it is a fresh call that WILL execute, and the same `id` with different args is no longer a `conflict`. A finite horizon is what keeps the decision store finite, so this is a fact callers must hold rather than a hole to close \u2014 and because a repeat is defined by acceptance rather than by token, a post-horizon same-`id` re-send of a `write` is exactly what \xA713.7 forbids a client to make automatically. A command idempotent by `id` is therefore NOT thereby `read`: safe to resubmit is not safe to repeat \u2014 and the dangerous reading is a reasonable one, since an operator who retries after a timeout mints a fresh `id` because the old request is gone. **NON-ADDITIVE, and versioned as such:** a client that ignored `effect` would keep performing exactly the retry the field exists to stop, so it rides `protocol.v` \u2014 the marker that ALREADY EXISTS on the service record spec and the describe descriptor, never a new field on the cluster document, which has no `protocol` and where \xA77 would drop it unread by exactly the clients this must stop. An instance whose clusters declare `effect` registers and describes at `v:2`; `v:1` descriptors stay valid, carry no `effect`, and every command served under one reads as `write`. The caller-side refusal of a `protocol.v` it does not implement is a requirement this cut CREATES, not one already met: today `describe`'s pinned output schema fixes `descriptor.protocol.v` to the constant `1`, so an unamended responder cannot publish a `v:2` descriptor at all, and the registry reader refuses a service record that is not `v:1` \u2014 but the resolving caller validates neither, and the shape it reads does not carry `protocol`. The responder-side fence is what protects old clients today, and only until this cut widens that constant. **Release order was the wrong instrument and is withdrawn**: a same-release ordering rule has no observable runtime meaning, since a release is not a deployment and an already-running v1 caller is unchanged by whatever a new artifact contains. **The cutover rule is \xA711's, and \xA713.7 does not state one.** Moving to `protocol.v: 2` IS a non-additive discovery change, so the \xA711 rule for one (previous row, landed first) is the sole authority on how it rolls out. \xA713.7 carries only what is specific to `2`: a caller that resolves a descriptor whose `protocol.v` it does not implement MUST fail the resolve (`unsupported-version`) and MUST NOT invoke against it \u2014 a descriptor it cannot read is no descriptor, and reading it as `v:1` reinstates the repeat \u2014 and implementing that refusal is what makes a caller count as having ADOPTED the section for \xA711's condition. Two intermediate drafts had to be withdrawn to reach that: one sited the cutover in \xA713.7 as a same-release ordering clause, which has no observable runtime meaning because a release is not a deployment; the next stated the cutover in BOTH sections, which is a single-source-of-truth defect, since two normative statements of one rule agree until either is edited and then silently become two conformance rules. The reason it cannot be sited here is the durable part: the condition is a property of the whole deployment, and a responder cannot evaluate it \u2014 no in-band negotiation, no caller version on the wire \u2014 so a rule stated here would bind the one party unable to check it. |\n| 2026-08-16 | **A non-additive discovery change is an out-of-band deployment cutover and rolls out CALLER-FIRST (\xA711).** The preceding \xA711 rule says v0 has no in-band capability negotiation and that deployments agree out of band; this says what that obliges when a discovery change CANNOT be ignored safely \u2014 where an unamended client that drops the new field per \xA77 would then behave in the very way the change exists to prevent, so no default value repairs the direction that matters. The obligation rests on the DEPLOYMENT, because neither participant can discharge it: a responder cannot tell an amended caller from an unamended one, since no request carries a caller version and `describe`'s answer is read by the caller without a version check. So every caller adopts the new rules BEFORE any responder registers or describes at the new version, and the two halves SHOULD ship in SEPARATE releases \u2014 **a release is not a deployment**, and an already-running caller is unchanged by whatever a new artifact contains, so the order of two source edits proves nothing about the processes on the wire. `protocol.v` on the registered service record is the observable marker: \"has any responder cut over\" is a checkable registry property, while \"has every caller adopted\" is the out-of-band agreement \xA711 already requires. **The residual is stated rather than engineered around**: an early cutover exposes unamended callers to exactly what the new version prevents, and within v0 nothing in band detects it \u2014 closing that needs negotiation v0 does not have, and the v1 marker owns it. Prose only: no schema, no wire field, no code. |\n| 2026-08-14 | **The auth-admin rail moves off the retired `ctl` surface onto the endpoint SUBJECTS (a subject-plane migration, NOT yet a conforming endpoint - see the residual below), and its authz description is corrected to what ships.** TWO defects on the same \xA713.9 rows, fixed together. **(1) The rail.** The rows served the auth plane's generic \"retire a lifecycle\" operation on `ctl.auth-admin.<owner>.<actor>` \u2014 a rail \xA713.11 retires in full and states MUST NOT be handled. New normative rows written onto a deleted rail are defects, not exceptions to it, so they are rewritten onto the v0.4 endpoint surface rather than given scoping language: `ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.<nonce>`, served queue-qualified on the class rail, with the reply DERIVED from the parsed request (the bound-reply rule becomes structural \u2014 no caller- or payload-supplied reply target can arrive) and the request/reply planes disjoint, so the listener credential cannot express a request subject and the self-forge closes by grammar. The requester credential now pins its caller TRIPLE and exactly ONE target incarnation, so a leaked requester cannot be re-aimed. \xA713.11 is unchanged and gains no carve-out. **(2) The authz sentence.** These rows described serve-time authz as a space-manager-LEASE holder check; the implementation replaced that with the serve-issuance-gate check on 2026-07-22 without a spec change, so the normative text had been false since. It now describes what ships \u2014 a fresh leader-served read of `epgate.<serveEndpoint>.<serveInstanceId>` requiring presence, the declared epoch, and THE PRINCIPAL CROSS-CHECK (`row.principal` must equal the subject-derived caller principal), the last being new here: the two-token `ctl` subject could not express the caller beyond an alias, so the rail had accepted ANY registered instance's gate. The binding is stated as ALIAS-LEVEL, not incarnation-level: the gate is keyed by the persisted `instanceId` and its row carries no lifecycle uid, so a same-principal predecessor presenting the current epoch still passes; binding the publishing incarnation needs a gate-row schema change and is not attempted here. **NAMED RESIDUAL (Cotal #399) - THE RAIL IS NOT A CONFORMING ENDPOINT: it carries the endpoint SUBJECTS only. It still exchanges the pre-v0.4 `{op,args}` / `{ok,data,error}` bodies this document states are DELETED, registers no `svc.<endpoint>.<instanceId>` service record, does not serve the reserved `describe`, and has no contract/cluster artifact - so a GENERIC endpoint client can neither discover nor invoke this command. The exploitable half is closed in this change - the request carries a caller-chosen `id`, the responder echoes it on every reply, and the caller refuses any reply that does not echo, so a wrong-id `ok:true` cannot clear a retirement hold - but the versioned typed envelope, contract digests, `class`, deadline/`replyExpected` semantics, structured errors, service registration and `describe` are a separate cut tracked at #399, whose acceptance test is that a GENERIC client can discover and invoke the command. Recorded here rather than left implicit: serving a deleted envelope on the new rail is the same class of defect as serving on a deleted subject.** |\n| 2026-07-19 | **v0.4 amendment continuation: retirement cleaner inventory is discovery-only.** The terminal retirement barrier no longer accepts a caller-supplied `(endpoint, pools)` hint: the per-op cleaner and settlement-executor pool set is now DISCOVERY-ONLY, exactly the retiring lifecycle's accepted `oblig.<uid>.>` pool routes discovered from the just-drained obligation set. This SUPERSEDES the round-11 optional-hint clause (the 2026-07-15 row): the hint was a TRUSTED ADDITIVE AUTHORITY input that would mint a bounded per-op credential for a pool with no backing obligation, and the despawn rail never exercised it (always an empty hint), so it was grant-widening surface with no production caller. Every grant now scopes to exactly the pools the target holds accepted work on, and the \xA713.9 residuals cover only those discovered pools. The intent's `endpoints` field is removed from the closed operation-intent schema; a pre-change durable intent that still carries it fails the closed-schema check on resume (the v0.4 hard-cut window, where a clean broker holds none). |\n| 2026-07-16 | **v0.4 amendment continuation: connect-arm deny-new (production activation R1).** Every bearer carries its incarnation's root credential id (`act.credentialId`); the exchange mints the root credential RELEASE-LAST (active `cred.` row durable, gate finalize, lifecycle-head current-root CAS, bearer bytes last) and the connect authority requires the LIVE row (leader-served from the shape-proved primary auth store, re-proved on every rebind) plus root head equality, so revoking the row denies the next connect and a superseded or crash-orphaned root issuance never authenticates. The root credential is **incarnation-wide** (ratified): one row per incarnation, re-stamped (the same id) every exchange for its 90d life, never a fresh id per exchange, so one revoke denies every bearer of the incarnation, and a crash after the head CAS re-exports the same id by design (nothing unobserved to revoke; the only pre-release crash window is a durable unstamped row, denied by head equality). The authority store shape proof binds the stream to the actual KV bucket (exactly the one `$KV.<bucket>.>` subject + durable file storage, in addition to the primary/un-mirrored/non-evicting/`allow_direct` flags) at every bind and at boot ensure. Claimless bearers, revoked/expired/absent rows, and an unreadable authority store deny outright (no file-only fallback; a failed reader-credential renewal downs the reader immediately and denies). The head's current-root stamp moves only ABSENT to value: root rotation without the full family-revoke barrier is refused structurally. Named R1 residuals: a same-alias re-grant while the predecessor incarnation is live refuses the exchange (production issuance runs no takeover barrier yet), and the auth service's reader/mint-writer are seed-signed infra credentials (revoked by service stop or signing-seed rotation) pending the ledgered infra-mint family. |\n| 2026-07-16 | **v0.4 amendment continuation: retirement settlement authority split.** A seventh round (an independent cold read on the landed barrier plus the panel's authority ruling) split terminal pool cleanup across two profiles: the bounded cleaner keeps ONLY bind-scoped fetch, leader-served EPF terminal-observe reads, and ACK (its former own-pool `wrk` terminal-forge residual is REMOVED with the grant; its remaining residuals are terminal-free ACK suppression and the space-wide read exposure), while the op-bounded retirement settlement executor (a new \xA713.9 row) owns the intent-closed lease-record CAS and the lease-derived `wrk` terminal publish, carrying the relocated, intent-confined forge residual. Settlement is lease-fenced: an already-settled lease (a crashed owner's `committed`) dominates and is never overwritten. Effects-route completion is a new CLOSED `eff` fact (subject-bound caller and id; `fingerprint` and `sourceSeq` bound to the accepted decision), an action's completion requires the parsed `goal\u2026.result` fingerprint match, and subject presence never proves quiescence. The mediator's obligation-row residual is stated honestly (an operation/header-blind KV publish: valid-terminal overwrite or DEL/PURGE markers, refused loud by readers; the records stream denies stream-API message-delete/purge), and the caller-selected-reply confused-deputy injection residual is named for every raw `MSG.GET`/`MSG.NEXT` profile. |\n| 2026-07-15 | **v0.4 amendment (folds into the in-flight \xA713 revision below): lifecycle and admission fences.** Three-state lifecycle head (`active | retiring | retired`; currency only at `active`; `mappingRevision` = the head key's store revision), space-global never-deleted UID reservation (`uid.<lifecycleUid>`), per-kind issuance-gate operation intents and their allowed-transition sets, the locked terminal barrier order (obligation drain to quiescence before the exact-pool cleaner, both before frontiers), the \xA713.8 authority-head reservation/drain protocol (create-fence + proof-gated admission + per-class decision coordinates + writer\u2260target reclamation), the endpoint-wide admission-policy coordinate (the governance head + `policyRevision`) with drain-gated policy enforcement, the `ep` sentinel for untargeted admissions, and bind-time store shape proofs (\xA713.12). Refined per the re-verify round: the govern head's NORMATIVE policy selector `{ enforcedPolicyKey, enforcedPolicyRevision, pendingPolicy\u2026 }` with a stage/drain/promote mutation order (so the enforced policy is machine-selectable during the drain window), the `self`-class obligation's complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }` (the pinned BYTES, not just a digest) with deterministic `accepted \u2192 terminal` recovery and full-intent create-join (an accepted-but-uncommitted row never blocks quiescence), the retirement barrier's cleaner-credential revoke + verified-eviction BEFORE any frontier records, the LIMITS-retention bind-time proof (a non-Limits authority store deletes rows on consumer ack), and the runtime gate parse rejecting impossible `retired`-under-takeover/registration state. A second re-verify round added: the head's `lastTakeoverOpId` (the epoch advance stamps the completing op, so a losing concurrent takeover never claims the winner's completion), the immutable revision-addressed admission-policy key (a mutable per-instance slot loses the old revision under history 1 during the drain), the `epgate.principal` and the rule that a ledger row's `holderPrincipal` is ALWAYS a CONNZ-attributable principal (the endpoint NAME forms the `epcred.` key in a separate field, never the eviction target), and the lifecycle barrier's session-pair teardown (a takeover revoking a `session.`-derived credential terminalizes the session and revokes the paired serving row). A third round (a convergent panel + independent cold read) added: the normative immutable `policy` record kind `policy.<endpoint>.<digest-hex>` (self-certifying content-addressed key; the govern selector names exactly this kind, replacing the per-deployment \"versioned key\" allowance), the CLOSED `commitValue` union (`{ enc: \"b64u\", bytes }` exact base64url value bytes, or `{ enc: \"ref\", key }` naming an immutable records key; `commitDigest` = `sha256:<hex>` over the raw value bytes), proof-issuance PAUSE for policy-admitted decisions while a `pendingPolicy\u2026` is staged (which makes the policy drain converge and the after-final-enumeration no-admit rule hold for policy movement), the serving-principal JOIN into the lifecycle barrier's verified-eviction set (a session-pair teardown returns the paired serving row's holder principal and the barrier evicts it before the epoch CAS), and the torn-coordinate takeover guard (the intent capture re-proves head coherence, and the freeze CAS is preceded by a head-currency read, so a stale intent never freezes the winner's reopened gate). A fourth round (a convergent re-verify + independent cold read) added: the drain-window admission pause is now a NORMATIVE step of the \xA713.8 admission algorithm (the mediator's create-fence AND post-create recheck leader-read the govern head and refuse a policy-admitted decision while a `pendingPolicyKey` is staged, which also bounds the never-deleted `oblig` set during a long drain), the \xA713.9 matrix records the mediator's govern-head and policy-version read authority, the `policy` kind's immutability is stated honestly as a trusted-writer create-only-CAS invariant backed by read-time self-certification rather than a broker-level update/delete subtraction (KV operations share one subject), and the takeover barrier's crash-boundary recovery COMPLETES containment (revoke + reconcile + verified-evict every family holder) BEFORE it aborts a stale/torn freeze, so a crash after a partial revoke never leaves a revoked credential's connection live. A fifth round (panel + independent cold read on the B2 mediator) refined: `commitDigest` is the RFC-8785 canonical content digest of the committed value, `sha256:<hex>` (not a raw-bytes digest, so it is insensitive to a non-canonical storage stringify), and `commitValue`'s `b64u`/`ref` forms both resolve that same value; the policy publication is content-addressed by the same canonical digest (property-order-insensitive). The session expiry sweep now enumerates a marker-preserving stream read rather than the bucket's `keys()` (which filters DEL/PURGE), so a tombstoned session key is reported as corruption, not silently skipped. The terminal barrier's frontier record is pinned as the `frontier.<lifecycleUid>` kind (\xA713.7: create-only, never deleted, one key per retired lifecycle, recorded once under its own operation's `opId` before the gate/head terminals), and the exact-pool cleaner's `retired` disposition is a first-class `wrk` terminal fact carrying its operation and retiring-target binding. A sixth round (the D14 confinement review) pinned the two mediated-profile grant shapes: the admission mediator's enumeration consumer carries a deterministic (endpoint, connection)-bound name with name-literal CREATE/INFO/MSG.NEXT/DELETE rows (closing the name-wildcard cross-consumer reach; the own-name delete is what keeps the fixed name reusable across filters), both profiles' reply inboxes are connection-scoped (`_INBOX_<connId>.>`, never the account-wide default), and both payload-blind write residuals are named with equal explicitness: the mediator's own-endpoint acceptance-forge and the cleaner's own-pool `wrk` terminal-forge (work suppression or mis-settlement), each confined to its subject-expressible scope. A seventh round (the control-surface sealed-scanner seal) moved the dynamic-enumeration `CONSUMER.CREATE` off every standing/runtime credential (the takeover/retirement/handle-revocation barrier and the session sweep on `cotal_auth_<space>`, and the admission mediator plus the retirement obligation-drain on `cotal_records_<space>`) into dedicated SEALED scanners the trusted process opens for itself and NEVER hands out, because a consumer-create request BODY is not subject-ACL confinable (an extended name+filter grant still admits a `durable_name` + push `deliver_subject` exporter of every current/future row that survives connection close and revocation, nats-server#8274, reproduced live); each scanner is pinned to one literal consumer name under a forced pull/`LastPerSubject`/ephemeral/memory config, bind-verified before use and unconditionally deleted after, its CREATE filter confined to its subtree, space-bonded so a hand-assembled or foreign-space scanner never enumerates, and fence-free by construction (a `LastPerSubject` read carries no upper cutoff, so a same-subject overwrite during the scan is SEEN, not dropped). Its re-verify round hardened the seal from asserted to enforced: the scanner capability handle is immutable once branded (a swapped scan op throws rather than surviving the injection assert; that mutation vector was reachable only from inside the trusted process, the signing-seed residual class, never externally), every scan over a space's literal consumer name serializes process-wide (a second scanner instance can never interleave with a live scan and return a partial enumeration; cross-process duplication remains excluded by the one-authority-plane-per-space composition), every delivered subject is revalidated against the exact requested filter (an out-of-filter delivery from a foreign re-resolution of the literal name is refused loud; a foreign SAME-OR-NARROWER filter remains covered by the one-plane composition, not by this check), the two scanner profiles are explicit \xA713.9 matrix rows whose grant builders the mechanical matrix audit pins as the SOLE dynamic-enumeration `CONSUMER.CREATE` holders on the two authority streams (the provisioner's pre-created full-tail reader durables remain the one other records-stream consumer authority, and the audit pins that complete surface too), and the admission-mediator coordinate stays package-internal until a composition owns the one-records-scanner-per-space injection. An eighth round (the control-surface piece-2/4 wiring) landed: the record-reader provisioning seam is an ALLOWLIST over one canonical authority-def collection (a reader durable's kind must be a registered caller-readable record kind, so every authority-control kind and every unregistered kind refuse, and a dual-token kind whose atomic head is authority admits only a filter strictly deeper than the head, never one that can match or is shallower than the head key); that classification is runtime-frozen and the seam consults a private module-load snapshot, so a post-import mutation cannot remove the guard (the same integrity discipline is applied to every exported security-relevant collection: the baseline grant vocabularies, the credential-lifetime matrix, the session terminal states, the schema profile, and the broker floor are all frozen, and the minting-path consumers read private snapshots). The retirement barrier's cleaner authority is SPLIT into two per-operation credentials: a zero-write cleaner (its residual is terminal-free ACK suppression) and a settlement executor that alone holds the lease-record CAS and the lease-derived `wrk` terminal publish on the intent's exact pools plus the leader-served EPF and records fencing reads its own code path performs (NO EPW read: the settlement path settles or expires through the lease key before any EPW live-entry probe, so that read is unreachable and ungranted); the two are distinct CONNZ principals fenced independently before any frontier records, and the barrier runs settlement on the executor's own connection rather than its standing one. The retirement barrier is the `frontier.<lifecycleUid>` writer (the exact-arity `frontier.*` grant row), and the auth service's boot crash-resume finishes an owed retirement through the assembled deps (a per-endpoint short-lived drain client over the reviewed admission-mediator profile sharing the plane's sealed records scanner, and the per-op cleaner/executor split), fail-closed and loud like the takeover resume. Its re-verify round closed three composition gaps: the barrier now grants `STREAM.INFO` for exactly the CLOSED retirement-frontier stream set (the per-space lifecycle-data streams EPF/EPW/EPE/records, one source feeding both the intent validation and the grant, so a frontier read is never denied on a real broker nor a caller-selected arbitrary stream), the settlement executor drops the unreachable EPW live-entry read (the settlement path settles or expires through the lease key before any EPW probe, so that grant was dead), and the assembled drain completes every settleable obligation but fails CLOSED with an operator-legible frozen-not-lost message on accepted work that needs a confined commit-applier/route-reconciler authority (a scoped boundary whose full mechanics are a separate reviewed slice, never a broad records-write grant bolted onto the drain). A ninth round (the cross-process plane-ownership seal, \xA713.13) closed the last composition assumption the sealed scanners leaned on: at most one authority plane per space now holds them by a broker-visible claim, one exact never-deleted auth-KV `plane` row binding the two non-reconnecting scanner connections' broker identities, taken by create/revision-CAS with the candidates INERT until the win (no scan capability exists before it); a stale `held` row is reclaimed on LIVENESS ALONE (both claimed tuples conclusively absent under a COMPLETE connection sweep, adjudicated by the delivery daemon's closed read-only oracle over the delivery-admin rail; the auth process holds no `$SYS`), with no TTL, no heartbeat, and no sealed-scan-progress bit (a mid-scan crash reclaims; a paused-but-live plane keeps its connections and its ownership); the winner re-validates the claim before AND after every sealed scan (refuse or discard), an owned scanner disconnect fences the plane (invalidate exposure, close the sibling, never a transparent reconnect into a successor's consumer), clean close releases only after the scan clients are down, the three operator refusal faces carry distinct copy (live peer / inconclusive-fail-safe / mid-life fenced stop), and the launcher adds an exclusive-create pidfile belt. Its re-verify round hardened the reclaim and the fence: a `gone` verdict is valid only under the single-nats-server-process boundary, proven per observation from the responding server's own topology declaration in the `$SYS` reply envelope (any cluster self-report, multi-server observation, or missing declaration reads `unknown`; leafnode/gateway-extended accounts and backup-restore-onto-a-fresh-broker are named residuals; multi-server needs an incarnation/roster authority) \u2014 never inferred from which servers replied, which could neither be enforced by reply-counting (a partition shows one responder) nor flipped to require-the-claimed-server's-reply (a restarted server can never reply, the permanent-wedge horn); claim re-validation covers the two pinned scanner tuples (a tuple-only row rewrite is a lost claim); a scanner-death fence is FATAL to the whole authority plane (every authority operation refuses and the service exits loud, never a healthy-looking half-dead plane); the plane credentials' non-expiring boundary is normative (exactly the two non-reconnecting plane connections; every other authority credential keeps short-expiry + renewal); the claim row, connection tuple, oracle-query, and oracle-result schemas are closed exactly (unknown fields refuse, at every level); only successful well-formed CONNZ pages count toward a reclaim sweep (an API error, malformed envelope, non-string cluster declaration, id mismatch, or incomplete page poisons the observation); every sweep's reply inbox carries a per-call nonce (concurrent sweeps cannot cross-complete); the fenced plane's refusals are audience-split (a retryable unavailability to connecting agents, the state-3 restart copy to the operator's log and exit line); and the pidfile belt publishes atomically pre-populated (temp inode + no-overwrite `link(2)`; an empty slot is unpublishable and a pre-protocol one reclaims exactly once). A tenth round (the confined drain repairers) closed the retirement drain's accepted-work boundary functionally: the fail-closed applyCommit/reconcile interim is replaced by two per-op, per-repair principals \u2014 the COMMIT APPLIER (`local.epapl_<opId-hash>`, one exact records-KV publish row, minted only for a key inside the CLOSED self-commit class derived from the canonical frozen kind registry + the commit-path writer metadata, so a forged accepted-self row can never name an authority coordinate into a grant) and the POOL-ROUTE RECONCILER (`local.eprec_<opId-hash>`, one exact EPW item create-publish row, executing only a MEDIATOR-DERIVED closed repair command: the mediator reads and row-binds the durable acceptance decision itself and derives the exact subject + the \xA713.6 canonical acceptance item bytes, now a normative derivation so first enqueues and crash repairs are byte-identical) \u2014 each minted per repair, executed, closed, with the CAS-header and payload-blind residuals named per profile; an accepted self-commit now re-applies (or classifies landed/superseded) and an accepted pool route re-materializes, so a retirement with covered accepted work COMPLETES on resume, and an accepted EFFECTS route with no completion marker terminalizes through the RETIREMENT-CANCEL terminal (\xA713.8 option (i)): the effects completion fact becomes a closed two-member union (ran, or `cancelled: { opId, target }` \u2014 the same identity spine, never a forged success, written only for the retiring target's own acceptances), an action's goal union already carries the first-class `cancelled` state (the retirement attribution rides its digest-bound payload), the cancel publishes CREATE-ONLY on the SAME completion subject so first-terminal-wins is structural in both directions, and a third per-op principal (`local.epcan_<opId-hash>`, one exact completion-subject create row) executes the mediator-derived repair \u2014 so a retirement with in-flight accepted effects work now COMPLETES on resume with a reader-legible cancelled terminal instead of freezing. An eleventh round (the despawn\u2192retirement trigger, the P1 closure) reserved the `auth-admin` control service (SPEC 13.2): the AUTH plane serves the GENERIC \"retire a lifecycle\" operation on the `ctl` grammar's subject-attributed rail (the delivery-admin discipline: broker-ACL caller attribution, bound replies, an unbound reply target dropped before processing), authorized at SERVE TIME by the fresh space-manager-lease holder check (one leader-served read of the manager bucket's single lease key; holder == the subject-attributed requester principal; DEL/PURGE markers and TTL-expunged rows read absent and refuse fail-closed \u2014 never mint-time trust, closing the post-lease-loss window), answering the four-outcome idempotence table in operator vocabulary with every refusal a stated COMPLETE no-op; the space manager triggers it per despawn through an ephemeral request-and-reply-only `retirement-requester` credential with a STABLE per-lifecycle opId (retries, same-name-spawn nudges, and boot resumes converge on one operation), holds the despawned name RESERVED-pending-retirement until the terminal (a same-name spawn refuses legibly and re-drives the request; the in-memory reservation's restart residual is named \u2014 the durable truth is the lifecycle head itself), and the retirement executes through the plane's own reviewed deps over its ONE sealed records scanner. The barrier's terminal cleaner/executor pool set is the operation's EFFECTIVE INVENTORY: the target's accepted `oblig.<uid>.>` pool routes discovered from the just-drained obligation set UNIONED with the intent's OPTIONAL trusted hint (the despawn rail passes none), superseding the round-8 \"intent's exact pools\" enumeration so an empty-hint despawn still settles every accepted pool item before the frontier; the durable-intent hint is a TRUSTED ADDITIVE AUTHORITY input (a hinted pool with no accepted obligation still receives a bounded per-op credential), and the compromised cleaner/executor residuals scope to that whole effective inventory, including any hint-only pool. |\n| 2026-07-10 | **v0.4 binding revision: endpoint control surface (\xA713).** One standardized typed surface for every endpoint (manager, delivery, wrapped third-party servers): class/instance/scatter rails with per-command broker enforcement and an authorization-mode gradient, lifecycle identity (recyclable alias + never-reused lifecycle UID + fenced process epoch, \xA713.1, \xA72/\xA76/\xA78 extensions), versioned envelope with structured errors and signed slots, three delivery contracts (ephemeral, split-key records, untrusted submissions \u2192 mediated canonical facts), verbs call/cast/watch/claim/scatter (claim owner-mediated: workers hold no pool grant), composites (action, checkpoint, guard, capability handle with redemption-pinned `handle`-mode targets, session, virtual endpoints), content-addressed cluster contracts + governed traits + describe, the ownership matrix (incl. exact reader/consumer/ack rows and pinned consumer-name grammars), takeover/retirement revoke-and-evict barriers over the full ledgered credential family (credential ledger, \xA713.1), mediated timer arming (request/armed/fire split with a scheduler-origin fire check), poison quarantine facts, an epoch-pinned record-write ingress plane (`epr`), a single-message digest-subject contract store (`epc`), pre-created pull-only reader consumers (no dynamic reader creates: a create's delivery target is body-set and unconfined), an alias CAS head for lifecycle activation, and receipts and trust anchors. **Hard cut:** deletes the v0 `ctl` rail, `ControlRequest`/`ControlReply`, the `self`/`manager`/`admin`/`delivery-admin` tiers, and the reserved `control.<instance>` subject. `protocolVersion` targets `0.4` at migration completion; `1.0` stays reserved as a later stability declaration. |\n| 2026-07-07 | Documentation revision, no wire change: layered authority statement (schema authoritative for shapes, prose for semantics), document-snapshot policy and this change log (\xA711), reciprocal links to the informative docs. |\n| 2026-07-03 | **v0.3 binding revision: owner+actor identity.** The wire identity becomes the two-token principal `(owner, actor)`: subjects carry the sender as `<owner>.<actor>`, and grants, durables, presence, and `from.id` re-key onto the pair (\xA72, \xA73, \xA76, \xA78, \xA79). The connection nkey remains only the transport credential (the per-connection reply inbox). Adds the per-user-auth authorization grammar and the owner-token format (\xA72, \xA79). Supersedes the single-id grammar. |\n| 2026-06-21 | **v0.3 binding revision: channel live delivery.** Channel live delivery moves from the mediated per-instance live-tail durable to native `sub.allow`-bounded core subscriptions, with an explicit per-channel `live`/`durable` delivery class and the per-member durable backstop (\xA74, \xA77, \xA78); membership moves to a privileged-written registry (\xA77). Supersedes the v0.2 single-durable live-tail. |\n| earlier | v0.2 and before predate change control: the v0.2 contract (single mediated live-tail durable binding) is superseded by v0.3 and kept only in history. |\n"
+    "body": "# Cotal Wire Specification\n\n> **Status:** Draft, v0.5 (pre-1.0). This document is the normative wire contract. Libraries\n> (including the reference TypeScript implementation) are thin clients over it; where a\n> client disagrees with this document, this document wins.\n>\n> **Layered authority.** Message *shapes* are defined by the machine-readable schema,\n> [`spec/cotal.schema.json`](spec/cotal.schema.json) (\xA75); this document's prose defines\n> *semantics*: routing, delivery guarantees, presence, authorization, and conformance. For\n> the reference implementation's operator surfaces (the CLI, the `cotal_*` tools), see the\n> [Reference docs](docs/README.md#reference); those describe the TypeScript implementation,\n> not this contract.\n>\n> **Editors:** Cotal maintainers. **Last updated:** 2026-09-22. Changes are tracked in\n> [Appendix D](#appendix-d-change-log); versioning rules are \xA711.\n>\n> **v0.5 binding revision: workflow runs.** A deployment MAY host **durable workflow runs**: programs\n> in the Cotal workflow language ([`spec/cotal-lang.md`](spec/cotal-lang.md), normative and\n> incorporated by reference) whose every effect is recorded in a per-run **step journal** so a run\n> resumes on any host by re-execution against its journal (\xA714). The revision adds one per-space\n> stream (`WFJ_<space>`, one subject per run, an append-only journal fenced by the run's own subject\n> sequence), four core record kinds (`run`, `answer`, `notice`, `migration`), a per-run driver grant\n> family, and the language reference; it changes no existing kind, subject, grant row or shipped\n> datum, so it is **additive** under \xA711: a v0.4 participant that ignores \xA714 conforms to v0.4\n> unchanged, and the advertised `protocolVersion` targets `0.5` once the v0.4 migration completes and\n> the \xA714 plane is served. Language semantics carry their own version (`languageVersion`, pinned on\n> every run record) and move independently of the wire version.\n>\n> **v0.3 binding revision: owner+actor identity.** An instance's wire identity moves from a single\n> id (the connection nkey, used as the sender token everywhere) to a two-token **principal**\n> `(owner, actor)` (\xA72): the human/account owner and the agent actor become distinct routing tokens,\n> so every subject carries the sender as `<owner>.<actor>` (\xA73), and grants, durables, presence, and\n> `from.id` re-key onto the principal (\xA76, \xA78, \xA79). The connection nkey survives only as the transport\n> credential, keying the per-connection reply inbox `_INBOX_<connId>` (\xA72, \xA710); the wire identity and\n> the connection credential are now distinct. Cross-owner **and** same-owner cross-actor forge/read\n> isolation is a normative confinement property (\xA79). `parseSubject` splits the tokens; a well-formed\n> split is necessary but not sufficient: a reader additionally rejects a non-principal owner token\n> (e.g. an old-shape alias carrying a raw nkey) at the surfacing boundary (\xA73, \xA79). The owner-token\n> *format* (`u_` + 26 base32-lower) is normative; its *derivation* from an owner's identity (login \u2192\n> auth callout, or another identity adapter) is a pluggable edge, not fixed by this contract. This\n> supersedes the v0.2/early-v0.3 single-id grammar. As with the live-delivery revision, the advertised\n> wire `protocolVersion` (\xA76, \xA711) is the migration's normative target, not a claim that every surface\n> has cut over.\n>\n> **v0.4 binding revision: endpoint control surface.** Structured command traffic moves from the v0\n> `ctl` control rail to one standardized, typed, discoverable endpoint surface (\xA713): class +\n> instance + scatter rails with per-command broker enforcement, a versioned envelope, three\n> delivery contracts (ephemeral / record / journal), normative composites (action, checkpoint,\n> guard, capability handle, session), content-addressed contracts with governed traits, and\n> lifecycle identity (\xA713.1) extending \xA72/\xA76/\xA78. This is an intentional **hard cut** (\xA711,\n> \xA713.11): the v0 control grammar, envelope, and authority tiers are deleted, not dual-served.\n> The advertised `protocolVersion` targets `0.4` at the completion of this revision's migration;\n> `1.0` remains reserved as a later stability declaration, not part of this revision.\n>\n> **v0.3 binding revision: channel live delivery.** Channel *live* delivery moves from a single\n> mediated JetStream live-tail durable (`chat_<id>`) to native core-NATS subscriptions bounded by\n> `sub.allow`, with durability provided by an explicit per-channel `live`/`durable` delivery class\n> (\xA74, \xA77, \xA78). Join/leave becomes a direct subscribe/unsubscribe with no privileged mediation,\n> and channel membership moves off consumer topology to a privileged-written registry (\xA77). This\n> supersedes the v0.2 single-durable live-tail. The reference implementation migrates additively\n> (the legacy durable and the new core-sub path coexist behind `id` dedup until the legacy path is\n> removed), but that migration path is not itself normative. The advertised wire `protocolVersion`\n> (\xA76, \xA711) stays `0.2` until the core-sub behaviour ships; this revision is the normative target the\n> migration converges to, and the additive `deliveryClass` field is backward-compatible meanwhile.\n\nThe key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, MAY, and OPTIONAL in\nthis document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)\nand [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174).\n\nSections 3 to 7 define the transport-agnostic Cotal contract. Sections 8 to 10 define\nthe NATS + JetStream binding (v0). A conformant deployment implements one binding; the\nNATS binding is the only one defined today. External specifications this document relies on\nare listed in Appendix C.\n\n---\n\n## 1. Scope and terminology\n\nCotal is a wire interface for software, especially AI agents, to coordinate in real time\nas lateral peers in a shared pub/sub space, not as nodes in an orchestrator tree.\n\n- **Space**: an isolated coordination context. One space is one tenant boundary; messages\n  in one space are not visible in another. NATS binding: one space = one account.\n- **Instance**: a connected participant, identified by a stable **instance id**. Also called\n  an endpoint.\n- **Agent node**: an instance whose `kind` is `agent`, versus a plain `endpoint` such as an\n  observer, logger, or dashboard.\n- **Peer**: any other instance in the same space.\n- **Channel**: a named multicast topic within a space, dotted and hierarchical.\n- **Service**: an anycast role reached by name (`svc`, \xA74).\n- **Endpoint (control surface)**: a daemon that registers a service identity, publishes\n  typed contracts, and serves commands on the endpoint rails (\xA713).\n- **Broker**: the message router for a space. v0 assumes a single trusted broker.\n- **Delivery message**: a multicast, unicast, or anycast `CotalMessage`.\n- **Endpoint request**: a typed request/reply command addressed to an endpoint class or\n  instance on the `ep` rails (\xA713). The v0 `ctl` control rail is deleted (\xA713.11).\n\n---\n\n## 2. Identity\n\nAn instance's wire identity is a **principal** = a pair of routing tokens `(owner, actor)`:\n\n- **`owner`**: the account that owns the instance: the human (or organization) an agent acts on\n  behalf of. In an authenticated deployment it is a derived **owner token** (`u_` followed by 26\n  base32-lower characters), a namespaced, nkey-disjoint token deterministically derived from the\n  owner's stable identity (e.g. an IdP subject) by the deployment's identity adapter; the wire\n  contract fixes the token *format*, not the derivation mechanism, which is a pluggable edge. In open\n  dev mode the owner is the literal `local`.\n- **`actor`**: the instance's own handle within that owner (its agent id). Distinct actors under one\n  owner are distinct principals and are confined from one another (\xA79), so one human's two agents\n  cannot forge or read as each other.\n\nEach token is sanitized to `[A-Za-z0-9_]` (see \xA73) with `-` additionally reserved as the form\nseparator, so a principal has two unambiguous serializations: the **dot-form** `<owner>.<actor>` and\nthe **dash-form** `<owner>-<actor>`. The same principal MUST appear identically as: the\n`AgentCard.id` (\xA76, dot-form), the sender tokens in subjects (\xA73), the message `from.id` (\xA75,\ndot-form), the presence key (\xA76, dot-form), and the per-instance durable names (\xA78, dash-form).\n\n**The principal is distinct from the connection credential.** In the authenticated NATS binding the\nconnecting user is still an Ed25519 nkey (base32, 56 chars, prefix `U`, e.g. `UAQG...`), stable for\nthe lifetime of the connection, but it is **not** the wire identity. The nkey authenticates the\ntransport and scopes only the per-connection reply inbox `_INBOX_<connId>.>` (\xA710); the principal\nthat keys every subject, grant, and durable is carried by the minted grant, not by the nkey. This\nseparation is what lets a login (\xA79) mint a fresh connection whose nkey the client never sees while\nthe principal stays stable across reconnects.\n\n- A client that authenticates with a static credential MUST adopt the principal that credential's\n  grant names; if a principal is also set explicitly (via the card) it MUST match, else the client\n  MUST fail before publish.\n- A client that authenticates through the auth callout (user mode, \xA79) cannot know its connection\n  nkey before connecting, so it chooses its own reply-inbox nonce (`connId`) and derives its\n  principal from its bearer; the broker's minted grant, not the client's self-read, is the\n  boundary.\n- Open dev mode MAY use `local` as the owner and an opaque stable actor, but open mode is outside\n  the security claims in \xA79 and is not a conformant authenticated deployment.\n\nFuture binding, not v0: portable `did:key` identity plus signed envelopes so authenticity\nsurvives an untrusted relay. See the threat model in [docs/security.md](docs/security.md).\n\n---\n\n## 3. Subject layout\n\nEvery wire subject is rooted at `cotal.<space>`. `<space>` and every routing token are\nsanitized: any character outside `[A-Za-z0-9_-]` maps to `_`. Sanitization is lossy; tokens\nMUST NOT be decoded back into display names.\n\nThe **sender** of every delivery is a principal (\xA72), carried as **two adjacent tokens**\n`<owner>.<actor>`. Routed kinds (`inst`) also carry the recipient principal as two tokens.\n\n| Purpose | Subject | Sender tokens | Delivery |\n| --- | --- | --- | --- |\n| Multicast | `cotal.<space>.chat.<owner>.<actor>.<channel...>` | 3\u20134 | \xA74 multicast |\n| Unicast | `cotal.<space>.inst.<recipOwner>.<recipActor>.<sndOwner>.<sndActor>` | 5\u20136 | \xA74 unicast |\n| Anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` | 4\u20135 | \xA74 anycast |\n| Endpoint rails | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026`, `cotal.<space>.ep<c\\|e\\|f\\|j\\|r\\|t\\|w\\|s>.\u2026` | see \xA713.2 | \xA713 control surface |\n| Plane liveness | `cotal.<space>.live.<plane>.<owner>.<actor>` | 4-5 | \xA76.1 request/reply |\n| Trace | `cotal.<space>.trace.<instance>` | n/a | reserved |\n\nToken indexing is zero-based on `subject.split(\".\")`: `cotal` = 0, `<space>` = 1,\n`<kind>` = 2. The sender principal is recovered as the dot-form `<owner>.<actor>` (= the message\n`from.id`, \xA75), so a guard comparing `from.id` to the subject sender uses one value.\n\n**Two-token sender, and its asymmetry.** A reader MUST locate the sender by kind:\n\n- `chat`: sender owner at token 3, actor at token 4; the channel is everything after, tokens 5+,\n  so it may be hierarchical (`team.backend`).\n- `svc`: route target at token 3; sender owner at token 4, actor at token 5.\n- `ep`: per-mode arities with the caller as the trailing identity tokens; \xA713.2 defines them.\n- `inst`: recipient owner+actor at tokens 3\u20134; sender owner+actor at tokens 5\u20136.\n\nThe two-token sender is what lets a native publish grant **forge-lock** the sender suffix (e.g.\n`inst.*.*.<myOwner>.<myActor>` permits a DM to anyone but only *as me*), so the broker enforces\nsender authenticity and a receiver need not re-verify a payload claim. A subject that does not match\none of these shapes (wrong prefix or wrong per-kind arity) MUST be treated as having no sender and\nMUST NOT be read as a delivery. `parseSubject` **splits only**: it recovers the tokens but does not\nvalidate that `<owner>` is a well-formed owner token; trust comes from the broker's forge-locked\ngrant, and a reader that surfaces content additionally rejects a non-principal owner token at the\nsurfacing boundary (\xA79). Reference implementation: `parseSubject` in\n`packages/core/src/subjects.ts`.\n\n**Channel tokens.** A channel is dotted; each segment is sanitized. The literal wildcards\n`*` and `>` are preserved only as whole segments for subscription and allow-list patterns;\n`>` is valid only as the final segment. A publish target MUST be concrete, with no `*` or\n`>`; a subscription MAY be wildcard. A channel is at most 4096 characters in total\n(`MAX_CHANNEL_LENGTH`): every grant line a channel mints rides the minted credential's\nCONNECT line (\xA713.9), so an unbounded channel is an unbounded connect.\n\n**Reserved prefixes.** Application messages MUST NOT use subjects beginning with `$JS.`,\n`$KV.`, `$SYS.`, `$O.`, or `_INBOX.`. (`$O.` is the Object Store data/meta subject prefix\nper ADR-20, `$O.<bucket>.C.>` / `$O.<bucket>.M.>`; `OBJ_<bucket>` is a stream NAME, not a\nsubject prefix.)\n\n---\n\n## 4. Delivery modes\n\n| Mode | Routing field | Semantics |\n| --- | --- | --- |\n| multicast | `channel` | delivered to every subscriber of the channel |\n| unicast | `to` | delivered to the named instance's inbox |\n| anycast | `toService` | delivered to one consumer of the named role |\n\nExactly one of `channel`, `to`, or `toService` MUST be set on a `CotalMessage` (\xA75).\n\n**Authenticated delivery kind.** A receiver MUST derive \"how was this addressed to me\"\nfrom the delivering subject kind (`chat` -> `channel`, `inst` -> `dm`, `svc` ->\n`anycast`), not from payload routing fields, which are advisory. (\"Delivery kind\", the\naddressing axis, is distinct from a channel's `live`/`durable` **delivery class**, \xA77.) A peer can put your id in\npayload `to`, but cannot publish on your private unicast subject. Reference:\n`MessageMeta.kind`.\n\n**Delivery guarantee: `live` and `durable` classes.** Channel delivery has two classes, fixed\nper channel and wire-observable (\xA77); the guarantee is defined here, its NATS realization is the\nbinding in \xA78. A receiver MUST derive its effective class from channel config (\xA77), not from\nper-message metadata (`MessageMeta` need not carry it); it MUST NOT assume one class.\n\n- **`live`** is native broker-subscription delivery and is **at-most-once**: a message reaches\n  only the instances subscribed to the channel at publish time. An instance that is disconnected,\n  busy, or not yet joined does not receive that message live and has no claim to the live copy\n  later. There is no per-subscriber redelivery of the live copy.\n- **`durable`** is `live` plus a per-subscriber durable backstop and is **at-least-once for\n  current members within retention**: the message is also retained for each member and delivered on\n  that member's next connection or turn, remaining pending until acked. A crash or `ack_wait` expiry\n  redelivers the durable copy. At-least-once is bounded by the channel's retention / `replayWindow`\n  (\xA77): a message evicted by retention before ack may be lost; the guarantee is not unbounded.\n\nUnicast (`to`) and anycast (`toService`) are at-least-once via their own DM/TASK consumers (\xA78);\nthey have no channel membership and are not subject to the per-channel delivery-class mechanism. An\n`@mention` (\xA75) on a `live` channel additionally writes a durable copy to each mentioned target\n**authorized to read that channel** (its `allowSubscribe` covers the channel), so an authorized but\noffline target still receives it; an `@mention` MUST NOT deliver channel content to a target outside\nits read ACL. Durable mention routing resolves each lowercased name to a unique current instance id\nfrom presence at publish time; an ambiguous (multiple live matches) or unresolvable name yields no\ndurable copy, and authorization is checked against the resolved id's current `allowSubscribe`. A\ntarget authorized for a channel is **mention-reachable** there whether or not it is currently joined; this is intentional (an `@mention` can pull an authorized peer in) and is distinct\nfrom membership; a client SHOULD distinguish \"joined\" (actively subscribed) from \"readable /\nmention-reachable\" (in `allowSubscribe`) so an unjoined channel is not treated as \"cannot reach me\nhere.\"\n\nA message delivered both live and durable is **one logical delivery**: receivers MUST deduplicate\nby `id` across classes (\xA78); the durable copy owns ack/commit; and a previously seen `id` MUST NOT\nbe treated as authorization for a later durable copy (for example one that arrives after a leave).\nReceiver deduplication MUST NOT use the empty string as a key. Two received messages MUST NOT be\ntreated as one logical delivery solely because both carry `id: \"\"`; each otherwise-deliverable\nmessage remains independently deliverable. Because live, backfill, and durable copies with\n`id: \"\"` cannot be correlated by wire identity, an at-least-once path may surface the same logical\nmessage more than once. The existing \xA75 obligation for publishers to supply a unique string id is\nunchanged. An absent or non-string id remains a malformed envelope.\nReceivers MUST tolerate the `live` gap and rely on the `durable` backstop for catch-up on\n`durable` channels. Malformed JSON, spoofed sender payloads, and unparseable delivery subjects are\npermanent anomalies and MUST be terminated, not retried.\n\n**Ordering.** Cotal does not define global ordering across modes, channels, or consumers.\nImplementations MUST NOT depend on cross-subject ordering. Per-consumer delivery is ordered\nby the backing stream except where redelivery or explicit backfill interleaves older\nmessages.\n\n---\n\n## 5. Envelopes\n\nDelivery messages are UTF-8 JSON objects with this shape (`CotalMessage`):\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `id` | string | MUST | unique message id; NATS binding also uses it as `Nats-Msg-Id` |\n| `ts` | number | MUST | epoch ms |\n| `space` | string | MUST | space name |\n| `from` | `EndpointRef` | MUST | `{ id, name, role? }` |\n| `channel` | string | one-of | multicast target |\n| `to` | string | one-of | unicast target instance id |\n| `toService` | string | one-of | anycast target role |\n| `mentions` | string[] | MAY | lowercased peer names; wakes the mentioned peer. On a `live` channel it also routes a durable copy to each mentioned target authorized to read that channel (\xA74); it never delivers content outside the target's read ACL and is not a routing substitute for `channel`/`to` |\n| `parts` | `Part[]` | MUST | content |\n| `replyTo` | string | MAY | id of the message replied to |\n| `contextId` | string | MAY | thread/conversation correlation id |\n\n`Part` is one of the three core shapes, or an extension object whose `kind` is namespaced\nas described in \xA711:\n\n- `{ \"kind\": \"text\", \"text\": string }`\n- `{ \"kind\": \"data\", \"data\": <any JSON value> }`\n- `{ \"kind\": \"artifact\", \"name\": string, \"mediaType\": string, \"digest\": string, \"size\": number }`\n- `{ \"kind\": \"<reverse-DNS extension kind>\", ... }`\n\nA `data` part's `data` MUST be a JSON value at every depth; a publisher MUST refuse the part\nrather than serialize a value JSON cannot represent, naming the offending member's path (a\ntop-level `undefined` serializes to a keyless `{\"kind\":\"data\"}` object, and `NaN`, a `Date`,\nor a class instance would be silently rewritten rather than refused).\n\nAn `artifact` part REFERENCES bytes held outside the message. `digest` MUST be\n`sha256:<lowercase hex>` over the raw bytes and is the artifact's identity; the part carries no\nlocation, so resolution is the receiver's. `name`, `mediaType`, and `size` are the publisher's\nclaims: a receiver MUST NOT allocate from `size`, and MUST verify fetched bytes against `digest`\nbefore use.\n\n`EndpointRef` is `{ \"id\": string, \"name\": string, \"role\"?: string }`.\n\nOn receive, a client MUST verify `from.id` equals the subject sender (\xA73). On mismatch, a\nmissing `from`, or an unparseable delivery subject, the message MUST be rejected and never\nredelivered.\n\nEndpoint requests and replies (the control surface) use the versioned typed envelope of\n\xA713.3 (`EndpointRequest`/`EndpointReply`); they are not Cotal delivery messages. The v0\n`ControlRequest`/`ControlReply` shapes are deleted (\xA713.11).\n\nReceivers MUST ignore unknown object fields. Unknown conformant extension `Part.kind` values\nMUST be ignored unless the receiver explicitly supports that extension. Bare unrecognized\ncore-kind values are not conformant. Messages MUST fit the broker's configured maximum payload;\nbytes that do not fit move out of the message and are referenced by an `artifact` part (above).\nThe transport that serves those bytes is not defined by this document.\n\n**Schema.** The JSON Schema (draft-07) at\n[`spec/cotal.schema.json`](spec/cotal.schema.json) is **authoritative for message shapes**:\na conformant delivery message MUST validate against it, and where this document's field\ntables and the schema diverge on a shape, the schema wins. Delivery *semantics* (routing,\nguarantees, rejection) are defined by this document's prose. The schema is generated from\nthe reference source, [`packages/core/src/types.ts`](packages/core/src/types.ts)\n(`pnpm gen:schema`), and committed; the published copy lives at\n`https://docs.cotal.ai/cotal.schema.json`.\n\n**Rejection reasons.** The three permanent anomalies in \xA74 are terminated, never redelivered.\nThese reason tokens are advisory (for logs and error surfaces); the action is uniform:\n\n| Reason | Trigger |\n| --- | --- |\n| `malformed-subject` | the delivery subject does not parse (\xA73) |\n| `sender-mismatch` | `from` is missing, or `from.id` does not equal the subject sender (\xA75) |\n| `malformed-json` | the payload is not valid UTF-8 JSON |\n\n---\n\n## 6. Presence and discovery\n\nPresence is a per-space directory keyed by instance id. NATS binding: JetStream KV bucket\n`cotal_presence_<space>` (\xA78).\n\n`Presence`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `card` | `AgentCard` | MUST | identity record |\n| `status` | `PresenceStatus` | MUST | `idle`, `waiting`, `working`, or `offline` |\n| `condition` | `PresenceCondition` | MAY | harness-reported structured condition. Missing means nothing was reported. A connector relays the harness signal and MUST NOT infer a condition itself |\n| `environment` | string | MAY | opaque reference whose meaning belongs to the provider that issued it. Core MUST NOT parse it |\n| `activity` | string | MAY | freeform current activity |\n| `statusSince` | number | MAY | epoch ms when the instance entered its current `status` and `activity`. A change to either moves it; a heartbeat or a repeated report does not, so `ts` dates liveness and `statusSince` dates the report. An offline record MUST NOT carry it: an observer that derives `offline` from a stale `ts` does not know when the peer left |\n| `activitySince` | number | MAY | epoch ms when the current `activity` was set. A status change or a heartbeat does not move it, so an activity left behind while the status flips every turn still reads as old |\n| `activeAt` | number | MAY | epoch ms of the last work progress the harness reported, such as a token or a tool call. Missing means the connector reports none. `ts` is the heartbeat, so a live instance whose turn stopped advancing keeps a fresh `ts` and an old `activeAt`. A connector relays the harness's events and carries the value on its next heartbeat |\n| `attention` | `AttentionMode` | MAY | global attention mode: `open` \\| `dnd` \\| `focus`. Advisory observability; `open`/absent \u21D2 receives everything. Reset: `open` published on `SessionStart`, removed on the offline sweep |\n| `lifecycleUid` | string | MUST in auth mode from v0.4 | the current managed-lifecycle UID (\xA713.1); distinguishes a live instance from a same-name successor. Advisory for display; authority checks use the trusted lifecycle mapping, not presence |\n| `channelModes` | `Record<string, ChannelMode>` | MAY | per-channel attention overrides (`ChannelMode` = `quiet` \\| `muted`), keyed by concrete channel name. Advisory, **not** access control (the broker still authorises and delivers); a receive-side preference, reset on restart |\n| `ts` | number | MUST | epoch ms of last heartbeat |\n\n`AgentCard`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `id` | string | MUST | instance id (\xA72) |\n| `name` | string | MUST | display name; at most 128 characters (`MAX_NAME_LENGTH`, refused at the shared validator; an unbounded name rides the CONNECT line until the broker drops it silently, \xA713.9) |\n| `kind` | `agent` or `endpoint` | MUST | participation class |\n| `role` | string | MAY | service role |\n| `description` | string | MAY | one-line summary |\n| `tags` | string[] | MAY | capability tags |\n| `skills` | `AgentSkill[]` | MAY | `{ id, name, description? }` |\n| `meta` | object | MAY | free-form display metadata. Reserved flat string keys are `connector` (host harness name), `model` (pinned model), `provider` (effective provider serving the model, connector-reported), `host` (self-reported machine), `cwd`, `repo`, `branch`, `head`, `sessionKind`, and `sessionId`. All are advisory only |\n| `protocolVersion` | string | MUST from v0.4 | wire version spoken (\xA711); `\"0.4\"` for this revision. Advertisement is the marker at the v0.4 reachability boundary (\xA713.11): a participant that omits it is pre-0.4 (omission means the pre-0.4 line, where the field was optional) and MUST NOT be addressed on the `ep` rails. A change signal, not negotiation |\n\nAn instance MUST refresh its own presence entry on the heartbeat interval, default 2000 ms.\nThe liveness window defaults to 6000 ms. A peer whose `ts` is older than the liveness window\nis considered `offline`.\n\nLive clients MUST NOT heartbeat as `offline`. A graceful disconnect MAY publish one final\n`offline` presence record. Observers MUST also derive `offline` from stale timestamps and\nfrom KV delete/purge events. Offline peers MAY remain in local rosters for observability.\nAn instance MUST write only its own presence key, and the key MUST equal `card.id`.\nReaders MUST drop a record whose `card.id` differs from its KV key, whose `card.name` or\n`status` does not have the type given above, or whose `ts` is not a finite number, and SHOULD\nreport the rejection on their recoverable diagnostic path. A reader that kept a record whose\n`ts` is missing or text such as `\"nope\"` could not age it past the liveness window, so it would\nshow its peer live after the key expired.\n\n`PresenceCondition`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `code` | `PresenceConditionCode` | MUST | `rate_limit` \\| `overloaded` \\| `auth` \\| `billing` \\| `budget` \\| `context` \\| `model` \\| `request` \\| `server` \\| `retrying` \\| `approval` \\| `input` \\| `failed` |\n| `source` | string | MAY | harness-native value, relayed verbatim |\n| `message` | string | MAY | free text from the harness |\n| `since` | number | MAY | epoch ms when the condition began |\n\n### 6.1 Plane liveness\n\nA credentialed peer MAY ask whether the manager plane or the delivery plane has a bound\nresponder in its space. The question is presence only. It does not read either lease bucket,\nand the peer does not need to own the plane it asks about.\n\n**Planes.** The set of planes is closed: `manager` and `delivery`. A client MUST refuse any\nother plane before it publishes anything.\n\n**Subjects.**\n\n| Purpose | Subject |\n| --- | --- |\n| Request | `cotal.<space>.live.<plane>.<owner>.<actor>` |\n| Reply | `cotal.<space>.live.<plane>.<owner>.<actor>.reply.<nonce>` |\n| Responder serve filter | `cotal.<space>.live.<plane>.*.*`, queue group `live.<plane>` |\n| Responder reply grant | `cotal.<space>.live.<plane>.*.*.reply.>` |\n\n`<owner>.<actor>` is the asking principal (\xA72). The plane rides the subject so a credential can\nbe scoped to one plane by the broker. A `live` subject is not a delivery: `parseSubject`\nrecovers no sender from it, and a reader MUST NOT treat it as one.\n\n**Request.** The body is empty. The caller names a reply subject under its own request subject,\n`<request>.reply.<nonce>`, with a fresh nonce per probe. A responder MUST drop, without\nanswering, any request whose reply target is absent or is not under `<request subject>.reply.`.\nIt SHOULD report that drop on its recoverable diagnostic path. It MUST NOT report it on a\nchannel that can end the process, and it keeps serving.\n\n**Reply.** `LivenessAnswer`, JSON:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `plane` | `manager` \\| `delivery` | MUST | the plane asked about; a caller MUST reject a reply whose `plane` differs from the plane it asked |\n| `responder` | `ResponderState` | MUST | `bound` \\| `unbound` \\| `stale` \\| `unknown` |\n| `instance` | string | MAY | an opaque token naming the responder that answered. Non-empty when present |\n\nA responder MUST put nothing else in the reply. In particular it carries no lease holder, pid,\nworkspace path, instance id, runtime or roster.\n\n`instance` is minted fresh each time a responder binds and is derived from nothing. It is not\nthe endpoint's principal, the lease row's `instanceId`, a pid, a host or a path. It lets a\ncaller that probes more than once tell two responders apart from one responder whose state\nchanged. The queue group hands one probe to one member, so a single answer samples one\nresponder and cannot report a split across instances.\n\n**Responder verdicts.** A responder grades only itself:\n\n- manager: `bound` while its v0.4 service endpoint (\xA713) is serving, otherwise `unbound`. A\n  closed service connection is not serving, including while the manager re-dials it. A\n  disconnected one is not serving either, including while the client reconnects it.\n- delivery: from its own shard lease row. Absent or not ready is `unbound`. A ready row held by\n  a different instance than the responder is `stale`. A ready row it holds is `bound`.\n- A responder that cannot determine its state answers `unknown`.\n\n**Rebinding.** A responder MUST bind its serve filter again on every broker connection that\nreplaces the one it bound on. A filter left on a closed connection gets the broker's\nno-responders answer, which a caller grades `unbound` for a plane that is still served. Each\nnew bind mints a new `instance`.\n\n**Caller grading.** The caller grades the outcome of asking:\n\n| Outcome | `responder` | `instance` |\n| --- | --- | --- |\n| a reply that parses as above | the reply's `responder` | the reply's `instance`, if any |\n| the broker's no-responders status (503) | `unbound` | absent |\n| timeout, permission refusal, transport failure | `unknown` | absent |\n| a reply that does not parse | `unknown` | absent |\n\nOnly the broker's no-responders answer yields `unbound` without a reply. Every other failure\nto get a readable reply is `unknown`. A caller MUST NOT report `unknown` as either health\nstate. A caller using the NATS binding MUST request without the muxed inbox, so a\nno-responders status reaches it rather than surfacing as a timeout.\n\n**Grants.** An agent may publish the request subject for each plane under its own principal\nand subscribe `<request subject>.>` for its replies. It holds neither serve filter, so it\ncannot answer for a plane. The `delivery` profile holds the delivery plane's serve filter and\nreply grant. The `supervisor` profile holds the manager plane's pair, and the remote-manager\nprofile holds them only for its supervisor actor (`manager_<instanceId>`). No responder can\npublish a request subject, because its reply grant stops at the `.reply.` leaf. Appendix B\nlists the agent rows.\n\nReference implementation: `livenessSubject`, `livenessServeFilter` and `livenessReplyGrant`\nin `packages/core/src/subjects.ts`; `LivenessAnswer`, `parseLivenessAnswer` and\n`responderFromProbe` in `packages/core/src/liveness.ts`; `CotalEndpoint.serveLiveness`,\n`serveDeliveryLiveness` and `probeLiveness` in `packages/core/src/endpoint.ts`.\n\n---\n\n## 7. Channels\n\nA channel is addressable as soon as it is published to. Channel config is optional and lives\nin the per-space registry bucket `cotal_channels_<space>`, keyed by the concrete channel\ntoken.\n\n`ChannelConfig`:\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `replay` | boolean | history replay-on-join; overrides the space default |\n| `replayWindow` | string | backfill horizon matching `^\\d+(s\\|m\\|h\\|d)$`, e.g. `\"24h\"` |\n| `deliveryClass` | `live` \\| `durable` | per-channel delivery class (\xA74); overrides the space default |\n| `description` | string | one-line purpose; max 200 chars |\n| `instructions` | string | advisory usage text; max 2000 chars |\n\nSpace-wide defaults (`ChannelDefaults`: `replay?`, `replayWindow?`, `deliveryClass?`) live under\nthe reserved key `=defaults`. Effective replay is `channel.replay ?? defaults.replay ?? true`.\nEffective delivery class is `channel.deliveryClass ?? defaults.deliveryClass ?? \"durable\"`.\n`defaults.deliveryClass` MUST be written at space creation from the deployment profile\n(local/self-hosted \u21D2 `durable`, persistence on by default; public/web-scale \u21D2 `live`, durability\nopt-in per channel), so the effective default is always discoverable on the wire, never inferred\nfrom out-of-band context. The same effective config MUST be the single source of truth for live\njoin, durable fan-out, history read, and membership surfacing; an implementation MUST NOT resolve\nthe class differently in different paths.\n\nJoin subscribes the instance to the channel; leave unsubscribes it. A join target MUST be within\nthe instance's read ACL (`allowSubscribe`, \xA79); a join outside it MUST be refused by the broker on\nsubscribe. A client MUST NOT publish to wildcard channels, but a wildcard read ACL (`team.>`)\nauthorizes subscribing to any one concrete channel under it **without enumerating channels in\nadvance**. In the NATS binding, join is a native `sub.allow`-bounded core subscription to the\nchannel subject and leave is the corresponding unsubscribe; **no privileged mediation is\nrequired**: the broker enforces every subscribe against `sub.allow`, so an instance whose ACL\npermits a channel joins and leaves it on its own, with no manager present. Open mode behaves the\nsame (the client subscribes directly). Leaving the last channel is permitted: under the core-sub\nbinding an empty subscription set subscribes to nothing (the v0.2 \"empty filter subscribes to all\"\nhazard and its last-channel-leave refusal were artifacts of the multi-filter durable and no longer\napply). On a `durable` channel, join additionally establishes durable membership, a separate\n**privileged** step: the instance requests durable membership from the server-side delivery daemon (a\ndurable-join command on the `delivery` endpoint, \xA713, carrying the channel and its captured join\ncursor) and the daemon writes the membership record. This is decoupled from the live subscribe, so a self-serve live join never depends\non it: a `durable` channel still delivers live with no privileged writer present, and only its\ndurable backstop requires one. A locally created subscription that the\nbroker later refuses (the permission violation is asynchronous in the NATS binding) is NOT a\nsuccessful join: an instance MUST treat a join as effective only once the broker has accepted the\nsubscribe, and MUST drop the channel from its joined set on a late refusal (\xA712). Leave removes the\nmembership (see membership below).\n\nReplay / catch-up on join:\n\n1. Record the channel join watermark (the CHAT frontier) before the subscription is active, so\n   live tail and backfill do not double-deliver.\n2. Subscribe to the channel subject (`sub.allow`-bounded; \xA78). The live copy now flows.\n3. If effective replay is on, read retained messages for that channel up to the watermark,\n   through a single-channel history read bounded by the current read ACL (`allowSubscribe`, \xA78),\n   optionally limited by `replayWindow`. History is ACL-bounded, not membership-gated: an ACL-holder\n   may read a channel's retained content whether or not it is a current member (it could self-join\n   and read regardless), so the confidentiality boundary here is the ACL, consistent with the live\n   read.\n4. Surface backfilled messages with `MessageMeta.historical = true`.\n5. Deduplicate by `id` across the live tail, the backfill, and (on `durable` channels) the durable\n   backstop, so a message surfaces once. Receiver deduplication MUST NOT coalesce copies solely\n   because `id` is the empty string (\xA74).\n\n   Informative: an implementation preserving an incarnation across a local restart may start step\n   3's read from the sequence that incarnation had reached, rather than from the retained window's\n   start; a fresh joiner reads the window.\n\n`replay=false` is noise control, not confidentiality. CHAT history is readable only within an\ninstance's read ACL (`allowSubscribe`, \xA79); confidential content MUST use DM or anycast.\n\nChannel membership governs **durable-delivery inclusion** (who receives fan-out copies into their\nper-subscriber backstop) and is broker-known, not self-reported. It is NOT a confidentiality\nboundary tighter than the read ACL: `allowSubscribe` bounds what content an instance may read (live\nand history, \xA79), and an ACL-holder can self-join, so membership adds delivery semantics, not read\nconfinement. In the NATS binding, membership is a privileged-written record in the space registry\nplane under a key the agent's profile cannot write (NOT the agent's presence key), carrying per-member\njoin/leave cursors so a publish concurrent with a join or leave orders deterministically; it is NOT\nderived from consumer topology, and an agent MUST NOT self-assert its own membership. It is written by\nthe server-side delivery daemon in response to a durable-join command on the `delivery` endpoint\n(\xA78, \xA713, Appendix B), distinct from and not required by the self-serve live subscribe. The implementation MUST re-authorize every\n**durable-backstop** read of `(instance, channel, message)` against the instance's current read ACL\nand membership before surfacing content, so a channel dropped from the ACL or **left** is no longer\nsurfaced from the backstop: **leave is a hard read boundary for the durable backstop** (it does not\nrevoke the ACL: an instance may still re-subscribe live, or read ACL-bounded history, within\n`allowSubscribe`). Membership remains observability data for liveness/roster purposes and MUST NOT be\nused as a send authorization gate.\n\nOn a `durable` channel, membership carries the member's **join cursor** (the CHAT frontier captured\nat join, the same watermark used to deconflict the live tail and the backfill) and, on leave, a\n**leave cursor/tombstone**. The durable backstop is at-least-once (within retention)\nfor messages whose stream sequence is **> the member's join cursor and \u2264 its leave cursor**, where each\ncursor is the CHAT frontier (the last sequence) captured at that transition; messages published before a\njoin or after a leave are not redelivered as durable and are reachable only via an ACL-bounded history\nread (within `allowSubscribe`). A rejoin takes a new join cursor, so messages published during the gap are not durably\nredelivered. A `durable` join is atomic across its two effects: the instance is durable-joined only\nonce BOTH the broker-confirmed live subscribe AND the membership write have succeeded, and on a late\nsubscribe refusal the membership record MUST be removed. If the live subscribe succeeds but durable\nmembership cannot be established (for example no privileged writer is present), the instance is\n**`joined live` with the durable backstop unestablished**: it MUST NOT be reported as `joined durable`,\nthe live subscription remains active, and the durable shortfall MUST be surfaced as an exceptional\ndelivery state (e.g. `durable backstop unavailable`), never silently.\n\n---\n\n## 8. NATS + JetStream binding\n\nBacking streams are created once at space setup. `STREAM.CREATE` is denied to agents in auth\nmode.\n\n| Stream | Captures | Retention | Required config |\n| --- | --- | --- | --- |\n| `CHAT_<space>` | `cotal.<space>.chat.>` | Limits | file storage, `max_msgs_per_subject=1000`, `discard=Old`, `allow_direct=true` |\n| `DM_<space>` | `cotal.<space>.inst.>` | Limits | file storage, no Direct Get |\n| `TASK_<space>` | `cotal.<space>.svc.>` | WorkQueue | file storage, no Direct Get |\n\nChannel **live** delivery is a native core-NATS subscription to `cotal.<space>.chat.*.*.<channel>`\n(wildcard sender owner+actor) bounded by `sub.allow` (\xA79), not a durable consumer; join/leave is the\nsubscribe/unsubscribe and needs no privileged mediation. The legacy v0.2 `chat_<owner>-<actor>`\nlive-tail durable is removed from this binding (it MAY coexist transiently during migration behind\n`id` dedup, but is not part of the contract).\n\nDurable consumers. Per-instance durables are keyed on the principal's **dash-form** `<owner>-<actor>`\n(a `.` is illegal in a durable name; see \xA72), so a durable name-scopes to exactly one principal:\n\n| Durable | Stream | Filter | Policy |\n| --- | --- | --- | --- |\n| `chathist_<owner>-<actor>-<uid>` | CHAT | one `cotal.<space>.chat.*.*.<channel>` per read | transient single-filter consumer for history reads (join-backfill / focus-recall); created per read scoped to one channel in `allowSubscribe`, then deleted; `AckNone`. History is ACL-bounded by the pinned filter, not membership-gated (\xA77, \xA79) |\n| `dm_<owner>-<actor>-<uid>` | DM | `cotal.<space>.inst.<owner>.<actor>.>` | provisioner-created in auth mode at lifecycle activation; bind only; `DeliverPolicy.ByStartSequence` with `OptStartSeq = activationFrontier + 1`, where the **activation frontier** is the DM-stream's last sequence captured at activation (`0` on an empty stream, so the start is `1`): `ByStartSequence` is inclusive and the lifecycle interval is half-open, so the consumer starts strictly AFTER the frontier, never `All`, which would replay a recycled alias's history and the inactive-gap backlog; `AckExplicit`; `ack_wait=60000ms` |\n| `svc_<role>` | TASK | `cotal.<space>.svc.<role>.>` | provisioner-created in auth mode; bind only; `AckExplicit`; `ack_wait=60000ms`. **Intentionally role-shared, not lifecycle-scoped**: anycast work belongs to the role, and successive holders draining one pool is the contract |\n\nFrom v0.4, each lifecycle's durable state lives in the **half-open interval**\n`(activationFrontier, retirementFrontier]` per stream: consumers start strictly after the\nactivation frontier (`OptStartSeq = frontier + 1`, table above; the frontier is captured\nAFTER any inactive alias gap), and terminal retirement records the\nretirement frontier before the alias is freed, so a successor lifecycle never receives the\npredecessor's pending backlog nor messages published while no lifecycle was active (\xA713.1).\n\nPer-instance durable names use the principal's dash-form `<owner>-<actor>` (both tokens\nfail-loud-validated, not lossily sanitized), so a durable name-scopes to exactly one principal (\xA72).\nThe authenticated wire identity is the principal, not the connection nkey. From v0.4, in auth mode,\nper-instance durable state is additionally **lifecycle-scoped** (\xA713.1): durable consumer names,\npending delivery cursors, membership rows, and ACL/ledger rows key on\n`(principal, lifecycleUid)` (dash-form `<owner>-<actor>-<lifecycleUid>`), terminal retirement\nrecords per-stream sequence cutoffs before an alias is reused, and a same-name successor\ninherits none of its predecessor's pending state: its consumers start after its OWN\nactivation frontier (which is \u2265 the predecessor's retirement cutoff), the cutoffs bound the\npredecessor's interval, they are never the successor's start.\n\n**Durable backstop (\xA74).** The per-subscriber durable copy is a delivery contract, not a pinned\nlayout: each member has a private durable store, written on publish for a `durable` channel's current\nmembers and, for an `@mention` on a `live` channel, for each mentioned target authorized to read that\nchannel (its `allowSubscribe` covers it), so an authorized but offline target still receives it. The\nagent holds **no content-bearing read** on this mixed store. A **trusted reader** (the server-side\ndelivery daemon) pulls each pending entry, re-authorizes `(instance, channel, message)` against the\nmember's **current read ACL** and, for `durable`-channel fan-out entries, its **membership interval**\n(the message's CHAT sequence is `> joinCursor` and `\u2264 leaveCursor`; \xA77), not a current-member boolean,\nso a pre-leave entry stays deliverable and a post-`leaveCursor` one does not,\nand delivers each authorized copy to the member over an **at-least-once** handoff (its own\n`dlv_<owner>-<actor>-<uid>` DELIVER consumer, carrying the same ack semantics, not a fire-and-forget publish). The trusted reader MUST NOT ack or\ndelete the backstop entry until the member has confirmed the copy was surfaced or handled (or it has\nbeen transferred to an equivalent per-member at-least-once mechanism with the same ack semantics); on a\ndownstream nak, timeout, or crash before that confirmation, the entry remains pending and redelivers, so\na crash between the `dlv` handoff and the member surfacing the message cannot lose it, and `durable`\nstays at-least-once end-to-end, not maybe-once. Content\nfor a channel dropped from the ACL, or (for a durable channel) left, is never surfaced (at-least-once for\nthe member within retention; **leave is a hard read boundary for the backstop**); a `live`-channel\n`@mention` copy is delivered and `id`-deduped the same way. The read MUST run in this trusted component\nthe agent cannot bypass, because a self-bound consumer has no server-side per-message ACL/membership\nfilter. The store's stream/subject layout, the fan-out writer, the trusted reader, and the membership\nregistry are reference-implementation, not normative; a conformant deployment MAY realize the backstop\ndifferently as long as the \xA74 guarantee and the \xA79 checks hold.\n\nThe absence of a usable receiver dedup key does not relax acknowledgement ownership: a\nJetStream-consumed copy with `id: \"\"` that is surfaced or handled MUST be acknowledged\nindependently. The reference fan-out and transfer publishes carry no `Nats-Msg-Id` for an\n`id: \"\"` message, so id-less messages are not publish-deduplicated on the durable plane.\n\nPublishers MUST publish channel, unicast, and anycast delivery messages through JetStream and set\nthe JetStream message id to `CotalMessage.id` (`Nats-Msg-Id` on the wire). A JetStream publish is\nan ordinary subject publish that the stream also captures, so the same message reaches core\nsubscribers live (\xA74 `live`) and is retained for history and the durable backstop in one publish;\nthe publish path is unchanged from v0.2; only the live *read* moves to a core subscription.\nAck/nak/term semantics apply to JetStream-consumed copies (history, DM, anycast, and the durable\nbackstop): receivers MUST ack only after a message has actually been surfaced or handled, MAY nak\ntransient failures, and MUST term permanently invalid messages. The at-most-once `live` copy is not\nacked.\n\nHistory on join uses the pinned single-filter `chathist_<owner>-<actor>-<uid>` consumer create above, bounded to\n`allowSubscribe`; agents are not granted unfiltered Direct Get. DM and TASK MUST NOT enable Direct Get\nbecause it would bypass the consumer-create deny that is part of the confidentiality boundary.\n\nKV buckets are also streams and are pre-created:\n\n| Bucket | Holds | TTL |\n| --- | --- | --- |\n| `cotal_presence_<space>` | presence (\xA76) | 6000 ms |\n| `cotal_channels_<space>` | channel registry (\xA77) | none |\n| `cotal_membership_<space>` | derived channel-membership feed (below) | none |\n\n**Derived channel-membership feed (observability).** `cotal_membership_<space>` is a per-agent\n(key = `card.id`) derived view of who is subscribed to each channel: the **union** of an agent's\n`live` core-subscriptions (read by a privileged daemon from the broker's connection view) and its\n`durable` memberships (the members registry), each value `{ live: string[], durable: string[],\nobservedAt }` with `live` keeping subscription patterns (wildcards) the consumer expands at read time.\nIt exists so an observer can show silent readers and `live`-channel membership without a broker-admin\ncredential in the dashboard tier; it is written by a scoped privileged daemon and read by the\nadmin/observer profile only. It is **DISPLAY-ONLY and broker-derived**: it MUST NOT be an input to any\ndelivery, ACL, or authorization decision (authority for those stays the broker's `sub.allow` and the\nmembers registry), and it is not part of the normative wire contract a client must implement.\n\n---\n\n## 9. NATS + JetStream security and authorization\n\n**On by default.** A space is provisioned with decentralized JWT auth. Open unauthenticated\ndev mode is available but out of scope for the security claims here. *(Informative\noperator-facing views of this section: [docs/identity-and-auth.md](docs/identity-and-auth.md),\n[docs/channels-and-permissions.md](docs/channels-and-permissions.md); the threat model is\n[docs/security.md](docs/security.md).)*\n\n- **Account = space, user = agent.** A space is one NATS account. The **broker's** operator signs\n  the account; an account signing key mints per-agent user JWTs. A broker (one nats-server trust\n  root: one operator, one system account) MAY host several spaces \u2014 one account per space, every\n  account signed by that one operator. Broker trust is therefore per-broker, never per-space: a\n  space owns only its own account and references the broker's operator, and rotating or replacing\n  broker trust is intrinsically broker-wide - it affects every tenant on the broker at once and\n  cannot be scoped to a single space.\n- **Profiles are default-deny allow-lists.** Subject, stream, durable, and KV names are built\n  from the same builders as \xA73 and \xA78. Exact profile shapes are in Appendix B.\n- **An agent's channel scope is three concepts**, each a list of channel names or wildcard\n  subtrees (`team.>`): `subscribe`, the active read set, the channels it subscribes to at boot\n  (now native core subscriptions; mutable at runtime by direct subscribe/unsubscribe with no\n  mediation); it MUST be a subset of `allowSubscribe`. `allowSubscribe`, the read **ACL**, the\n  channels it MAY read (default = `subscribe`), minted as native `sub.allow` subscribe grants over\n  `cotal.<space>.chat.*.*.<channel>` (wildcards preserved, so an open ACL needs no enumeration) and\n  as the matching per-channel history-consumer create grants. `allowPublish`, the post **ACL**,\n  the channels it may publish to; **default-deny** (a chat publish grant is minted only for a\n  declared channel).\n\nEvery grant below is keyed on the agent's **principal** `<owner>.<actor>` (\xA72), except the reply\ninbox, which is keyed on the **connection** `<connId>`: the connection nkey (static mode) or the\nclient-chosen nonce (user mode, \xA79). This is the one place the wire identity and the connection\ncredential diverge (\xA72): the principal keys subjects/durables/presence; the connId keys the inbox.\n\n| Profile | Application publish | Read surface | Notes |\n| --- | --- | --- | --- |\n| `agent` | own `chat.<owner>.<actor>.<ch>` for each `allowPublish` channel (post ACL, default-deny), `inst.*.*.<owner>.<actor>`, `svc.*.<owner>.<actor>`; endpoint request forms per minted capability (`ep.one`/`ep.all`/`ep.inst` with the capability's authz-mode/target pattern, caller triple `<owner>.<actor>.<uid>` pinned; `describe` by default; `epj` submissions for journaled capabilities; \xA713.9); own presence key | own `_INBOX_<connId>.>` + own endpoint reply rail (`ep.reply.*.*.*.<owner>.<actor>.<uid>.*`, exact arity); channel live tail via native `sub.allow` subscriptions to `chat.*.*.<channel>` per `allowSubscribe` (wildcards preserved); `STREAM.INFO` (stream-level state only, no body read) on `CHAT` and the world-readable KVs, plus `TASK` when the credential carries a `role`; presence and channel-registry KV watches, including create/info/delete of their client-managed ordered consumers on those two streams only; CHAT history via single-filter `chathist_<owner>-<actor>-<uid>` creates, one per `allowSubscribe` channel (ACL-bounded); own lifecycle-scoped `dm_\u2026`/`svc_\u2026` bind-only; durable backstop via own bind-only lifecycle-scoped `dlv_\u2026` DELIVER consumer, **no** grant on the mixed pre-auth fan-out stream; granted record-key/event-topic read subtrees per capability | read bounded by `allowSubscribe`; ordered-consumer cleanup cannot delete KV records or streams; durable copies re-authorized (current ACL + membership + lifecycle) by the trusted reader before the `dlv` handoff; no Direct Get; DM/TASK/DLV create denied. The `manager-caller` view narrows this endpoint control set to `ep.inst.manager.<managerInstanceId>.<command>` only, plus the exact instance `describe`, contract reads, own reply/progress rows, and own inbox. It carries no agent messaging, delivery, class, or scatter rows. |\n| `observer` | none | chat, CHAT history, presence, channel registry | DMs invisible |\n| `admin` | none | whole space live tap plus DM history | plaintext god-view, opt-in |\n| scoped host profiles | least-privilege per function | least-privilege per function | The former allow-all `manager` is **deleted**; its host duties split into scoped, single-function creds (`supervisor`, `provisioner`, `delivery`, `membership-rw`, `operator`, `purger`, `teardown`, `channel-writer`, \u2026). No allow-all credential exists. Appendix B summarizes them; the concrete grant lists are **generated from the \xA713.9 ownership matrix** into `provision.ts` (the matrix is the single oracle; `provision.ts` is its artifact, Appendix B its summary). |\n\nDM and TASK confidentiality, and the CHAT read boundary, close the leak paths:\n\n1. Replies and pull responses ride a per-connection inbox prefix, `_INBOX_<connId>.>`, which\n   `sub.allow` permits alongside the agent's channel read grants (next item) and nothing else. In user\n   mode the client picks `<connId>` (a nonce) and the callout scopes the inbox to it, so a\n   wildcard-inbox subscribe that would sniff peers' DM deliveries is refused. Re-authorized durable\n   copies do NOT ride the inbox; they ride the agent's own lifecycle-scoped `dlv_<owner>-<actor>-<uid>` DELIVER consumer\n   (item 5, \xA78).\n2. **Channel live reads are bounded by `sub.allow`.** `allowSubscribe` is minted as native subscribe\n   grants over `cotal.<space>.chat.*.*.<channel>` (wildcards preserved); the broker refuses, per\n   subscribe, any channel subject outside the ACL. There is no per-channel consumer name to confine,\n   so an open ACL (`team.>`, `>`) grants selective single-channel join with no enumeration and no\n   read-breakout. A `>` grant is read-all chat in the space by design (credential compromise reads\n   all chat), so it suits trusted/local deployments, not least privilege.\n3. A consumer create on the bare/multi-filter subject is not ACL-constrainable, so the provisioner\n   pre-creates `dm_<owner>-<actor>-<uid>`, `svc_<role>`, and the per-member `dlv_<owner>-<actor>-<uid>` handoff\n   durables. Agents bind their own `dm_\u2026-<uid>`/`svc_<role>`/`dlv_\u2026-<uid>` only (never\n   create); the mixed pre-auth fan-out store is read by a trusted reader, not the agent (\xA78, item 5).\n   Those bare/multi-filter create forms are not granted to agents (default-deny), with explicit\n   create-denies on `DM_<space>`, `TASK_<space>`, and the `DLV` stream; on `CHAT_<space>` the only\n   consumer-create an agent holds is the pinned single-filter history create (next item), so a broad\n   CHAT create-deny is intentionally absent: it would also deny that pinned create.\n4. CHAT history reads are bounded to `allowSubscribe`: a consumer create on the extended subject\n   `$JS.API.CONSUMER.CREATE.<stream>.<name>.<filter>` carries a single filter the server pins to the\n   request body, so an agent is granted exactly one such create-subject per `allowSubscribe` channel\n   and can read history of no other channel. The unfiltered Direct Get grant is not given to agents.\n5. **The durable backstop is read by a trusted reader, not the agent.** The agent holds no\n   content-bearing read on the mixed pre-auth fan-out store; a trusted reader (the server-side delivery\n   daemon) MUST re-authorize `(instance, channel, message)` against the member's current read ACL and,\n   for `durable`-channel fan-out entries, its current membership, before handing the authorized\n   copy off to the member's own lifecycle-scoped `dlv_<owner>-<actor>-<uid>` DELIVER consumer:\n   broker ownership of an inbox (\"this is agent A's\") is not authorization, since the store can hold\n   messages for channels A has since dropped from its ACL or left, and a self-bound consumer cannot\n   filter per-message on membership. Fan-out-on-write is routing, not an authorization check; for a\n   durable channel a `leave` is a hard read boundary on the backstop. History/backfill reads are instead\n   self-served and bounded by the current read ACL (the pinned single-filter create above), consistent\n   with the live read. An `@mention` durable copy is written only to a target authorized to read the\n   channel, so `mentions` cannot carry content outside a target's read ACL.\n6. **\"Current read ACL\" is the effective broker-accepted credential.** An ACL narrowing takes effect\n   when the credential/permissions are updated and enforced by the broker (re-mint / reconnect /\n   revocation), not as an instantaneous global value; until then an existing broad credential remains\n   broad. Both the broker `sub.allow` checks and the trusted-reader re-checks are evaluated against that\n   effective credential.\n\nThis binding provides containment and authenticity under a single trusted broker: an agent\ncan emit only as itself and only to its declared `allowPublish` channels, and read only its own\nDMs and chat *content* within `allowSubscribe` (and, for `durable` content, its current\nmembership), enforced by the server. It does not provide\nnon-repudiation, does not survive an untrusted relay, and DMs are plaintext to the broker and\nto `admin`. The read bound is on **content**, not metadata: agents hold `STREAM.INFO` on CHAT\n(for the join watermark, the recall drop-marker, and channel-list counts), so a `subjects_filter`\nquery leaks chat subject *metadata* (channel names, sender ids, and per-subject counts) for\nchannels outside `allowSubscribe` (channel names are already public via the registry). A\ncredential minted with a `role` also holds it on TASK, under the same gate as that role's\n`svc_<role>` bind grants, so a `subjects_filter` there leaks anycast subject metadata\n(`svc.<role>.<owner>.<actor>`, who anycast which role) to an operator-chosen role profile. DM,\nDLV, and EPC carry **no** agent `STREAM.INFO` grant: `subjects_filter` is a request-body field no\nACL can narrow to counts alone, so INFO there would enumerate who DMed whom, and no agent-side\nreader needs it (\xA713.1 reaches DM and DLV by durable name, EPC by subject-scoped `DIRECT.GET`).\nHiding the remaining metadata is deferred strict-containment work.\nSee [docs/security.md](docs/security.md).\n\n**Consumer-delivery confused deputy on the read grants.** A JetStream consumer delivers stored\nbytes to a **caller-chosen destination the broker does NOT confine to the requester's\n`pub.allow`**: a push consumer's `deliver_subject`, and a pull `MSG.NEXT`/`DIRECT.GET`\nrequest's reply subject, are set in the request body and the server's internal client publishes\nthere regardless of the requester's publish permissions. The v0.3 read grants above,\nCHAT-history `CONSUMER.CREATE`, the bind-only DM/DLV/TASK `MSG.NEXT`, and the KV watch creates\n(Appendix B); therefore let an agent redirect content it may legitimately READ onto a subject\nit may NOT publish to: e.g. replay a stored CHAT message whose `from.id` is another sender onto\n`inst.<victim>.<thatSender>`, where the recipient derives the DM sender from the subject and\nsurfaces it as a genuine DM from a principal who never sent it. The \xA713.9 \"Mediated reads\" rule\napplies here: **no untrusted agent holds a raw consumer `CREATE`/`MSG.NEXT` or `DIRECT.GET` on\n`CHAT`/`DM`/`TASK`/`DLV` or the KV buckets**; those reads are served by the trusted\nreader/mediator (\xA78) onto the agent's own confined rail. Which of these read paths require\nmediation and which are provably safe depends on whether a redelivered message retains its\noriginal captured subject and how the receiver's subject-derived kind check (\xA712) then\nclassifies it; the reference implementation determines this by test and pins the exact grants.\nOn the v0.3 rails without this mediation, read containment holds only against a *conforming*\nclient; the broker does not enforce it.\nSee [docs/security.md](docs/security.md).\n\n---\n\n## 10. Connection and onboarding\n\nJoin link grammar:\n\n```text\ncotal://[token@]host[:port]/space[?channel=a,b]      plaintext\ncotals://[token@]host[:port]/space[?channel=a,b]     TLS required\ncotal://user:pass@host/space                         user/password auth\n```\n\n- Default port is `4222`.\n- `channel` and `channels` query parameters are equivalent comma-separated channel lists.\n- Credentials in `userinfo` are parsed out and passed to the NATS client as connect options;\n  they are not left inside the server URL.\n- Bare `userinfo` with no `:` is a token. `user:pass` is username/password.\n- `cotals://` means `nats://host:port` plus TLS-required connect options.\n- Credentials (`creds`) are mutually exclusive with token and username/password auth.\n- A client MUST set `inboxPrefix` to `_INBOX_<connId>` before any request, pull consumer, or KV\n  watch operation, where `<connId>` is the connection identifier (the connection nkey in static\n  mode; the client-chosen nonce in user mode, \xA72/\xA79), NOT the owner+actor principal, which the\n  client may not know pre-connect.\n\nAuthenticated onboarding has two bindings. **Out-of-band credential minting** provisions a per-agent\ncredential ahead of connect (the static path). **Auth-callout onboarding** validates a user bearer at\nconnect time and mints the scoped data-account JWT then (user mode, \xA72/\xA710): the client presents a\ndeny-all sentinel credential plus its bearer, the callout derives the owner+actor principal and grants,\nand re-binds the connection into the data account. The owner-token *derivation* (how a bearer maps to\nan owner token) is a pluggable identity adapter (any OIDC/IdP via a thin bridge), not fixed by this\ncontract; the callout *mechanism* and the resulting grants are. From v0.4 every minted connection also carries its **lifecycle UID** (\xA713.1): the manager\nmints it for managed agents at provision, and the callout/exchange attaches it as a claim at\nconnect for user-mode connections, so the caller-UID token in every endpoint-rail grant is\nauthority-assigned, never client-chosen. Every bearer additionally carries its incarnation's\n**root credential id** (`act.credentialId`, \xA713.1). The exchange ensures the ACTIVE\n`cred.<lifecycleUid>.<credentialId>` ledger row exists BEFORE the bearer bytes are released\n(the row durable first, the issuance-gate finalize CAS, the lifecycle head's current-root CAS\nlast), and the connect authority proves the presented id against the LIVE row, leader-served\nfrom the shape-proved primary auth store: the row MUST be `active`, unexpired, and bound to the\nconnecting principal and lifecycle, and a root-issued credential MUST additionally equal the\nlifecycle head's current root credential. A claimless bearer, a revoked, expired, or absent row,\nand an unreadable authority store all DENY the connect. The root credential is\n**incarnation-wide**: ONE `cred.<lifecycleUid>.<credentialId>` row per incarnation, re-stamped\n(the same id) on every exchange for the incarnation's lifetime, never a fresh id per exchange.\nRevoking that one row is the per-credential revocation lever and denies EVERY bearer of the\nincarnation at the next connect (deny-new; evicting an already-live connection is the lifecycle\nbarriers' job, \xA713.1). Because the id is incarnation-stable, a crash after the head's current-root\nCAS re-exports the SAME id on the next exchange (that id IS the incarnation's live root, so there\nis nothing unobserved to revoke); the only pre-release crash window is a durable active-but-\nunstamped row, which the head-equality check denies. Rotating an incarnation's root credential is\nexclusively a lifecycle barrier's job, never a bare re-mint. A bearer MAY carry a server-authored\n**view** claim, selected only by the exchange and re-authorized against the live grant ledger at\nevery connect. The callout then mints the connection as that closed profile instead of `agent`.\nElevated views such as `admin`, `purger`, `channel-writer`, and `deployer` remain human-only. The\nnarrowing `manager-caller` view MAY be minted by either the human or managed-agent exchange and is\nserved on both exchange faces. It adds no capability. Its required `act.managerInstanceId` binds\nevery manager request to one exact live registered instance and is valid with no other view. The\nexchange selects from read-only observations of manager issuance gates and service registrations.\nIt refuses zero or ambiguous candidates and refuses an unavailable owner-specific remote manager\nrather than falling through to a co-located manager. An explicit selector must name a live candidate.\nThe `session-caller` view carries a required `act.session` claim `{endpoint, sessionId, epoch, exp}`\n(exp in unix seconds) and is valid with no other view; `act.session` is valid only with it. It needs no\nledger scope: the redeemed \xA713.6 session grant is the authority. The human exchange accepts it only\ntogether with a `sessionGrant` body (each without the other is a 400), and the trusted auth path MUST\nleader-read the `session.<sessionId>` row from the dedicated sessions store before it signs. It MUST\nrefuse unless the row is `active`, `row.grantSig` equals the presented grant's signature, the row's\nholder principal and lifecycle are the bearer's owner, actor and `lifecycleUid`, the endpoint and\nserving epoch equal the presented ones, `row.exp` is in the future, and the serving manager's issuance\ngate is a candidate for this owner with a process epoch equal to the row's. The stamped `exp` is the\nrow's, and the bearer TTL is bounded by it. The callout MUST re-run the same check, without the\nsignature comparison, against a fresh read at connect. It mints the `session-caller` profile for that\none session and binds the minted connection's expiry to the grant's, which is the static arm's\nexpiry, rather than the bearer's. The auth service's host-issuer connection performs both reads and\nholds only `STREAM.INFO` and the leader-served `STREAM.MSG.GET` on `KV_cotal_sessions_<space>`: no\nDirect Get and no write on that store.\nOn a public exchange face, `channel-writer`, `channel-purger`, `manager-caller`, and `session-caller`\nMAY be issued. `admin`, `purger`, `deployer`, and `manager-service` MUST remain loopback-only. A\nmanaged-agent secret exchange MUST refuse every view other than `manager-caller`.\n\n---\n\n## 11. Versioning and extensibility\n\n- Wire contract version is v0.2 as advertised today. `AgentCard.protocolVersion` (\xA76) carries\n  this string. The two v0.3 binding revisions (channel live delivery and owner+actor identity,\n  see the header) and the **v0.4 endpoint control surface** (\xA713) are the normative targets the\n  reference implementation is converging to. The control surface is an intentional **hard\n  cut on the pre-1.0 line** (\xA713.11): the v0.3 control grammar and envelope are removed from\n  this contract, not dual-served, a breaking revision, permitted pre-1.0, shipping under an\n  explicit new version marker per this section's rule; the marker is the disjoint endpoint\n  subject grammar and versioned envelope. The advertised `protocolVersion` bumps to `0.4` when\n  the control-surface migration completes (one campaign, one merge); a version string is not a\n  per-surface cutover claim. **`1.0` is deliberately deferred**: it is a stability declaration\n  to outside implementers, made separately once the contract has settled (further pre-1.0\n  arcs (presence/addressing, multi-space, federation) may still break the wire). **The wire `protocolVersion`\n  is the compatibility signal**; dated document snapshots (below) are navigation artifacts, not\n  negotiation; an implementation MUST NOT treat a document date as an interop key.\n- **v0.5 (workflow runs, \xA714) is an additive revision.** It adds a per-space stream, four core\n  record kinds, a per-run grant family and a normative language reference, and changes no existing\n  kind, subject, grant row or shipped datum; a participant that ignores \xA714 conforms to v0.4\n  unchanged. Two versions ride it and they are deliberately distinct: the wire `protocolVersion`,\n  which targets `0.5` when the plane is served, and the language's own `languageVersion` (\xA714.2),\n  which is bumped when a program's MEANING changes and is pinned per run, so a language revision\n  never forces a wire revision and a wire revision never invalidates an open run.\n- v0 has no in-band capability negotiation. Deployments MUST agree on the binding and\n  version out of band. A participant advertises the version it speaks via\n  `AgentCard.protocolVersion` (\xA76) as a one-way change signal, optional before the v0.4\n  marker, MUST from v0.4 (\xA76, \xA713.11); v0 defines no behavior on a mismatch beyond rejecting\n  messages it cannot parse.\n- **A non-additive discovery change is an out-of-band deployment cutover, and it rolls out\n  CALLER-FIRST.** A discovery change is non-additive when an unamended client that ignores it per\n  the unknown-field rule below would then behave in a way the change exists to prevent \u2014 for such\n  a change, ignoring is not a safe default and no default value repairs it. Every caller in a\n  deployment MUST implement the new version's rules BEFORE any responder in that deployment\n  registers or describes at that version. The two halves SHOULD therefore ship in **separate**\n  releases \u2014 the caller side first and adopted across the deployment, the responder's emission only\n  after \u2014 and shipping them in one release does not make a deployment safe, because **a release is\n  not a deployment**: an already-running caller is unchanged by whatever a new artifact contains,\n  so the order of two source edits says nothing about the processes on the wire. This rule exists\n  because the preceding one leaves a responder no way to detect the hazard itself: with no in-band\n  negotiation and no caller version on the wire, a responder cannot tell an amended caller from an\n  unamended one, so the obligation rests on the deployment rather than on either participant. The\n  observable marker is the discovery protocol's `protocol.v` on the registered service record\n  (\xA713.7) \u2014 \"has any responder cut over\" is a checkable registry property, while \"has every caller\n  adopted\" is exactly the out-of-band agreement this section already requires. **The residual is\n  real**: a deployment that cuts a responder over early exposes its unamended callers to whatever\n  the new version exists to prevent, and within v0 nothing in band detects it. Closing that needs\n  negotiation v0 does not have, and the v1 marker below is where it belongs.\n- New message families, subjects, and routing kinds are added in the core contract,\n  generalized for all deployments, not in one example.\n- Receivers MUST ignore unknown object fields and MUST NOT treat an unknown field as an\n  error.\n- A future v1 MUST either keep v0 subjects backward-compatible or use an explicit new\n  version marker in subjects, credentials, or deployment config.\n\n**Document snapshots.** Published revisions of this document are dated snapshots\n(`YYYY-MM-DD`, the **Last updated** date above): the current revision is canonical, and a\nsuperseded one stays retrievable from the repository history (the git history and tagged\nreleases of `SPEC.md`), so a client built against it can still be audited. The snapshot\ndate advances on any normative change; the wire `protocolVersion` moves only per the\nchange process below.\n\n**Change process.** This document is the change-control point: a change lands here first,\ngeneralized into `core`, and the reference implementation follows. Additive changes (a new\noptional field, a new namespaced `Part.kind`, a new subject) are backward-compatible and ship as\na minor bump, since receivers ignore what they do not recognize. Changing the meaning of an\nexisting field or subject, or removing or renaming one, is breaking. **Pre-1.0**, a breaking\nchange ships as a minor bump of the v0.x line under an explicit new version marker in\nsubjects, credentials, or deployment config (the v0.4 endpoint grammar is such a marker);\n**post-1.0**, it ships as a major bump. `1.0` itself is a stability declaration, made\ndeliberately and separately from any wire change.\n\n**Extension namespacing.** Core `Part.kind` values, `meta` keys, and `tags` are bare and reserved\nto this spec (`text`, `data`, `artifact`, and future core additions). A non-core extension MUST namespace its\ncustom `Part.kind` values and `meta` keys reverse-DNS, under a domain its author controls, e.g.\n`{ \"kind\": \"com.acme.snapshot\" }` or `meta[\"com.acme.region\"]`; Cotal's own non-core extensions\nuse `ai.cotal.*`. This keeps third-party names from colliding with each other or with future core\nnames, with no central registry.\n\nReserved future work: signed envelopes, `did:key` identity, auth-callout bootstrap tokens,\nmanager profile scoping, and federated/untrusted relay bindings. (Revocation/TTL for minted credentials is no longer future work on the control\nsurface: v0.4 defines it normatively via the credential ledger and the lifecycle barriers,\n\xA713.1.)\n\n---\n\n## 12. Conformance\n\n*(An informative build-order walkthrough of this checklist is\n[docs/build-a-client.md](docs/build-a-client.md).)*\n\nA conformant authenticated NATS client MUST:\n\n1. Use one stable principal `<owner>.<actor>` as its wire identity everywhere: subject sender\n   tokens (\xA73), `from.id` (\xA75), presence key (\xA76), durable names (dash-form, \xA78); and treat the\n   connection credential (nkey) as distinct, keying only its reply inbox (\xA72).\n2. Publish only on subjects whose sender tokens are its own principal `<owner>.<actor>` (\xA73).\n3. Publish delivery messages as UTF-8 JSON through JetStream with `msgID = id` (\xA78).\n4. Set exactly one routing field on each delivery message (\xA75).\n5. Reject any received delivery message whose `from.id` does not match the subject sender, and whose\n   subject `<owner>` is not a well-formed principal owner token: a subject that split-parses but\n   carries a non-owner in the owner slot (e.g. a raw nkey, an old-shape alias) MUST NOT be surfaced\n   as a delivery (\xA73, \xA75).\n6. Derive delivery kind (channel/dm/anycast) from the subject, not payload routing fields (\xA74).\n7. Ack only surfaced/handled messages and terminate permanent anomalies (\xA74, \xA78).\n8. Write only its own presence key on the heartbeat interval (\xA76).\n9. Set the per-instance inbox prefix before transport operations (\xA710).\n10. Treat unknown fields as ignorable (\xA711).\n11. Resolve a channel's effective delivery class (`live`/`durable`) from channel config, not from a\n    deployment assumption, and use one resolution across live join, durable fan-out, history read,\n    and membership surfacing (\xA74, \xA77).\n12. On a `durable` channel, tolerate the at-most-once `live` gap and catch up via the durable\n    backstop; deduplicate by `id` across the live, backfill, and durable copies (\xA74, \xA78). Receiver\n    deduplication MUST NOT coalesce copies solely because `id` is the empty string (\xA74).\n13. Join and leave a channel's **live** subscription by subscribing/unsubscribing under `sub.allow`\n    with no privileged mediation; treat a live join as effective only once the broker accepts the\n    subscribe, and drop it on a late permission refusal. On a `durable` channel, additionally establish\n    durable membership via the privileged provisioner; if it cannot be established, report `joined live`\n    with the durable backstop unestablished, never `joined durable` (\xA77, \xA79).\n14. Bound history/backfill reads by the current read ACL, and re-authorize every durable-backstop read\n    against the current read ACL (and, for `durable`-channel entries, membership) before surfacing\n    content, treating a leave as a hard read boundary on the backstop (\xA77, \xA79).\n\nTest vectors use these sample principals (`<owner>.<actor>`); `<ownerA>` = `u_aaaaaaaaaaaaaaaaaaaaaaaaaa`,\n`<ownerB>` = `u_bbbbbbbbbbbbbbbbbbbbbbbbbb` (owner tokens are `u_` + 26 base32-lower, \xA72):\n\n- Alice: `<ownerA>.alice`\n- Bob: `<ownerB>.bob`\n- Reviewer role: `reviewer`\n\nSubject parsing. `parseSubject` **splits only** (\xA73): it recovers tokens by prefix and per-kind arity\nbut does NOT validate the owner token: a well-formed *split* is necessary, not sufficient, for a\nsubject to be surfaced as a delivery. The last row shows an old-shape alias that split-parses yet MUST\nbe dropped at the surfacing boundary (\xA79):\n\n| Subject | Result |\n| --- | --- |\n| `cotal.main.chat.<ownerA>.alice.team.backend` | `kind=chat`, `sender=<ownerA>.alice`, `rest=team.backend` |\n| `cotal.main.inst.<ownerB>.bob.<ownerA>.alice` | `kind=inst`, `sender=<ownerA>.alice`, `rest=<ownerB>.bob` (recipient) |\n| `cotal.main.svc.reviewer.<ownerA>.alice` | `kind=svc`, `sender=<ownerA>.alice`, `rest=reviewer` |\n| `cotal.main.ctl.manager.<ownerA>.alice` | no sender; v0 control subject, retired (\xA713.11): nothing serves it and it MUST NOT be handled |\n| `cotal.main.chat.<ownerA>.alice` | no sender; malformed (owner+actor but no channel token) |\n| `cotal.main.chat.UAQGWOEVJKMIO4WXSYOTLARXYOZTCXFK67JASEH6AFFFYK6FOPSKQCAD.team.backend` | split-parses (`kind=chat`, `owner=UAQ...QCAD`, `actor=team`, `rest=backend`) but MUST be dropped: `UAQ...QCAD` is not a principal owner token (\xA73, \xA79) |\n\nSample multicast message:\n\n```json\n{\n  \"id\": \"018f1d0a-0000-7000-9000-000000000001\",\n  \"ts\": 1710000000000,\n  \"space\": \"main\",\n  \"from\": {\n    \"id\": \"u_aaaaaaaaaaaaaaaaaaaaaaaaaa.alice\",\n    \"name\": \"alice\",\n    \"role\": \"planner\"\n  },\n  \"channel\": \"team.backend\",\n  \"mentions\": [\"bob\"],\n  \"parts\": [{ \"kind\": \"text\", \"text\": \"Can you review this?\" }],\n  \"contextId\": \"ctx-1\"\n}\n```\n\nSample unicast message changes only the routing field:\n\n```json\n{\n  \"id\": \"018f1d0a-0000-7000-9000-000000000002\",\n  \"ts\": 1710000001000,\n  \"space\": \"main\",\n  \"from\": {\n    \"id\": \"u_aaaaaaaaaaaaaaaaaaaaaaaaaa.alice\",\n    \"name\": \"alice\"\n  },\n  \"to\": \"u_bbbbbbbbbbbbbbbbbbbbbbbbbb.bob\",\n  \"parts\": [{ \"kind\": \"text\", \"text\": \"Direct note.\" }]\n}\n```\n\nInterop scenario:\n\n1. Provision a space and credentials for Alice and Bob.\n2. Alice and Bob connect with inbox prefixes `_INBOX_<connId>` (per-connection, \xA72).\n3. Both write presence and join `team.backend`.\n4. Alice multicasts on `team.backend`; Bob receives with `kind=channel`.\n5. Alice unicasts to Bob; Bob receives with `kind=dm`.\n6. Alice anycasts to `reviewer`; exactly one reviewer receives with `kind=anycast`.\n7. A late joiner joins `team.backend`; replayed messages arrive with `historical=true` and\n   live-tail duplicates at or below the join watermark are ack-dropped.\n\n---\n\n## 13. Endpoint control surface (v0.4)\n\nEverything on the mesh that serves structured commands (the manager daemon, the delivery\ndaemon, a wrapped MCP server, a third-party service) is an **endpoint**: a daemon that\nregisters a service identity, publishes its contracts, and answers `describe`. There is no\nspecial-cased service in this contract: `manager` and `delivery` are endpoint names like any\nother, and no subject or envelope in this section knows them. This section supersedes and\n**deletes** the v0 control rail (`ctl.<service>.<owner>.<actor>`, `ControlRequest`/\n`ControlReply`, the `self`/`manager`/`admin`/`delivery`/`delivery-admin` service tiers, and the\nreserved `control.<instance>` subject). The cut is hard (\xA713.11): no v0 control subject,\nenvelope, handler, or grant survives, and a pre-cut control credential cannot reach a post-cut handler.\n\nLayering: identity and transport are \xA72/\xA73, extended by the lifecycle identity below; \xA713.1\nidentity; \xA713.2 grammar; \xA713.3 envelope; \xA713.4 delivery contracts; \xA713.5 verbs; \xA713.6\ncomposites; \xA713.7 contracts and discovery; \xA713.8 distributed guarantees; \xA713.9 authority\nboundary; \xA713.10 receipts and signing anchors; \xA713.11 the hard cut; \xA713.12 the NATS binding;\n\xA713.13 plane ownership; \xA713.14 conformance.\n\n### 13.1 Lifecycle identity\n\nThe principal `owner.actor` (\xA72) is a **recyclable routing alias**: despawning an agent frees\nits actor name, and a later spawn may legitimately reuse it. An alias is therefore never\nsufficient *authority* identity on this surface. Two further identity components exist:\n\n- **Lifecycle UID** (`lifecycleUid`, one token `[a-z0-9]{26,32}`, \u2265128 bits of CSPRNG\n  entropy in a fixed canonical encoding): an unguessable, never-reused\n  identifier of one managed lifecycle under a principal. The UID is entropy, never order:\n  no allocator counter exists, and what is durable and monotonic is only the never-used\n  set. Before anything else, the minting authority (the manager for managed agents; the\n  provisioner for endpoint daemons and operator credentials) **reserves the candidate UID\n  space-globally**: a create-only write of the reservation key `uid.<lifecycleUid>`\n  (\xA713.7), never deleted for the life of the space. A create conflict burns the candidate\n  and draws a fresh one (the alias head alone cannot reject the same UID under a different\n  alias, and the `gate.`/`cred.` families key by UID alone, so uniqueness must be\n  space-wide); a DEL/PURGE marker on a reservation is corruption, never reusable absence.\n  Only then does it mint **before the entity is reachable**, persisting a CAS-fenced\n  mapping\n  `{ owner, actor, lifecycleUid, managerInstance, processEpoch,\n  state: active | retiring | retired, currentCredentialId?, lastTakeoverOpId?, op? }` (closed\n  schema; the\n  embedded `owner`/`actor` MUST equal the key's alias tokens, so a key-mismatched row\n  never authorizes; `currentCredentialId` is absent until the credential ledger releases\n  a root under the reopened gate; `lastTakeoverOpId` is the opId of the takeover operation\n  that LAST advanced `processEpoch` (the epoch advance and this stamp are ONE head CAS, so a\n  completion is bound to exactly one operation: a resuming barrier confirms the completed head\n  carries ITS opId, and a LOSING concurrent takeover that captured the same pre-takeover\n  coordinates finds a foreign opId and refuses, never claiming the winner's completion; absent\n  until the first takeover); `op` is required at `retiring` and forbidden elsewhere)\n  under the alias's **CAS head key** (\xA713.7:\n  the **unsplit** `lifecycle.<owner>.<actor>` head key HOLDS this mapping as one atomic\n  record, the single authoritative current mapping and the only source of `mappingRevision`,\n  \xA713.9; the UID-suffixed `lifecycle.<owner>.<actor>.<lifecycleUid>` key is optional\n  append-only audit, never the authority). `mappingRevision` IS the head key's store\n  revision, learned from the publish ack or from the leader-served read that returned the\n  mapping (one read returns `{ mapping, revision }`); the value carries NO revision field,\n  and a body-supplied revision is never a CAS coordinate. Head states: `active` is the\n  ONLY current state. `retiring` is the containment phase of the terminal barrier (below),\n  bound to the retirement operation's `op.opId`; it is non-current and NOT replaceable.\n  `retired` is terminal and asserts the barrier COMPLETED (the cleanup proof), which is\n  what makes replacing a retired predecessor safe. **Every currency seam fails closed on\n  both non-`active` states**: target resolution, the process-epoch reads gating\n  record/status writes, admission/start, and supervision derive current authority only\n  from `state: \"active\"`; `retiring` and `retired` alike yield no current mapping and no\n  current epoch. Activation is the head CAS (create-only for a virgin alias;\n  revision-pinned from a `retired` predecessor), so two concurrent mints for one alias\n  serialize there and exactly one activates; the loser terminalizes its own orphan gate\n  and burns its reserved UID, never deleting either (`currentCredentialId` is a public key\n  identifier/fingerprint plus authority epoch, never secret material). A supervised restart\n  of the same entity **preserves**\n  the UID (revoking/rotating the connection credential and advancing the process epoch); a\n  terminal despawn, explicit stop, or supervision escalation retires the UID through the\n  terminal barrier *before* the alias is freed. A retired UID is never reactivated\n  (`retired \u2192 active` for the SAME UID is forbidden; only the ALIAS is replaceable, by a\n  freshly reserved UID); recycling cannot move to the reservation, which is never freed.\n- **Process epoch** (`incarnation`, an unsigned integer): the fenced ownership epoch of the\n  process currently animating an identity, advanced by CAS on every takeover or restart. At\n  most one live epoch owns an identity; a superseded process MUST stop serving and its commits\n  are rejected (\xA713.8). **The epoch fences egress only**: reply, event, timer, session, and\n  record-write-ingress publish grants pin it (\xA713.9), but request subjects deliberately omit it; a caller cannot\n  know the serving epoch, so **no subject-level fence for ingress exists or can exist**. An\n  un-revoked superseded serve credential remains a member of the class queue group and can\n  consume (and externally effect, and never validly answer) one call in N. Takeover therefore\n  carries a **normative barrier, in order**: freeze issuance for\n  the lifecycle in the credential ledger (below) \u2192 revoke EVERY active credential-ledger\n  row under the lifecycle prefix, every root (the superseded `currentCredentialId` and any\n  earlier unexpired root: each root mint, initial or rotation, writes its own ledger row)\n  and every ledgered descendant (handle-redemption-minted and per-session credentials,\n  \xA713.6), via the deployment's auth\n  authority, verifying the updated revocation state is enforced on EVERY server of the\n  cluster before proceeding (fail-closed on partial acknowledgment: an unrevoked-anywhere\n  credential can reconnect there) \u2192 evict the live connections of every revoked\n  credential's `holderPrincipal` (from its ledger row, above)\n  cluster-wide and verify the re-scan found none, the barrier executor (the trusted auth\n  path) holds the delivery endpoint's `evictPrincipal` capability for exactly this step\n  (Appendix B: granted to the barrier executor, not only `supervisor`); `evictPrincipal`:\n  system-account CONNZ scan \u2192 per-server KICK \u2192 re-scan verify, fail-closed on partial\n  scans; Appendix B) \u2192 **only THEN advance the process epoch by CAS (N\u2192N+1), reopen the gate\n  at the new generation, and activate the successor's serve subscription**. The epoch CAS is\n  LAST, not first: a superseded process is revoked and evicted before the successor's epoch\n  exists, so it cannot publish a reply or event in a window between the CAS and the eviction;\n  the egress epoch is honest attribution precisely because no live predecessor egress survives\n  the barrier. (A reply the predecessor emitted for an in-flight call before eviction reaches\n  a caller only within that caller's own deadline and from a not-yet-evicted process; the\n  barrier's job is that no such process remains once the successor answers.) Where\n  revocation or verified eviction is unavailable (e.g. static credential material\n  pre-rotation, Appendix B), takeover MUST fail loud rather than proceed.\n\n**Credential ledger (normative).** Ingress has no epoch fence, so revocation is only as\ncomplete as the set of credentials it covers, and the lifecycle's `currentCredentialId` is\nnot that set. Every credential the trusted auth path mints **derived from** a lifecycle (the\nshort-lived credential of a handle redemption, the two per-session credentials of a session\nredemption, \xA713.6) is recorded at mint time in a durable, auth-owned **credential ledger**\nrow `{ credentialId, holderPrincipal (the `<owner>.<actor>` whose connections the barrier evicts; the credential id is NOT the principal, and eviction is by principal), lifecycleUid (the holder's), sourceChain: [root |\nhandle.<issuerKeyId>.<id>\u2026 | session.<sessionId>], the FULL verified lineage: for a\nhandle redemption, EVERY handle in the presented `parentDigest` chain (\xA713.6), never only\nthe leaf, state: active | revoked (monotonic), exp }`, keyed\n`cred.<lifecycleUid>.<credentialId>` so both barriers enumerate a lifecycle's full descendant\nfamily by key prefix. Each mint additionally writes one reverse-index key\n`bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>` per chain member, so **revoking a\nsturdy handle revokes every credential minted under it or under any of its descendant\nhandles**; a credential redeemed through a child handle carries the parent in its\n`sourceChain`/`bysrc` keys, so parent revocation reaches it without walking handle records.\n**Source gates.** The same fence applies per issuing handle, because a handle's revocation\nstate lives in the records bucket while credential indexes live here, and two buckets share\nno order: each sturdy handle has an auth-bucket gate `srcgate.<issuerKeyId>.<id>`\n(`{ state: open | frozen }`, CAS). Handle revocation CASes the source gate to `frozen`\n**before** it enumerates `bysrc.`, and a redemption, after writing its `cred.`/`bysrc.`\nrows, revision-pinned-CASes the source gate of EVERY handle in the presented chain (plus the\nlifecycle gate below), releasing only if all are still `open` at their observed revisions. An\nin-flight redemption under a handle being revoked therefore either finishes before the freeze\n(its rows are in the enumeration) or loses a CAS and never releases. **Handle revocation\ncarries the SAME cluster-wide eviction as a lifecycle barrier** (\xA713.9 `evictPrincipal`):\nafter freezing the source gate and enumerating `bysrc.`, revocation revokes every descendant\ncredential AND verifies revocation enforced on every server, then evicts and re-scans the live\nconnections of every revoked credential's principal, fail-closed, an already-connected\ndescendant credential is never silently left with live grants. The handle status write is\nacked only after that eviction is verified complete.\n\nAn unledgered mint MUST NOT occur (the ledger write precedes credential\nrelease, fail-closed), and the rule carries a mechanical audit invariant in the style of the\n\xA713.9 matrix grep test: every credential the auth authority has ever released MUST resolve\nto a `cred.<lifecycleUid>.<credentialId>` row; an issuance path that cannot show its ledger\nrow is non-conformant, auditable by diffing issued-credential ids against the ledger.\n\n**Issuance gate (normative).** \"Freeze issuance\" is a durable transition, not an assertion:\neach managed-agent lifecycle has a gate key `gate.<lifecycleUid>` in the same auth KV,\n`{ state: open | frozen | retired, generation, op? }` (CAS). A `frozen` gate MUST carry a\ndurable **operation intent** `op = { opId, kind: activation | takeover | registration |\nretirement, successor? }`: after a crash the intent alone\ndecides WHICH operation a frozen gate belongs to and what may advance it, a retry or\nreconciler resumes the SAME `opId`, and a writer that is not that operation's executor\nMUST NOT advance, reopen, or terminalize the gate.\n**A crash can leave the gate frozen under an operation whose executor no longer exists**, and\nfail-closed then blocks every restart while protecting nothing. An operator-facing reconciler\nMAY complete that dead operation's obligation \u2014 resuming its SAME `opId` and reopening at the\nUNCHANGED coordinate with `generation` advanced by one \u2014 but ONLY after it has AFFIRMATIVELY\nverified that the gate's freeze-holder principal is gone, via the same liveness machinery the\nbarrier's eviction trusts (`principalLiveness`, \xA713.9). A holder that is alive, or whose\nliveness cannot be proven, MUST refuse; a timeout or an incomplete sweep is unknowability and\nMUST NOT be read as death. The affirmative check is a PRECONDITION ON TOP OF the barrier's own\nverified eviction, never a replacement for it. A `retired` gate RETAINS the\nterminalizing operation's intent as audit, and an idempotent terminal retry succeeds only\nfor that SAME operation. **Successor coordinates are per-kind and derivable, never loose\nprose**: an `activation` or `retirement` intent carries NO `successor` (an activation's\nsuccessor IS the head mapping the same operation writes; a retirement has none); a\n`takeover` or `registration` operation's successor artifacts are durably keyed by its own\n`opId` (the `stage.<opId>.` staging family and the operation's audit rows), so\n`{ opId, kind }` alone resumes deterministically. The gate MAY carry a `successor` summary\ntoken for those two kinds, but the staged rows are authoritative and a resumer MUST NOT\nact on a summary that the staged rows do not corroborate. **Allowed transitions are also\nper-kind**: a gate is BORN `frozen` only under an `activation` intent (and only for a UID\nwhose `uid.` reservation already exists); `open \u2192 frozen` belongs to `takeover`,\n`registration`, and `retirement`; `frozen \u2192 open` (reopen) belongs to `activation`,\n`takeover`, and a `registration` abort, NEVER `retirement` (a retirement freeze never\nreopens); `frozen \u2192 retired` belongs to `activation` (a head-CAS loser terminalizing its\nown orphan gate) and `retirement`, NEVER `takeover` or `registration` (those abort by\nreopening). An implementation MUST refuse a transition whose gate op kind is outside these\nsets, before any CAS is attempted. The `opId` is an identifier, never a\nbearer capability: a resumer re-authenticates as the operation's executor, and possession\nof the id alone grants nothing. `retired` is terminal, a retired\nlifecycle never mints again. `frozen` is **not** terminal, because a supervised restart\npreserves the UID (\xA713.1) and must mint the successor process's root credential: the\ntakeover barrier freezes at generation `G`, completes revoke + verified eviction of the\nfamily, and only then CASes the gate to `open` at generation `G+1`; the reopen is the\nbarrier's own final step, so no credential of generation `G` is ever live when generation\n`G+1` mints. A gate reopen by anyone but the completing barrier is non-conformant.\n**Endpoint instances use a disjoint gate family, distinguished by explicit prefix and\nnever by token arity**: the endpoint issuance gate is `epgate.<endpoint>.<instanceId>`,\n`{ state: open | frozen | retired, generation, processEpoch, registrationRevision,\nnameAuthorityRevision, principal, op? }` (the endpoint fence coordinates of \xA713.5/\xA713.7, plus\n`principal`: the serving instance's own CONNZ-attributable connection principal, recorded at\nregistration), and\nendpoint-derived credentials ledger under `epcred.<endpoint>.<instanceId>.<credentialId>`\nwith the same row schema, mint protocol, gate discipline, and never-delete rules as\n`cred.`/`gate.`. An interrupted endpoint registration repair MAY journal verified evictions\nunder the disjoint cursor key `eprepair.<endpoint>.<instanceId>`. A cursor MUST bind the exact\nregistration `opId`, the observed frozen-gate KV revision, and the sorted distinct holder set.\nA holder is appended durably only after its eviction verifies, and the holders one eviction sweep\nverified are appended before the next sweep is attempted. A retry MUST repeat the freeze-holder\nliveness precondition, MAY skip only holders in a cursor whose complete binding still matches, MUST\nrestart from empty progress on any mismatch, and MUST reopen only after every current holder\nverifies. Cleanup occurs after reopen; a cursor that\ncannot be deleted cannot authorize a later freeze because that freeze has a different gate revision.\n**`holderPrincipal` is ALWAYS a CONNZ-attributable `<owner>.<actor>` in\nBOTH families** (the barrier KICKs it; an endpoint NAME is not attributable and never sits\nthere): in `cred.` it is the caller principal; in `epcred.` it is the serving instance's own\nconnection principal, copied from the endpoint gate's `principal`, while the endpoint NAME that\nforms the `epcred.` KEY is a SEPARATE row field, so the key identity and the eviction target\nstay disjoint (an `epcred` row that put the endpoint name in `holderPrincipal` could never be\nKICKed). The `cred.`/`epcred.` families hold ONLY conformant ledger rows:\nimplementation staging, half-minted state, and tombstone fences live in a distinct\n`stage.` family, never under a ledger prefix a barrier enumerates.\n\n**Remote manager-service authority (user-auth only).** `manager-service` is one CLOSED,\nserver-authored authority view, not a profile name, arbitrary bearer profile, or client-supplied\npermission set. It exists only for a signed-in human whose current actor-ledger row contains the\ndedicated `supervise` scope. `spawn` and `admin` never imply `supervise`, and `supervise` never\nimplies either. Only the loopback/operator exchange MAY issue this view; the public exchange and\nevery managed-agent secret exchange MUST refuse it. The callout re-reads the ledger row at exchange\nand connect, so a missing, narrowed, or revoked `supervise` scope denies the next view exchange and\nnew connection with the full re-grant requirement. A plain user bearer remains `agent`-scoped.\n\nThe view names exactly one ordinary derived owner, a fixed server-selected manager actor, that\nactor's lifecycle UID, and one opaque locally selected `instanceId`. The actor and instance id are\nnot client-selectable, and the view grants no second manager instance, other endpoint, or other owner.\nIt may reach only the manager instance's own `svc.manager.<instanceId>` registration/status,\npre-authorized immutable contract publication, endpoint rails, and the disjoint\n`epgate.manager.<instanceId>` / `epcred.manager.<instanceId>.<credentialId>` family. It does not\nconfer the space signer, callout signer, owner secret, static provisioner credential, generic\nstream/KV authority, or authority over another instance's gate, records, contracts, or\ncredentials. A manager-service credential is ledgered and gated exactly as this section requires;\nits `holderPrincipal` is the derived-owner/fixed-actor principal, never the endpoint name.\n\nThe typed protocol includes two host-owned registration-maintenance operations. An\n`evict-family-principal` request names one principal, but the host MUST enumerate the authenticated\ncaller instance's `epcred.manager.<instanceId>.*` family and refuse unless that principal is one of\nits holders. The host, using its signer, then mints the bounded delivery-admin caller, requests\n`evictPrincipal`, and returns the closed `EvictionResult`; a garbled, foreign, or contradictory\nresult MUST NOT authorize. The participant never receives that credential. A\n`reconcile-registration` request MAY name another manager instance in the same space only to clear\nan abandoned governance-slot holder. The host MUST observe that target's frozen registration gate,\nprove the freeze-holder `gone` under a complete liveness sweep, run the normal registration repair\nwith verified eviction, and refuse live, unknown, incomplete, unestablishable, or non-registration\nstates. There is no force path. A participant credential still gains no direct authority over the\ntarget gate, records, family, or delivery-admin rail.\n\nThe bounded executor returned by `prepare` is renewable through `renew` for the same public nkey and\ncurrent open registration. A remote manager MUST obtain a fresh executor before maintenance or clean\nderegistration when its retained credential is not healthy. A restart MUST drive family eviction\nthrough the host operation before advancing its epoch. A registration blocked by a foreign frozen\nmanager governance slot MAY request guarded host reconciliation and retry exactly once.\n\nThe typed protocol also carries two host-owned MANAGED-AGENT operations,\n`manager-managed-agent-enrollment` and `manager-managed-agent-prepare-retirement`. Both name the\nauthenticated owner's own managed agent and both require the caller's current `supervise` scope;\n`spawn` and `admin` never imply it. Both MUST be authorized against the caller instance's CURRENT\nopen manager gate: the gate's principal MUST equal the server-derived serve principal, its process\nepoch MUST equal the request's `serveEpoch`, and the request's registration proof MUST match the\nproof the host issued for that registration revision and epoch. An enrollment request MUST carry the\nSHA-256 digest of the agent's standing actor token and never the token itself, and MUST NOT carry a\nlifecycle UID: the HOST selects it, because only the host can observe the retirement tombstones that\nmake a UID permanently unusable. A prepare-retirement request MUST name a target owner equal to the\nauthenticated owner, and its `opId` MUST equal `managedRetirementOpId(target.lifecycleUid)`,\nrecomputed by the host rather than trusted, so one lifecycle never carries two terminal operations.\n\nThese two operations mutate host-owned storage, so an implementation that owns no such storage MUST\nrefuse them with `unimplemented` rather than answering a manager-lifecycle phase for them. An auth\nservice that owns the actor ledger and the space's provisioning authority answers both itself, after\nthe same decision. Its enrollment writes the managed grant at a fresh host-minted lifecycle UID with\nthe request's supervising actor as the grant's parent, so the ledger's delegation envelope bounds it,\nand then provisions that UID's durables; a provisioning failure revokes the grant and releases the\nfootprint before the refusal. An enrollment whose token digest matches the agent's standing grant is\na retry of that enrollment: it walks the held grant through the supervising actor's current\ndelegation envelope and refuses as a fresh enrollment would when the grant falls outside it;\notherwise it answers the held UID and provisions it again, and its failure leaves that grant in\nplace. While the agent holds a grant with another digest, enrollment MUST be refused\nwith `conflict` until that lifecycle's retirement is prepared, so a successor never takes a running\nagent's grant. Its prepare-retirement releases the target UID's broker footprint and then revokes the\ngrant, only while the grant still names that UID, so a repeated request is harmless. The service runs\nenrollment and prepare-retirement of one agent one at a time, and every revoke it performs names the\nUID it releases. The enrolled agent's bearer exchanges at the public exchange face, so an auth\nservice without that face MUST refuse enrollment with `failed-precondition`. A host\nplatform that owns the writers MAY intercept them on its own authenticated route and obtain the\ndecision alone from the auth service's loopback door\n`POST /manager-service-authority/verify-enrollment`, which carries the same loopback guards as the\nmanaged-retire door (POST only, no `Origin`, JSON, the per-start capability, a closed\n`{ owner, request }` body). That door MUST derive the caller's capability scope from its own ledger\nand MUST NOT accept a scope from the caller. It decides only: it mints nothing, writes nothing, and\nreturns no secret.\n\nTwo further host-owned kinds address the hosted runtime of an already-enrolled managed agent:\n`manager-managed-agent-runtime-create` and `manager-managed-agent-runtime-status`. Each carries the\nmanaged-agent envelope plus exactly `target: { owner, actor, lifecycleUid }`. Both schemas are closed:\nan unknown top-level or target field, including `providerRef`, `handle`, or `name`, MUST be refused as\n`bad-request` with no effect. There are no participant stop, adopt, or probe kinds. Both MUST be\nauthorized with the same gate, epoch, and proof checks as enrollment, with a target owner equal to the\nauthenticated owner, and with `supervise` read from the host's own ledger row for the manager actor.\nThe decision yields only the verified owner, instance id, manager actor, and target. A status decision\nauthorizes no effect. An implementation without host intent storage MUST refuse both with\n`unimplemented`. The answer carries `state` (`reserved`, `creating`, `bound`, `create-unknown`,\n`closing`, or `closed`), `readiness` (`ready`, `bound-not-ready`, or `none`), and an optional\n`retirementPhase`. An enrollment result MAY carry `runtimeIntent: { state: \"reserved\" }`, which is\ndisplay-only and MUST NOT be treated as authority.\n\nThe host, not the participant, issues every data-account credential requiring the account signing\nkey. The only remote path is the lifecycle- and instance-bound typed protocol of \xA713.6; a broader\nbearer or a generic credential-mint endpoint is non-conformant. Its gate is frozen before staged\nmaterial becomes usable; every release is preceded by the ledger write and gate CAS; and all\nreplay/idempotency coordinates bind the owner, fixed actor, lifecycle UID, instanceId, operation,\nand public nkey. A remote manager may provision a managed descendant only after the host validates\nthat its current owner equals the manager-service owner and the current manager grant; that is a\nsame-owner validation seam, not delegated signer authority. Revocation freezes the one family,\nrejects fresh material and new connections, and proceeds through the bounded renewal/verified\nrevocation policy below. It MUST NOT silently substitute static or local authority.\n\n**Platform control authority (service view).** `platform-control` is a second CLOSED,\nserver-authored manager authority view, beside and separate from `manager-service`. It lets a host\nplatform run one control manager per assigned data account without any human's session. It is not a\nprofile name, not an exchange view, and not a generic host profile: the public exchange, the\nloopback exchange, and every managed-agent secret exchange MUST refuse it as a view. Its holder is a\nplatform principal. The holder's owner is a platform owner token, `p_` followed by 26 base32-lower\ncharacters, which the host derives from the space's owner secret, the space, and the assigned\ndata-account public key. This extends the \xA72 owner-token format for this view's principals and\ntheir same-owner descendants only; everywhere else \xA72 stands. A platform owner token is disjoint\nfrom every `u_` derived owner, from `local`, from nkeys, and from the \xA713.2 mode words. The host\nMUST NOT derive it from, or bind it to, an IdP subject, and MUST NOT name a `u_` owner on this path.\nNo human is authenticated, and no ledger `supervise` scope is read or synthesized.\n\nThe view exists only while the host's current platform-control assignment names it. An assignment\nis one row `{ space, accountPublicKey, instanceId, lifecycleUid, predecessorInstanceId?,\nassignmentRevision, state }` that the platform backend alone writes. An account has at most one\ncurrent row, so it has at most one platform control instance. The host MUST read it fresh for every\nrequest under this view\nand MUST refuse, writing nothing, when it is absent or `revoked`, or when it disagrees with the\nrequest's account, instance id, lifecycle UID, or assignment revision. A failed read MUST refuse\nrather than reuse an earlier answer. The instance id and lifecycle UID are the assignment's, not\nthe caller's choice. They stay the same across the instance's restarts: a restart re-registers\nthrough the same-principal registration barrier at an advanced process epoch and is never a second\ninstance. The actors are the same fixed functions of the instance id. When the assignment names a\n`predecessorInstanceId`, the host MUST refuse `prepare` and `activate` with `failed-precondition`,\nwriting nothing, while that instance has a current `svc.manager` registration or a `frozen`\nissuance gate. The host only reads that instance's rows. It MUST NOT probe, freeze, evict, revoke,\nreopen, or deregister them. Apart from the\nholder's owner and this authorization source, the view is the `manager-service` family: the same\n`svc.manager.<instanceId>`, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>` rows, ledgered and gated as this section requires, with\n`holderPrincipal` the platform owner plus the fixed actor.\n\nThe view MUST NOT reach an instance whose issuance gate names another principal, including an\ninstance a signed-in human registered under `manager-service` and a manager registered under the\n`local` owner. There is no force or takeover path between the two views. Such an instance retires\nthrough its own owner's path before a platform instance may register. A re-registration never\nchanges an instance's owner, so the view never binds to an existing instance registered under\nanother owner. It registers its own assigned instance once that instance's predecessor has left\nthrough the predecessor's own path. Both registration proofs bind the owner, so a `manager-service` proof never\nvalidates under this view and a `platform-control` proof never validates under `manager-service`.\n\nA manager holding this view MUST run with no local signing trust and no local or custodial runtime\n(pooled control). The view confers no space signer, callout signer, owner secret, provisioner\ncredential, or launch authority. It provisions, enrolls, retires, validates, and authorizes only\nsame-owner descendants, whose owner is its own platform owner token, and grants nothing over a\nhuman owner's agents.\n\n**A read is never a fence; only a CAS write is.** JetStream `DIRECT.GET` may be served by a\nfollower or mirror and gives NO read-your-writes guarantee (a mint that *reads* the gate can\nobserve a stale `open` after a barrier froze it on the leader), so the auth bucket sets\n`allow_direct=false` (\xA713.12) and every fence here is a leader-served, revision-pinned CAS\nwrite. The mint protocol is **observe gate \u2192 write rows \u2192 CAS the gate \u2192 release**: the auth\npath reads the gate (recording `state`, `generation`, and KV `revision`), writes the\n`cred.`/`bysrc.` rows, then performs a **revision-pinned CAS update of `gate.<lifecycleUid>`\nitself at the observed revision**; a leader write that fails if the gate changed at all,\nand releases the credential only on CAS success with the gate still `open` at the same\ngeneration. On CAS failure, `frozen`/`retired`, or any generation advance it aborts and marks\nits own row revoked, never releasing. A barrier CASes the gate to `frozen` FIRST and only then\nenumerates the family. The race is closed by **serialization on one key**, not by timing or\nread freshness: freeze and mint-finalize are both CAS writes to the SAME gate key, so one\nloses; a mint that wins wrote its rows before its winning CAS, so the barrier's later\nenumeration sees them; a mint that loses never released. The ledger is written only by the\ntrusted auth path (\xA713.9 matrix; NATS binding: the auth KV, \xA713.12).\n\n**Every lifecycle operation is a cross-bucket saga, never an implied transaction.** The\nrecords head and the auth gate/ledger live in different buckets with no shared order, so\neach operation persists its durable intent (the gate `op`, above) before touching the\nsecond bucket, every crash boundary resumes the SAME operation from that intent, and the\nsafe orders are normative. **Initial activation, in order**: reserve the UID (create-only\n`uid.<lifecycleUid>`, above) \u2192 create the issuance gate `frozen` carrying the activation\n`op` (unmintable from birth; no credential is ever released under a frozen gate, per the\nunledgered-mint rule) \u2192 CAS the alias head to the new mapping (`active`) \u2192 reopen the gate\nat its first mintable generation as the operation's LAST step. A head-CAS loser\nterminalizes its own orphan gate and burns its reserved UID (never deleting either); a\ncrash after the head CAS leaves the lifecycle active-but-unreachable, and recovery resumes\nthe same activation `opId`, never minting a second UID for one activation. **Takeover**\nkeeps the barrier order above (freeze \u2192 revoke + verified-evict \u2192 epoch head CAS LAST \u2192\nreopen). **Terminal retirement** keeps the barrier order below. No other head transition\nexists: the head advances only inside these operations, and no epoch-advance or retire\nseam is exposed outside the operation that completes its barrier.\n\nBinding rule (normative): **durable** authority and state; sturdy handles, accepted goals,\ncheckpoint tokens and resumes, durable consumers and delivery state, ledger rows, bind\n`(principal, lifecycleUid)` and survive supervised restart. **Live** authority, session\ngrants, reply attribution, serve/commit ownership, additionally binds the process epoch and\ndies on restart. The alias alone authorizes nothing: a delayed or redelivered request, handle,\nor teardown that names a recycled alias fails against the replacement because the lifecycle\nUID differs. Endpoint daemons carry the same triple, with the **stable logical instance id**\n(`instanceId`, `[a-z0-9]{26,32}`, \u2265128 bits of CSPRNG entropy, persisted for the endpoint\nlifetime) as their routable identity component. `instanceId` is **minted by the provisioner,\nnever reused, and unique within `(space, endpoint)`**, the allocator records it in the\ninstance's service record by create-only CAS and rejects collisions durably. Reply\nattribution, scatter deduplication, queue ownership, and the event/timer planes all key on\nit, so its uniqueness and entropy are load-bearing, not cosmetic. `instanceId` is to an\nendpoint what `lifecycleUid` is to a managed agent, and both follow the same\nrestart-preserve / terminal-retire / epoch-fence rules.\n\n**Cross-plane scoping.** Chat/DM/presence *subjects* keep the \xA73 grammar (the alias), but\ntheir backing state is lifecycle-scoped: presence carries the current `lifecycleUid` (\xA76);\nper-instance durable consumers, pending delivery cursors, durable memberships, history\ncutoffs, and ACL/ledger rows key on `(principal, lifecycleUid)` (\xA78, \xA79). The DM subjects\n(`inst.>`) DELIBERATELY stay alias-keyed; a second implementer MUST NOT uid-scope them; the\nsuccessor cut for DMs is the ACTIVATION FRONTIER (the DM stream sequence captured at the\nlifecycle's provisioning, delivery starting at frontier+1, \xA78), and that frontier capture is\na leader-served read (the \xA713.9 read-service class), never a follower get. Explicit same-name\nrecreation inherits **no** predecessor authority or content: terminal retirement records\nper-stream sequence cutoffs before the alias is freed, messages published while no lifecycle\nis active do not flow to a later replacement, and retirement across streams is ordered and\nreconciled (never assumed atomic). **Destructive cleanup is broker-enforced where the resource is broker-addressable**: durable\nconsumer names, ACL rows, KV record keys, and membership rows are lifecycle-keyed, the UID\nis part of the resource NAME, and the teardown credential (the deprovisioner) is minted\ntarget-pinned to `(principal, lifecycleUid)` by exact name, so a credential minted for\nlifecycle A cannot even NAME lifecycle B's resources; the broker denies the stale delete\noutright. Only resources the broker cannot see (the manager's local credential/token/health\nfiles) fall back to a handler-side **delete-if-current** check carrying the retiring UID +\nexpected ownership revision. In both regimes the alias stays reserved until retirement and\ncleanup have durably completed, so a stale detached teardown can never destroy a same-name\nsuccessor. **Terminal retirement is additionally a credential barrier, in order**: CAS the issuance\ngate `open \u2192 frozen` carrying the durable retirement `op` FIRST (the bar: a staged mint\nloses the gate CAS, exactly the mint-protocol race above; the gate revision moves, so a\nmint that observed `open` cannot finalize) \u2192 CAS the head `active \u2192 retiring` bound to the\nsame `op.opId` (from this point every currency seam yields no current mapping and no\ncurrent epoch, and the alias is NOT replaceable) \u2192 revoke every\nactive credential-ledger row under the lifecycle prefix (all roots and all descendants,\ncredential ledger above), verifying revocation enforcement on every server as in the\ntakeover barrier \u2192 cluster-verified eviction of every revoked credential's live connections\n(`evictPrincipal`, as in the takeover barrier above) \u2192 **drain the target's acceptance\nobligations to quiescence** (\xA713.8: enumerate `oblig.<targetUid>.>`, settle every\nunresolved row through its decision coordinate, and re-enumerate until an enumeration\nfinds none unsettled; every writer that observed the pre-`retiring` mapping is settled\nHERE, before the cleaner below runs and before any frontier closes) \u2192 **fence the drain's\nper-op repair principals** (the commit applier, pool-route reconciler, and effects canceller\nminted inside the drain, `local.{epapl|eprec|epcan}_<opId-hash>`): cluster-verify eviction of\nany live connection under each BEFORE the cleaner and BEFORE any frontier \u2014 the applier\nespecially, whose records-KV last-value write is returned to a normal reader regardless of the\nper-stream frontier cutoff. These are self-minted data-account bearers with NO credential-ledger\nrow, so there is no connect-time deny-new: the guarantee here is **kill-live** (verified eviction\nof currently-connected principals), NOT reconnect prevention; a fresh connect within the\nbearer's TTL is the accepted residual NAMED per drain-repair profile in the \xA713.9 matrix (each\n\"RETIREMENT-FENCE residual\" row), of the same kill-live-not-deny-new class \xA713.13 fences for the\nplane connections (repair connections MUST be minted non-reconnecting so a verified eviction is\ndurable) \u2192 the trusted terminal **pool\ncleaner** settles the lifecycle's expired and orphaned pool work under a DISTINCT,\nseparately minted, exact-pool scoped profile whose pool set is this operation's **effective\ninventory**: the target's accepted `oblig.<lifecycleUid>.>` pool routes enumerated from the\nSAME drained, now-`retiring` obligation set (so no new row can appear and the enumeration is\ndeterministic across resumes). The inventory is DISCOVERY-ONLY: the barrier takes no\ncaller-supplied pool hint, so every inventory entry is an obligation-discovered pool this target\nholds accepted work on, and no pool ever enters the cleaner/executor grant without a backing\nobligation. Confinement is the EXACT per-pool effective-inventory grant plus the\nexecutor's per-item decision/horizon/retire-target checks (which bind HONEST execution, not a\ncompromised bearer): (\xA713.9\nmatrix row: bind-only on the pool's\npre-created durable, terminal-only ACK after the item's durable terminal fact, no consumer\ncreate/update/delete, no raw stream DELETE; it never holds, reuses, or impersonates the\nrevoked owner's authority, which this barrier just killed) \u2192 **retire the cleaner\ncredential itself, verified, BEFORE any frontier closes**: once the cleaner has settled the\npool and proven it quiescent (every pre-existing owner ACK drained through `AckWait`, and a\nfresh consumer read shows zero `num_pending` and zero `ack_pending`; a fire-and-forget ACK\nis confirmed with `AckSync` or re-proven, never assumed), the barrier REVOKES the cleaner's\nown bounded-lived credential and cluster-verifies eviction of its principal (`evictPrincipal`,\nexactly as for the owner above), so no in-flight cleaner can ACK a redelivery or write a\nterminal after the alias is reused; the cleaner's authority MUST be dead before the frontier\nrecords \u2192 record the\nper-stream retirement frontiers (the create-only, never-deleted `frontier.<lifecycleUid>`\nrecord, \xA713.7: one key per retired lifecycle, recorded once under this operation's `opId`) \u2192\nCAS the gate `frozen \u2192 retired` (terminal; unlike\ntakeover, retirement never reopens it) \u2192 CAS the head `retiring \u2192 retired` \u2192 only then\nfree the alias, and a successor activates only with a freshly reserved UID. `retired` on\nthe head therefore ASSERTS completed cleanup: replacing a retired predecessor needs no\nfurther proof, because nothing reaches `retired` without the barrier. Every boundary of\nthis sequence is crash-resumable through the durable `op` intent, and only the same\noperation resumes it. A **managed** lifecycle's terminal retirement has exactly one operation\nidentity, `managedRetirementOpId(uid)`, whichever entry point requests it: the participant\nmanager's `retire-lifecycle` rail request (\xA713.2) or the host's loopback managed-retire door, which\nfinishes the retirement when that manager is gone and requires the managed grant to be revoked at\nthat UID first. Both entry points create or resume the same durable operation, and one process\nnever executes it twice concurrently. Chat/DM/presence subjects stay\nalias-keyed, so without the revoke-and-verified-evict step a still-connected stale process\ncould keep speaking as the recycled alias. Where the deployment cannot revoke the credential\nor cannot verify eviction, alias reuse is **forbidden**: a same-name respawn fails loud.\nSupervised restart of the same UID retains all of it.\nIntentional role-mailbox continuity across lifecycles is only available as an explicit,\nseparately authorized transfer operation, never an accidental consequence of string reuse.\n\n### 13.2 Grammar\n\n**Endpoint names.** An endpoint name is one or more DNS-shaped labels, each matching\n`[a-z0-9]([a-z0-9-]*[a-z0-9])?` (no leading/trailing dash, no bare dashes; `_` MUST NOT\nappear in a label). Single-label names (`manager`, `delivery`) are reserved for\nendpoints shipped by this contract's reference implementation and require the space operator's\nprovisioning authority to serve; a third-party endpoint name MUST be reverse-DNS (two or more\nlabels under a domain its author controls, e.g. `com.acme.deploy`) and is mintable only under\nthe owner that registered that domain claim. In a wire subject the name is one token with `.`\nreplaced by `_` (`com_acme_deploy`); because `_` cannot appear in a label the mapping is\nbijective. Name authority is the credential, never the registry (\xA713.9). Endpoint-name\ntokens may contain `-` inside labels; they are never used to derive principal dash-form\nnames; control-surface consumer names are the \xA713.9 pinned grammars, each carrying a\nstated collision-freedom argument, and none is ever parsed back into its components, so\nthe \xA72 dash-form separator stays unambiguous.\n\n**Command tokens.** A command name is one token `[a-z0-9-]{1,32}`. The command is a validated\nsubject token so the broker enforces per-command authority (\xA713.9). `describe` and `cancel`\nare reserved command names (\xA713.7, \xA713.6).\n\n**Request subjects.** Three **addressing modes** under one kind `ep`, the mode token says\nwhere a request routes, never which verb it is (the verb rides the envelope, \xA713.3/\xA713.5):\n`one` (queue-group anycast: exactly one class member), `all` (scatter: every instance),\n`inst` (one instance by its stable triple). The `one` rail's queue group is canonically\nnamed by the endpoint-name token, and serve subscriptions to it are **queue-qualified\nonly** (\xA713.9): no credential can plain-subscribe the class rail, which is what keeps\nper-request nonces visible only to the queue-selected instance. Every request carries the caller as **three**\nforge-locked tokens `<owner>.<actor>.<uid>` (principal + lifecycle UID, \xA713.1) followed by a\ncaller-chosen unguessable **nonce** token (`[A-Za-z0-9_-]{22,64}`, \u2265128 bits of CSPRNG\nentropy; one outstanding call per nonce; reuse before the prior call resolves is a caller\nerror and the reply rail MUST treat the earlier subscription as dead); always, on calls and\ncasts alike, so one grant row covers both verbs and no shape is distinguished by counting. A\ncommand whose contract declares it **targeted** carries an **authorization-mode token** and,\nper mode, zero to three pinned target tokens between the command and the caller:\n\n| Form | Subject | Tokens |\n| --- | --- | --- |\n| Class, untargeted | `cotal.<space>.ep.one.<endpoint>.<command>.<owner>.<actor>.<uid>.<nonce>` | 10 |\n| Class, `self` | `cotal.<space>.ep.one.<endpoint>.<command>.self.<owner>.<actor>.<uid>.<nonce>` | 11 |\n| Class, `owner`/`any` | `cotal.<space>.ep.one.<endpoint>.<command>.<authz>.<tOwner>.<owner>.<actor>.<uid>.<nonce>` | 12 |\n| Class, `child`/`ledger` | `cotal.<space>.ep.one.<endpoint>.<command>.<authz>.<tOwner>.<owner>.<actor>.<uid>.<nonce>` | 12 |\n| Class, `handle` | `cotal.<space>.ep.one.<endpoint>.<command>.handle.<tOwner>.<tActor>.<tUid>.<owner>.<actor>.<uid>.<nonce>` | 14 |\n| Class, `exact` | `cotal.<space>.ep.one.<endpoint>.<command>.exact.<tOwner>.<tActor>.<tUid>.<owner>.<actor>.<uid>.<nonce>` | 14 |\n| Scatter | as class forms with mode token `all` | 10-14 |\n| Instance | `cotal.<space>.ep.inst.<endpoint>.<instanceId>.<command>[.<authz>[.<target tokens per mode>]].<owner>.<actor>.<uid>.<nonce>` | 11-15 |\n| Reply | `cotal.<space>.ep.reply.<endpoint>.<instanceId>.<epoch>.<owner>.<actor>.<uid>.<nonce>` | 11 |\n| Versioned rail (\xA713.15) | every form above with `ep.v1` in place of `ep` and `<generation>` inserted between `<uid>` and `<nonce>` | 12-17 |\n\n**The versioned rail.** An **issued** caller (\xA713.15) rides `cotal.<space>.ep.v1.\u2026`: the same\nforms, one more token, the caller's issued `<generation>` (32 lowercase hex characters), placed\nbetween `<uid>` and `<nonce>` on every request and reply form. The legacy `ep.` rail and the\n`ep.v1.` rail are disjoint subject spaces at the broker: an issued credential holds rows on the\nversioned rail only, a legacy credential holds rows on the legacy rail only, and an endpoint\nserves both. A responder derives the reply subject from the authenticated request subject on\nwhichever rail it arrived, generation included. `v1` versions the rail encoding, not the\nprotocol.\n\n**Single-owner endpoint names (normative).** An endpoint name binds to exactly ONE owner\n(\xA713.9: operator-provisioned core names, domain-owner-bound reverse-DNS names), so the name\ntoken alone determines the serving owner and instance-addressed subjects carry **no owner\ntokens**: `(endpoint, instanceId)` is the complete routable instance address. Two parties\nwanting the \"same\" name use their own reverse-DNS names; an owner-qualified shared-name form,\nif ever wanted, would be a later additive subject form, not a change to these. This trades an\nalready-forbidden expressiveness for structurally smaller subjects and credentials.\n\n**Remote manager service.** The core `manager` name remains operator-governed: a\n`manager-service` bearer (\xA713.1) does not transfer its name authority or create a generic\nuser-owned endpoint. It is the one closed user-auth exception to the single-owner endpoint rule:\nthe host may authorize one `manager` service instance whose service-record owner and serving\nprincipal are the bearer's derived owner plus fixed server-selected manager actor. The exception is\nscoped by the server-authorized lifecycle UID and opaque globally unique instance id, so the\n`(manager, instanceId)` route stays unambiguous and no registration can be mistaken for another\nowner's. The standard `ep` grammar is unchanged: the bearer reaches only that exact manager\ninstance, while the manager's own agent-control requests use the existing owner and same-owner\ndescendant checks. No endpoint name, target form, or wildcard is added for this view.\n\nThe target's **lifecycle UID is body-carried, not a subject token** (`target.lifecycleUid`,\n\xA713.3): a grant could only ever wildcard it (targets are dynamic; the UID is unknowable at\nmint time), so a token there would add zero broker enforcement while costing every targeted\ngrant row a token, the trusted validator, not the broker, compares the expected UID against\nthe current mapping (\xA713.1). The one exception is `handle` mode: at handle redemption the\ntarget's UID IS known and current, so the redemption-minted form pins the full target triple\nas subject tokens (below); pin what is knowable at mint time; body-carry only what is not.\nEvery form stays within the NATS 16-token recommendation.\n\n**Explicit discrimination (never arity counting).** The forms are distinguished by the token\nafter `<command>`: it is either one of the six reserved authorization-mode tokens (`self`,\n`owner`, `any`, `child`, `ledger`, `handle`) or the caller's owner token, and the two sets\nare disjoint by construction, because an owner token is `local` or `u_`+base32 (\xA72), never a\nbare mode word. The target-block arity then follows the mode (`self`: none;\n`owner`/`any`/`child`/`ledger`: one `<tOwner>` token; `handle`: three,\n`<tOwner>.<tActor>.<tUid>`); a closed set at a fixed position, exactly the property that\nmakes per-mode arity safe. A parser dispatches on that set; a subject matching no defined shape\nhas no sender and MUST NOT be handled.\n\n**Token bounds (normative).** On the endpoint rails every identity token is bounded:\n`owner` \u2264 64, `actor` \u2264 64, `command` \u2264 32, `endpoint` \u2264 64, nonce and ids \u2264 64 characters;\n`lifecycleUid` and `instanceId` are bounded by their single defining grammar\n`[a-z0-9]{26,32}` (\xA713.1); deliberately not restated here, so the bound cannot drift from\nthe definition. A total request or reply subject MUST NOT\nexceed 1024 bytes; implementations validate fail-loud at build time. (Transport headroom:\nthe reference deployment raises `max_control_line` to 64 KiB; the PUB line is never the\nbinding constraint; minted-credential size is, \xA713.9.)\n\n**The authorization-mode token** (`<authz>`) makes the authority gradient explicit and\nbroker-enforced where it is statically expressible, and honestly validator-primary where it is\nnot. Seven modes:\n\n- `self`, the target IS the caller: the form carries **no target tokens and no body\n  `target`** (a supplied one is `target-mismatch`, never ignored); the endpoint derives the\n  target from the broker-authenticated caller triple in the same subject. Fully\n  broker-confined, including the lifecycle UID, because the caller's own `<uid>` token is\n  the target's UID, forge-locked by the mint: a stale lifecycle's credential cannot even\n  publish the successor's subject.\n- `owner`, owner-domain: the target block is `<authz>.<tOwner>` (ONE target token); grants\n  pin `<tOwner>` to the caller's own owner (standing mints; a handle redemption instead pins\n  the issuer-signed target owner, \xA713.6). The target actor and expected lifecycle UID are\n  body-carried (`target`) and validator-checked against the current mapping, the broker\n  cannot express \"any actor under my owner, currently mapped to this UID\". An `owner`-mode\n  grant is NEVER minted with a wildcard target owner. Broker-confined on the owner; validator\n  on the rest.\n- `any`, unrestricted target owner (`<authz>.<tOwner>` with `*`): a distinct mode mintable\n  only for operator/admin capabilities, so no widening of an `owner` grant can ever reach\n  it. Validator-checked target as for `owner`.\n- `handle`, **redemption-minted only** (\xA713.6): the target block is\n  `handle.<tOwner>.<tActor>.<tUid>` (THREE target tokens), each a literal pinned at\n  redemption from the issuer-signed grant against the then-current mapping. Never a standing\n  capability, never wildcarded. Broker-confined on the full target triple; the validator\n  re-checks only currency; a subject `<tUid>` that no longer matches the current mapping is\n  `expired`.\n- `exact`, **privileged exact incarnation, minted only through its owning profile** (Cotal\n  #399): the target block is `exact.<tOwner>.<tActor>.<tUid>` (THREE target tokens), the same\n  literal-triple shape `handle` carries, minus the redemption promise. There is no issuer-signed\n  artifact, no redemption step, and no `sourceChain`; the row is built directly by the profile\n  that owns this command under root authority for one target it names, never a standing\n  capability, never wildcarded. Broker-confined on the full target triple, exactly as `handle`;\n  the validator re-checks only currency, and a subject `<tUid>` that no longer matches the\n  current mapping is `expired`. A generic reader of this mode infers precisely a privileged,\n  grant-pinned exact triple with a current-mapping check, and nothing more.\n- `child`, static-mesh own-child (`spawner == caller`): a **distinct trusted-validator form**.\n  The grant means \"may ask this validator\", not \"already authorized\"; the handler MUST\n  fresh-check the immutable spawner relation against durable state and fail closed. Its\n  `<tOwner>` ceiling is the caller's own owner, as for `owner` mode (a static-mesh child\n  shares its spawner's owner).\n- `ledger`, fresh-ledger escalation: a distinct trusted-validator form; the handler MUST\n  fresh-read the authorization ledger and fail closed on lookup failure, timeout, or absence.\n  Its grants pin literal `<tOwner>` values named at mint; a wildcard target owner in `ledger`\n  mode is mintable only for operator/admin profiles.\n\n`any`, `child`, `ledger`, `handle`, and `exact` are never wildcard-reachable from a `self`/`owner`\ngrant (distinct token \u21D2 distinct subject \u21D2 distinct grant row). A handler MUST resolve the target (the\nrevision-pinned `(alias, lifecycleUid)` mapping, \xA713.1) immediately before effect and reject\nany request whose body target disagrees with the subject target tokens (`target-mismatch`) or\nwhose expected target lifecycle UID does not match the current mapping (`expired`). The\nsubject, never the body, is the authorization boundary; handler policy only narrows.\n\n**Replies.** Every reply rides the dedicated reply rail above, **deterministically derived\nfrom the authenticated request subject**: the responder copies the caller triple and nonce\nfrom the request subject and prefixes its own endpoint/instance/epoch tokens (the owner is\ndetermined by the endpoint name; no owner tokens appear). A responder\nMUST ignore any transport- or payload-supplied reply target (the confused-deputy boundary).\nThe grants are exact-arity, no `>` tail admits subjects outside the grammar: the caller's\nread grant is its own rail (`ep.reply.*.*.*.<owner>.<actor>.<uid>.*`), so it reads only\nreplies addressed to it; the responder's publish grant pins its own instance triple and\nepoch (`ep.reply.<endpoint>.<iId>.<epoch>.*.*.*.*`), so the answering instance and\nepoch are read off the broker-authenticated reply subject, never trusted from the payload.\nTwo properties, enforced differently, stated precisely: **attribution** (who answered) is\nbroker-enforced by the responder's pinned prefix; **addressing** (whom a responder may\nanswer) is capability-by-secret, the responder's grant spans all caller suffixes, and what\nconfines it to the requester is possession of the unguessable per-request nonce, which only\nthe request's recipients hold. A stale process (superseded epoch) publishes attributably\nstale replies that callers reject; scatter gathers additionally reject replies from\ninstances outside the frozen expected set (\xA713.5).\n\n**Incarnation admission (the bound-incarnation fence).** Rejecting a reply is a REPORT, not a\nguard: it happens after the responder has already handled the request. On the class rail the\nqueue picks the responder, so a caller that resolved incarnation B can have its command executed\nby A and then be told the call failed \u2014 with no way to say whether any effect landed. A caller\nthat will accept an effect only from the incarnation it resolved therefore declares it in the\nrequest (`bind`, \xA713.3), and a responder that is not that incarnation **MUST refuse it at the\npre-effect seam** \u2014 before args validation, before target resolution, and before the \xA713.6/\xA713.10\ngoverned gate, which may consume a one-use payment proof. The refusal carries\n`ai.cotal.ep.bind-refused` and means the command did not run, so re-resolving and re-issuing\ncannot duplicate an effect; that is the distinction `ai.cotal.ep.unbound-responder` (raised by the\ncaller, on the reply) cannot make. `bind` is a caller declaration and never authority: it can only\nnarrow a request the subject already routed, and attribution still comes from the reply subject \u2014\na refusal attributed to the very incarnation the caller bound is incoherent and MUST be rejected\n(`internal`) rather than honored. A responder that does not implement the fence ignores the field\n(\xA75) and executes; the caller-side check remains the only protection in that skewed pair.\n\nThe **caller's** process epoch is\ndeliberately NOT encoded in the rails: reply consumption binds to the requesting process\nbecause a caller MUST subscribe the exact concrete nonce subject before publishing a call\nand MUST NOT persist nonces; a restarted successor never holds the predecessor's nonce\nsubscriptions, so in-flight calls die with the process (they are ephemeral by definition)\nand a late reply is unreadable rather than misdelivered.\n\n**Event and journal subjects.** Endpoint-published planes, captured by per-space streams\n(\xA713.12); the publishing instance's identity is forge-locked into the subject:\n\n| Plane | Subject |\n| --- | --- |\n| Events | `cotal.<space>.epe.<endpoint>.<instanceId>.<epoch>.<topic...>` |\n| Canonical facts | `cotal.<space>.epf.<endpoint>.<topic...>` |\n| Submissions | `cotal.<space>.epj.<endpoint>.<command>[.<authz>[.<target tokens per mode>]].<owner>.<actor>.<uid>` |\n| Timers | `cotal.<space>.ept.<endpoint>.<instanceId>.<epoch>.<timerId>.<schedule\\|armed\\|fire>` |\n| Record writes | `cotal.<space>.epr.<endpoint>.<instanceId>.<epoch>.<kind>.<qualifier...>` (mediated record-writer ingress; the instance's epoch-pinned rail for `svc`/`goal`/`cp` status writes; consumed ONLY by the record writer, which reads the writing epoch from the broker-authenticated subject, never from payload, \xA713.9) |\n| Contract artifacts | `cotal.<space>.epc.<digest-hex>` (one immutable artifact per subject; `<digest-hex>` is the artifact's SHA-256 hex, 64 chars; the `sha256:` prefix is not a subject token; \xA713.7) |\n| Work pools | `cotal.<space>.epw.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (one item per subject; the trailing four tokens are the item's **acceptance identity**; the accepted submission's caller triple + request id, \xA713.6) |\n| Sessions | `cotal.<space>.eps.<endpoint>.<sessionId>.<epoch>.<in\\|out>` |\n\nEvents carry the publishing instance's **epoch as a subject token**, pinned by the serve\ngrant, so a superseded process cannot emit progress indistinguishable from the current\nincarnation's; readers match the current (or goal-accepted) epoch and treat stale-epoch\nevents as attributably stale. A **targeted** journal command carries the same authz/target\nblock in its submission subject as its request forms, so the broker confines targeted\njournal work exactly as it confines calls; the canonicalizer additionally requires exact\nbody/subject agreement before acceptance. Timers use three forms: `.schedule` is the\ninstance-published **schedule request**, captured by a stream with message schedules\nDISABLED, so any client-set scheduling header is inert bytes, and the mediated timer writer\nrejects a request carrying one; `.armed` holds the **authoritative schedule message**,\npublished only by the mediated timer writer (\xA713.9), which derives the ADR-51\n`Nats-Schedule-Target`, the sibling `.fire` subject, from the broker-authenticated\nREQUEST subject's own tokens, never from any payload or header (a schedule's target MUST\ndiffer from its publish subject per ADR-51; replacement is the writer's same-subject\npublish on `.armed`); `.fire` is where fires appear. An instance's serve grant covers\n**only `.schedule`** (epoch-pinned); no client credential holds `.armed` or `.fire`\npublish; fired messages are written by the broker's scheduler alone, and the handler\nvalidates the carried `(timerId, generation)` against current status AND\n`now \u2265 the authoritative deadline` AND that the broker-authored scheduler-origin header\nnames its own exact sibling `.armed` subject (\xA713.12) before acting.\n\nReserved event topics: `ev.<cluster>.<event>` (cluster events), `goal.<cOwner>.<cActor>.\n<cUid>.<goalId>.<t>` (per-goal action progress; the caller identity in the subject gives\nmint-time read containment), `cp.<token>.<t>` (checkpoint transitions). Reserved fact topics:\n`dec.<cOwner>.<cActor>.<cUid>.<id>` (canonical decisions (accepted/rejected) caller-scoped, \xA713.4), `quar.<sourceSeq>` (poison quarantine, \xA713.4; its own family,\ndisjoint from the caller-id `dec` namespace by construction), `goal.<cOwner>.<cActor>.<cUid>.<goalId>.result` (terminal\nresults), `wrk.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (per-work-item terminal results,\nkeyed by the item's acceptance identity, \xA713.5/\xA713.6), `eff.<cOwner>.<cActor>.<cUid>.<id>`\n(per-request effect-complete facts for non-action effects commands, \xA713.9), `cp.<token>` (one-use checkpoint\nresume, journaled by create-only CAS, \xA713.6),\n`receipt.<cOwner>.<cActor>.<cUid>.<id>.<sourceSeq>`\n(caller-scoped; request ids are caller-chosen, so an endpoint-wide `receipt.<id>` would\nlet two callers collide and read each other's receipts, and **execution-scoped**: the\naccepted submission's `sourceSeq` is unique per execution, so a request id lawfully reused\nafter its decision retention expires (\xA713.4) mints a NEW receipt subject instead of\nappending to the old one, where a last-by-subject read would have hidden the earlier\nreceipt for the rest of its 90-day retention). Submissions are publishable directly by capability holders\nand are **explicitly untrusted** (\xA713.4); canonical fact subjects are publishable only by\ntheir mediated writer (\xA713.9). `<id>`, `<goalId>`, `<timerId>`, `<token>`, `<sessionId>` are\nsingle tokens `[A-Za-z0-9_-]{1,64}`.\n\nThe v0 subjects `cotal.<space>.ctl.>` and `cotal.<space>.control.>` are retired: nothing\nserves them and no post-cut credential carries a grant on them. `trace.<instance>` remains reserved,\nunchanged. `<pool>` is a single token `[a-z0-9-]{1,32}` (command-token grammar).\n\n### 13.3 Envelope\n\nRequests, replies, submissions, events, facts, and progress payloads are UTF-8 JSON. The\nenvelope is versioned and typed; `ControlRequest`/`ControlReply` are deleted.\n\n`EndpointRequest`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `v` | `1` | MUST | envelope schema version (independent of the wire `protocolVersion`; the envelope starts at its own v1 inside the v0.4 revision); other values rejected (`unsupported-version`) |\n| `id` | string | MUST | caller-chosen request id, `[A-Za-z0-9_-]{1,64}`; the idempotency key at the declared scope (\xA713.8), realized on journaled planes by the caller-scoped decision CAS (\xA713.4), never by a transport header |\n| `op` | object | MUST | `{ endpoint, command, inputDigest, outputDigest }`; MUST agree with the subject (`op-mismatch`). The digests bind the invocation to the described contract and are **both REQUIRED on every command except `describe`** (the discovery bootstrap), unconditional, because every command declares both schemas: a side with no payload declares the canonical void schema (\xA713.7), whose digest exists like any other. A serving member rejects a missing digest (`contract-mismatch`) before any effect, and one that cannot honor a pinned digest replies `contract-mismatch`, never coerces |\n| `class` | `ephemeral` \\| `journal` | MUST | the submission's declared delivery contract; MUST equal the command's contract class (`class-mismatch`); immutable per submission. (`record` is a state contract, never a request class; the action composite is a command marker, not a class; an action command's submissions are `journal`) |\n| `replyExpected` | boolean | MUST | the verb: `true` = call (a reply is expected on the reply rail; `deadlineMs` required; the caller subscribes its exact nonce before publishing), `false` = cast (fire-and-forget; a responder MUST NOT reply). The subject shape is identical for both; the verb never changes the grammar |\n| `goalId` | string | action commands | MUST for a command whose contract declares the action composite: the client-generated goal id (\xA713.6); absent otherwise. `id` remains the per-request idempotency key |\n| `target` | object | per mode | `{ owner, actor, lifecycleUid, mappingRevision? }`. **Absent for `self`** (and for untargeted ops): a supplied one is `target-mismatch`, never ignored. **Required for `owner`/`any`/`child`/`ledger`/`handle`**: `owner` MUST equal the subject `<tOwner>` token (`target-mismatch`); `actor` and `lifecycleUid` are validator-compared against the current mapping (`expired` on mismatch), and in `handle` mode MUST additionally equal the subject `<tActor>`/`<tUid>` tokens (`target-mismatch`); `mappingRevision`, when present, additionally pins the exact mapping revision the caller observed |\n| `bind` | object | MAY | `{ instanceId, epoch }` \u2014 the incarnation the caller's `describe` resolved against. A responder whose own `(instanceId, epoch)` differs **MUST refuse before any effect**, at the pre-effect seam and ahead of the governed gate: `failed-precondition` when a different instance received it, `expired` when the same instance is at another epoch, both carrying `details[].kind = ai.cotal.ep.bind-refused`, which asserts the command **did not run**. **Absent on `describe`** (the bootstrap that produces the bind; a supplied one is `bad-request`) and **absent on the scatter rail** (which addresses every incarnation; `bad-request`). On the `inst` rail it MUST name the subject's instance (`bad-request` otherwise) and adds the epoch the subject grammar has no token for. It confers nothing and can only make a responder the subject already reached refuse, so it satisfies monotonic attenuation |\n| `args` | object | MAY | validated against the input schema before any effect (`bad-request`) |\n| `from` | `EndpointRef` | MUST | as \xA75; `from.id` MUST equal the subject sender principal, and the sender UID token MUST match the caller's minted lifecycle UID (broker-enforced by the grant) |\n| `deadlineMs` | number | MUST for call/scatter and journal submissions | caller deadline budget; bounded, never unbounded. On a journal-class submission it is the **decision deadline**: the bound within which the caller expects its durable decision fact (\xA713.4) |\n| `correlation` | object | MAY | `{ traceparent?, tracestate?, baggage? }` per W3C Trace Context; propagated to downstream calls, events, facts, receipts |\n| `auth` | string | MAY | opaque signed authorization-context slot (capability handle, obligations, payment proof). Opaque to the transport, never to identity: its **`authDigest`** (\xA713.4 fingerprint) is `sha256:<hex>` over the UTF-8 bytes of this string **exactly as carried**; the slot is already a canonical signed artifact, so it is digested as bytes, never re-canonicalized, and is absent from the fingerprint iff `auth` is absent |\n\n`EndpointReply`:\n\n| Field | Type | Req | Notes |\n| --- | --- | --- | --- |\n| `v` | `1` | MUST | |\n| `id` | string | MUST | echoes the request `id` |\n| `ok` | boolean | MUST | |\n| `data` | any JSON | MAY | present iff `ok`; validated against the output schema |\n| `error` | object | iff `!ok` | `{ code, message, details?[], outcome? }`; codes below; `details[]` entries carry reverse-DNS `kind`; `outcome` per **Effect outcome** below |\n| `receipt` | string | MAY | opaque signed receipt slot (\xA713.10) |\n\n**Effect outcome.** An error reply MAY carry `error.outcome`, one of `executed`, `not-executed`,\nor `unknown`, stating whether the command's effect occurred. It is emitted by the **responder**,\nwhich is the only party that knows: a responder that refuses BEFORE dispatching to the handler\nMUST carry `not-executed`, and one that refuses AFTER the handler has run MUST carry `executed`.\nA responder that cannot distinguish the two MUST carry `unknown` rather than guess. An error\nreply that omits `outcome` MUST be read as `unknown`.\n\n`outcome` describes a reply, and only a reply. A refusal a CALLER raises locally is not an\n`EndpointReply` and carries no `outcome` field. It does not follow that the caller knows nothing:\nit MUST classify the refusal from what it observed, and only one of the four cases below is\ngenuinely `unknown`.\n\n- **Refused before publication** \u2014 the request was never put on the wire. The caller knows the\n  effect did not occur and MUST classify it `not-executed`. Treating this as `unknown` suppresses\n  a retry that is provably safe, including for a `write`.\n- **Refused while holding a reply** \u2014 the caller parsed a reply and then rejected it for a reason\n  of its own, the \xA713.2 post-reply currency check being the case in this document. What the caller\n  knows comes from the reply it holds: an `ok:true` reply means the handler ran to completion, so\n  the refusal is `executed`; an `ok:false` reply carries the responder's own `outcome`, which the\n  caller MUST adopt rather than overwrite. Discarding a held reply's outcome because the caller\n  went on to reject the reply loses the one fact the responder was in a position to state.\n- **Answered by the broker with no responders** \u2014 the request subject had zero subscribers, and\n  the broker says so on the reserved no-responders sentinel. That is a positive, broker-attested\n  fact that nothing received the request, so it is `not-executed`, not merely unanswered. A caller\n  MUST trust it ONLY on that reserved sentinel, which carries no responder publish grant: the same\n  status on an ordinary reply subject is a responder's own claim and proves nothing about\n  delivery.\n- **No reply observed** \u2014 a deadline that expires with no answer at all, a transport failure after\n  publication, any path where the caller cannot tell whether the request was handled. This is\n  `unknown`, and it is the only local case that is.\n\nA caller **MUST NOT infer execution from the mere arrival of a reply**: a reply proves the request\nwas HANDLED, never that it executed. The two differ on every path where a responder refuses before\nthe handler \u2014 the version, class, target, sender, authz, contract, and guard checks all publish\n`ok:false` having executed nothing, and each of those replies says so in its own `outcome`.\n\n`outcome` exists because a refusal code alone cannot carry this fact: the same code and the same\nmessage are correct for a request that ran and for one that never left, and a caller that cannot\ntell them apart and retries duplicates the effect. `effect` (\xA713.7) tells a client whether a\nrepeat is safe; `outcome` tells the caller what already happened. Neither substitutes for the\nother, and a `write` command refused with `unknown` is precisely the case where no automatic\nrecovery is available and the decision belongs to the caller.\n\n`outcome` is NOT a goal's terminal state. An action accepted under \xA713.6 reports its result as a\ngoal fact; an accepted action whose caller then loses its follow has an `outcome` of `executed`\nfor the SUBMISSION and no terminal state at all, which are different facts about different\nthings. `outcome` MUST NOT be used to report, replace, or summarize a goal outcome.\n\nThe answering instance, its epoch, and the addressee are read from the **reply subject**\n(\xA713.2), not from payload fields; a payload claim of either is advisory display data only.\n\nEvery other plane is typed too: a journaled **submission** is an `EndpointRequest` (same\nenvelope, published to `epj`); an **event** (incl. per-goal progress) is\n`{ v: 1, topic, ts, data, correlation? }`; an **acceptance fact** is the `AcceptanceFact` of\n\xA713.4; a **terminal result fact** carries the goal's terminal state (one of the five\nterminal values of \xA713.6), outcome digest, and\nresult payload (or its digest-pinned reference). All are runtime-validated at their\nconsuming boundary.\n\n**Monotonic attenuation (invariant).** Envelope content, the `auth` slot, a handle,\nobligations; may only narrow what the presenting credential already permits, never widen it.\nA handler that honors envelope content as authority beyond the broker grant is non-conformant.\nAuthority *conferral* exists only as trusted redemption (\xA713.6 capability handle).\n\n**Error catalog.** `code` is one token: `bad-request`, `unsupported-version`, `op-mismatch`,\n`class-mismatch`, `target-mismatch`, `sender-mismatch`, `unauthenticated`,\n`permission-denied`, `not-found`, `already-exists`, `conflict` (CAS/fencing loss,\nfingerprint conflict, duplicate resume), `contract-mismatch`, `contract-invalid` (schema\noutside the profile / over budget at registration), `failed-precondition`,\n`deadline-exceeded`, `cancelled`, `expired` (lease, handle, lifecycle UID, epoch, token),\n`unavailable` (no responder), `unimplemented`, `resource-exhausted`, `internal`. Extensions\nadd codes only under reverse-DNS. A `code` (catalog or extension) is one token of at\nmost **64 bytes**, so every fact shape that embeds one (`RejectionFact`, `QuarantineFact`)\nstays bounded by construction and the \xA713.12 fact fixture is a true worst case.\n\n### 13.4 Delivery contracts\n\nThree delivery contracts, chosen per command class, declared in the contract, immutable per\nsubmission. Decision rule: crash means \"just re-ask\" \u2192 **ephemeral**; long-lived state\nsomething converges on \u2192 **record**; must survive restart, be audited, metered, or\ncompensated \u2192 **journal**. Wrong-class submission fails loud.\n\n**Ephemeral**, request/reply on the `ep` rails; no broker persistence; at-most-once effect\nunless the command is idempotent by `id`. No-responder is a loud `unavailable`.\n\n**Record**, a `{kind, schema, spec, status, meta}` resource in the per-space records bucket,\nstored as **two keys with independent revisions**: `<key>.spec` and `<key>.status`. The split\nis the broker-enforced writer boundary: the spec-writer and status-writer roles hold publish\ngrants on their own key only (per-kind writer table, \xA713.9). Writes use per-key CAS; a lost\nrace is a loud `conflict`. The merged logical read returns both\nrevisions and carries `status.observedSpecRevision`; a reader treats\n`observedSpecRevision < spec.revision` as a stale-but-valid level-triggered projection, not\nan error, and `observedSpecRevision > spec.revision` (a lagging spec read, possible across\nreplica freshness points) as its own signal to re-read the spec key, bounded retries until\ncaught up or the caller's deadline, never trusting the mismatched pair. Watch delivers\ncurrent values then deltas per key; a watcher that falls behind MUST re-read both keys and\nresume, never patch forward across a gap. Records are\nbounded (\xA713.8).\n\n**Journal**, an explicitly **untrusted at-least-once submission log** feeding **canonical\naccepted-fact subjects** with a mediated writer; effects consume only canonical facts, never\nraw submissions.\n\n1. A journaled submission is published to the submission plane (`epj`) as a **plain append**:\n   submitters MUST NOT set `Nats-Msg-Id`, and native dedupe is **not relied upon**, the\n   server does not accept a zero duplicate window (\xA713.12), so the reference config sets the\n   server minimum and the guarantee rests on the header rule, not the window: a conformant\n   submission carries no dedupe header and cannot be suppressed by one. Native broker dedupe\n   keys on a caller-set header value compared\n   **stream-wide**, so on a shared submissions stream any writer could pre-seed a predicted\n   header value from its own allowed subject and silently suppress another caller's first\n   submission for a full dedupe window, a cross-caller denial that no \"advisory\" framing\n   makes safe; with the MUST NOT in force, a hostile header-bearing publish can suppress only\n   another non-conformant header-bearing write. Transport retries therefore simply append\n   again; the caller-scoped decision\n   CAS below resolves every copy to one decision. Submission subjects and fact subjects are\n   disjoint by construction (\xA713.2), so a submission credential cannot write a fact.\n2. The **semantic fingerprint** covers every effect-defining dimension, the fingerprint\n   object is `{endpoint, command,\n   class, authz?, target?: {owner, actor, lifecycleUid, mappingRevision?}, inputDigest,\n   outputDigest, args, authDigest?, caller: {id, lifecycleUid}, goalId?, id}`, and the\n   fingerprint VALUE is that object's `sha256:<hex>` content digest per \xA713.7 (strict\n   RFC 8785 over I-JSON, the SAME canonicalization every contract artifact uses; one\n   canonicalizer, never a second): absent optional fields are OMITTED from the object, never\n   written `null`, so two implementations digest identical bytes, which also makes the\n   fingerprint **computable for EVERY parseable submission**, however incomplete: a\n   parseable envelope missing `class` or digests fingerprints the subset it carries and is\n   rejected with that fingerprint. **\"Parseable\" here means canonicalizable I-JSON**, not\n   merely syntactically valid JSON: bytes that parse but cannot be canonicalized, duplicate\n   object names, a lone surrogate, a non-finite or out-of-I-JSON-range number; have no\n   interoperable RFC 8785 form and therefore no fingerprint, so they take the quarantine\n   path exactly as unparseable bytes and an invalid `id` do (\xA713.4 item 3: raw-byte digest,\n   no fingerprint). Every submission thus has exactly one terminal path. Same id +\n   same fingerprint is the same request (idempotent, first-wins); same id + different\n   fingerprint (including the same args retargeted at a different lifecycle) is a loud\n   `conflict`, never accepted or effected.\n3. The **canonicalizer**, the narrowly scoped mediated writer for this endpoint's facts\n   (\xA713.9); consumes the submission plane through a **normative durable `AckExplicit`\n   consumer** and acks a submission ONLY after a durable decision fact exists, and, for a\n   pool-admitted acceptance, ONLY after the \xA713.6 EPW enqueue create has additionally\n   succeeded (or lost its CAS to an already-present entry): a crash anywhere between\n   acceptance and enqueue therefore redelivers the submission, and the reconciliation\n   predicate resolves the redelivered copy; recovery never has to DISCOVER orphaned\n   acceptances, because an acceptance without its enqueue is by construction an unacked\n   submission that comes back. A crash before\n   the fact redelivers the submission; a crash after it observes the CAS winner on\n   redelivery. It validates each submission (schema, body/subject agreement incl. the target\n   block, authorization per \xA713.6, and (for work-pool commands) pool admission/capacity\n   BEFORE acceptance) and then decides each request exactly once by publishing a\n   **decision fact** to the caller-scoped subject\n   `epf.<endpoint>.dec.<cOwner>.<cActor>.<cUid>.<id>` with create-only CAS (expected last\n   sequence on the subject = 0), so distinct callers can never squat each other's ids. **For\n   an action command the canonicalizer additionally binds the goal before accepting**: it\n   create-only-CASes a **goal-bind fact** `epf.<endpoint>.goal.<cOwner>.<cActor>.<cUid>.<goalId>.bind`\n   carrying the accepted fingerprint, and rejects (`conflict`) any later submission whose\n   `goalId` matches but whose fingerprint differs, so two distinct `id`s naming one `goalId`\n   cannot both be accepted-and-effected (the decision CAS keys on `id`, which alone would let\n   both through; the goal-bind CAS keys on `goalId`, which stops the second BEFORE acceptance\n   and effect, not at the terminal-result stage where the effect has already happened).\n   The decision is `accepted` or `rejected` (with the catalog error); **rejection is as\n   durable, caller-readable, and idempotent as acceptance**, so a permanently invalid\n   submission is distinguishable from a lost one. First decision wins atomically; a later\n   attempt fails its CAS and reads the existing fact. There is no append-then-memo pair to\n   crash between. The canonicalizer is a **singleton per endpoint** (one active principal,\n   epoch-fenced like any serve identity, recovered through the \xA713.1 takeover barrier):\n   admission checks (pool capacity for work-pool commands) are thereby serialized with the\n   decisions they gate, so two canonicalizers cannot both admit the last slot; capacity is\n   consumed by the acceptance itself, never checked apart from it. A submission that cannot\n   yield a decision key; bytes that are not canonicalizable I-JSON (unparseable, duplicate\n   object names, lone surrogate, out-of-range number), or no `id` within the token\n   grammar; **or bytes that breach the command's declared `admissionCeiling`** (\xA713.7): raw\n   size over `maxBytes`, nesting over `maxDepth`, or member count over `maxItems`; is\n   **quarantined, never redelivered forever**: the canonicalizer publishes a\n   **`QuarantineFact`** to the disjoint quarantine family\n   `epf.<endpoint>.quar.<sourceSeq>` (\xA713.2); keyed by the source sequence, which exists\n   for every stored copy by construction, in a family that shares no namespace with\n   caller-chosen `dec` ids, so no legal request id can collide with a quarantine key, with\n   create-only CAS, and terminally acks\n   (`AckTerm`) the submission ONLY after that fact durably exists (or its CAS loss shows it\n   already does), so a poison message cannot pin `MaxAckPending` and the\n   fact-before-terminal-ack rule holds on the poison path exactly as on the decision path.\n   `QuarantineFact` = `{ v: 1, decision: \"quarantined\", sourceSeq, submissionDigest (the\n   `sha256:<hex>` digest of the raw stored bytes, \xA713.7), error: { code (catalog token),\n   detail? (\u2264 256 bytes) }, caller?: { id, lifecycleUid } (from the broker-authenticated\n   submission subject, when it parses), ts }`, every field bounded or fixed-size, so the\n   fact fits by construction; it never carries the poison bytes themselves.\n4. Journal submissions set `replyExpected: false`; the caller **observes its decision** by\n   watching/reading its own decision subtree (`epf.<endpoint>.dec.<its triple>.>`, a\n   caller-scoped read grant minted with every journal capability). An action command's\n   accept/reject is exactly its decision fact, expected within the submission deadline.\n5. The **acceptance fact is self-sufficient for effect and replay** (`AcceptanceFact`, the\n   `accepted` decision): `{ v: 1, id, decision: \"accepted\", fingerprint, request: <the\n   canonical EndpointRequest, args INLINE, bounded by the broker's max_payload; a submission\n   too large is refused loudly with resource-exhausted, never spilled into storage>, caller:\n   {id, lifecycleUid}, target?: {owner, actor, lifecycleUid, mappingRevision},\n   contractDigests: {input, output}, authzDecision: {revision, epoch},\n   route: \"effects\" | `pool.<pool>` (the acceptance's SINGLE execution route, decided by\n   the canonicalizer at admission: a pool-routed acceptance is executed by the pool's\n   worker path (\xA713.5) and the effects consumers MUST ack it without effect; an\n   effects-routed acceptance is executed by exactly one instance off the shared effects\n   durable (\xA713.9). No acceptance is ever executed twice, because the fact names its route),\n   readinessDeadlineMs?: <the acceptance-relative readiness bound, present iff the command\n   declares bounded readiness, \xA713.6; persisted HERE because it is goal state, not the\n   request's decision deadline>,\n   workExpiry?: <absolute expiry of a pool-routed item, present iff `route` is a pool, \xA713.8;\n   survives reconciliation re-enqueue unchanged>, sourceSeq, ts }`. A `target`-bearing\n   acceptance (work bound to a lifecycle) publishes ONLY after its target-indexed\n   obligation row exists AND only under an unexpired admission proof the mediator issued\n   for that row (\xA713.8: proof issuance is the post-create currency recheck, so a row whose\n   target or policy moved between create and recheck never admits; the fact's durable\n   address is caller-scoped, so the obligation row, keyed target-first, is the ONLY\n   target-enumerable record a retirement barrier can drain;\n   `target.mappingRevision` is provenance, never a fence). The\n   canonicalizer preflights the **serialized decision fact**, not merely the inline args,\n   against `max_payload`: a submission whose acceptance fact would not fit is rejected\n   `resource-exhausted`, and the rejection fact always fits by construction: every field\n   is bounded or fixed-size (the operator floor assertion covers the maximum serialized\n   rejection/quarantine fact, \xA713.12):\n   `RejectionFact` = `{ v: 1, id, decision: \"rejected\", fingerprint, error: { code (catalog\n   token), detail? (\u2264 256 bytes) }, caller: {id, lifecycleUid}, authzDecision?: {revision,\n   epoch}, sourceSeq,\n   ts }`; the fingerprint and the catalog error, never the args (a parseable submission\n   always yields the fingerprint; the unparseable/no-id case is the QuarantineFact above,\n   which requires neither `id` nor `fingerprint`). Digest-pinned\n   references inside a fact may name **only already-published public contract artifacts**,\n   never per-request payloads: the contract store is public, immutable, and permanent,\n   the opposite lifecycle of private, horizon-bounded request content (a large-payload\n   facility, if ever needed, is its own future primitive with its own store, retention, and\n   \xA713.9 rows). Effects and replay read the fact, never the raw submission (a TOCTOU re-read\n   of the untrusted log is non-conformant).\n6. Decision facts/tombstones are retained at least the declared **idempotency horizon**\n   (default 24h, space-configurable) AND longer than the maximum submission-log retention\n   plus recovery/redelivery lag; otherwise a rebuilt canonicalizer could re-accept an old\n   submission still sitting in the log as new work. The horizon is **realized by decision\n   retention, not by a clock**: the create-only CAS returns the recorded decision for exactly\n   as long as the fact exists, and a reused id becomes new work only once retention has\n   evicted the old fact and freed its subject; there is no separate time rule for the CAS\n   to disagree with. The \xA713.12 retention floor states the horizon by OUTCOME: no removal\n   cause may drop a decision fact or tombstone before it. The canonical subjects are the authority (D12) for anything\n   auditable, metered, compensated, effected, or replayed. Ordering is per-subject;\n   consumers never assume cross-subject order.\n\n**Events are not facts.** Cluster events and per-goal progress (`epe`) are direct,\nepoch-fenced, instance-published notifications on a durable, ordered, replayable stream;\nthat is the sense in which they ride the journal contract. They do NOT pass through the\ncanonicalizer, carry no acceptance semantics, and MUST NOT drive effects that require\ncanonical acceptance; anything auditable/metered/compensated goes through submissions and\nfacts.\n\n### 13.5 Verbs\n\n- **call**, bounded request/reply (`replyExpected: true`, `deadlineMs` mandatory). On the\n  `one` rail it is queue-group anycast; on `inst` it addresses one stable instance. No\n  responder \u2192 `unavailable`.\n- **cast**, the same subjects and grants (`replyExpected: false`): fire-and-forget,\n  at-most-once, the responder MUST NOT reply and the caller never reads the rail (the nonce\n  is present but unused). A cast to a journaled command is `class-mismatch`; journaled work\n  goes through submissions. In the NATS binding a publish violation is asynchronous \u2014 the\n  publish call returns normally while the broker refuses \u2014 so a caller-side cast\n  implementation MUST watch the connection status for a violation on the cast's own subject\n  and raise `permission-denied` naming that subject, exactly as a call does; a cast\n  implementation MUST NOT resolve as though a refused publish had been cast.\n- **watch**; observe a record (KV watch; fell-behind \u21D2 re-read, \xA713.4) or an event topic\n  (live subscription within the read grant plus filtered replay from the event stream).\n  Per-key and per-goal subjects carry read containment; a watch grant names the exact subtree.\n- **claim**, competitive at-most-one-winner acquisition from a durable work pool (`epw`),\n  **owner-mediated**: the pool's owning endpoint holds the pool's single `AckExplicit` pull\n  consumer (\xA713.12); workers hold **no** JetStream grant on the pool and acquire, renew, and\n  settle work exclusively through the owning endpoint's reserved **`lease`** and **`commit`**\n  commands on the ordinary `ep` rails. This is the only shape that satisfies both claim\n  invariants at once: the delivery's ack token never leaves the party allowed to use it, and\n  the attempt binding is **owner-recorded at assignment** rather than asserted by the worker\n  (a worker-carried \"sequence + attempt\" proves nothing about delivery; an owner assignment\n  does). The stored pool message is **work identity and input only, never the authoritative\n  lease**: broker redelivery re-delivers the same stored bytes, so a token in the payload\n  cannot fence, and the consumer's `ack_wait` is the broker's redelivery-to-owner timer only,\n  never the lease. `lease` (call): the owner fetches the next stored item and records the\n  lease `{item, sourceSeq, attempt: the delivery count, worker: the broker-authenticated\n  caller (principal + lifecycle UID, plus epoch for endpoint workers), fencingToken,\n  leaseDeadline}` in its `lease` record (key grammar \xA713.7, writer table \xA713.9) by\n  **first-wins idempotent CAS per (item, attempt)**, a duplicate or\n  delayed `lease` call for a still-current attempt returns the SAME lease; an attempt is\n  superseded once redelivery advances the delivery count; `fencingToken` is CAS-incremented\n  per attempt and `leaseDeadline` comes from the owner's own clock. Expiry revokes the claim\n  at that deadline even before reassignment. Every Cotal-owned commit from claimed work is\n  submitted through the reserved **`commit` command** carrying the exact lease tuple; the\n  handler validates token currency AND unexpired lease against its own clock AND that the\n  caller is the lease's bound worker, then performs an **atomic, idempotent per-item CAS to\n  a cached terminal result**, the per-item terminal fact\n  `epf.<endpoint>.wrk.<pool>.<acceptance identity>` (\xA713.2), create-only CAS per item,\n  under its mediated writer credential (\xA713.9): a committed item\n  can never be leased again, a duplicate commit returns the cached terminal outcome, and a\n  raced commit loses loudly. Only after observing the committed terminal state does the\n  owner ack the WorkQueue message; it holds the delivery natively, so the deletion\n  capability is never transferred, and no worker-side ack can destroy an item whose commit\n  was rejected. A lost owner ack merely redelivers the item to the owner, which observes the\n  committed terminal state and acks again: **settled work is never re-enqueued as new** (the\n  durable bridge is the acceptance fact plus the per-item terminal CAS; an accepted item\n  with no terminal result and no live pool entry is the only re-enqueueable state, \xA713.6). A\n  stale token, expired lease, or superseded worker is `expired`/`conflict`; workers hold no\n  bypass write.\n- **scatter**, a request on the `all` rail. The caller freezes a **request-scoped expected\n  set**, the live instances of the class from the service registry, each as\n  `(instanceId, registrationRevision, epoch)`, where `registrationRevision` is the store\n  revision of the instance's `svc\u2026.spec` record key (\xA713.7: it advances only on mediated\n  registration writes, and the record read/watch grant that freezes it is a \xA713.9 matrix\n  row), at send time. Gather accepts at most one\n  terminal reply per expected `instanceId`, attributed from the reply subject **including its\n  epoch** (\xA713.2): a second reply from the same `(instanceId, epoch)` is classified\n  `duplicate` and **reported, never silently dropped** (first reply wins); a reply from a\n  frozen `instanceId` at a different epoch, or an observed registration-revision advance;\n  is classified `churn` (the instance restarted mid-scatter and may never have seen the\n  request) and does not count toward completion; replies from outside the frozen set are\n  classified `unexpected` and never count toward completion. Completion is\n  all-expected-replied or deadline, in which case the result is explicitly partial with\n  `missing` / `churn` / `unexpected` / `duplicate` / `late` classifications (a churned slot\n  reports as `churn`, not `missing`). An empty or unreadable registry is\n  `failed-precondition`, not an empty success. Deadline mandatory. A per-instance liveness\n  probe that asks the broker about an instance's own rail is such a cast, and a refused\n  probe publish MUST surface as that same `permission-denied` refusal naming the refused\n  subject, never as a liveness verdict: only the broker's no-responders answer is a\n  liveness fact, and a refusal licenses nothing (a caller that swallowed it into `unknown`\n  would read a permission problem as \"no verdict\" and pay the full budget for it).\n\n### 13.6 Composites\n\nPatterns over the verbs and contracts; zero new transport.\n\n**Action**, a long-running command. `action` is a command **marker**, never a class: an\naction command's submissions are `class: journal` (\xA713.3).\n\n1. The caller submits with a client-generated `goalId` and the request fingerprint (\xA713.4).\n   Accept/reject is the durable decision fact (\xA713.4), expected within the submission's\n   decision deadline; there is no reply-rail answer to recover.\n   **Authorization linearizes at acceptance**: the acceptance fact persists the caller and\n   target lifecycle tuples, command + contract digests, and the authorization decision\n   revision/epoch it was made under. A scope narrowing before acceptance rejects the goal;\n   after acceptance it blocks *new* goals but an accepted goal continues, unless the\n   command's contract declares **continuous reauthorization**, in which case each declared\n   checkpoint re-validates and deterministically transitions to `cancelling`/`failed`\n   (`permission-denied`) on narrowing. Handle expiry/revocation mid-goal follows the same\n   declared policy.\n2. States: `accepted \u2192 running \u21C4 waiting \u2192 succeeded | failed | cancelled | expired |\n   uncertain`, with\n   `cancelling` between a cancel and its terminal state. This is the **single status\n   vocabulary** for every long-running surface. All five of `succeeded`, `failed`,\n   `cancelled`, `expired`, and `uncertain` (item 6) are **terminal**, and first-terminal-fact-wins\n   applies uniformly: `uncertain` is not an absence of an outcome, it is the outcome\n   \"this action's success signal did not arrive within its readiness deadline\".\n3. Progress rides per-goal events (`epe\u2026goal.<caller triple>.<goalId>.progress`), read-scoped\n   to the caller at mint time. The goal's current state is a status-only record projection;\n   the journal owns the facts.\n4. Cancel is the reserved `cancel` command: `graceful` (compensations, default) or\n   `terminate`. Cancel of an unknown/terminal goal is `failed-precondition` with the cached\n   outcome attached. Cancel races completion at the mediated commit point: first terminal\n   fact wins; the loser observes it.\n5. The terminal result is a journal fact and is cached. The full payload is retained at least\n   the declared result retention (default 24h); a **terminal tombstone**\n   `{goalId, fingerprint, state, outcomeDigest}` at least the idempotency horizon (\u2265 result\n   retention; outcome-stated by the \xA713.12 retention floor). Same goalId + fingerprint returns the cached outcome (after payload eviction:\n   the tombstone summary, `data.evicted: true`); same goalId + different fingerprint is\n   `conflict`; beyond the horizon a reused goalId is explicitly new work.\n6. **Bounded readiness (`uncertain`).** An action whose success signal may lawfully not\n   arrive within its readiness bound declares a **readiness deadline**, a distinct,\n   acceptance-relative bound persisted in the acceptance fact/goal state, NOT the\n   submission's `deadlineMs` (which bounds only the decision, \xA713.3). Spawn readiness is\n   the reference case: its readiness deadline is **30 s**, the migrated presence-or-exit\n   backstop, D29; every legacy spawn-timeout consumer converges on this single bound. When\n   the deadline passes without the signal, the owner records the goal's terminal **result\n   fact** (`goal\u2026.result`, \xA713.2) with the outcome\n   `uncertain`, and the goal IS terminal: `uncertain` is a terminal outcome like\n   `succeeded`/`failed`, immutable, first-terminal-fact-wins as for any goal (there is no\n   call and no reply rail here: an action is a journal submission, and the result fact IS\n   the caller-visible outcome, item 5). The underlying ENTITY's later convergence\n   (ready/exited) is observable on that entity's own status record (`svc\u2026.status`, the\n   lifecycle mapping); a caller that needs the eventual answer watches the entity, never\n   the goal; the goal is not rewritten and its status does not linger non-terminal.\n7. Goals bind the target's `(principal, lifecycleUid)` (\xA713.1): a goal accepted against a\n   lifecycle is not redeemable, cancellable, or effectful against a same-name successor. A\n   restarted instance (same `instanceId`/UID, advanced epoch) recovers its goals from journal\n   + records; a superseded epoch cannot commit transitions.\n\n**Awaitable checkpoint**; one durable pause primitive (approvals, guard holds, payment\nauthorization). A waiting action mints a checkpoint: a durable token persisted with the goal,\na `waiting` status carrying the checkpoint id and its **deadline generation**, and a durable\ntimer (\xA713.12). Deadlines are mandatory. Heartbeat/extension CAS-advances the generation in\nstatus, then replaces the timer (a new `.schedule` request; the mediated timer writer's\nsame-subject `.armed` publish is the server rollup, \xA713.2/\xA713.12, the 2.14 atomic\nstop-plus-publish is NOT assumed at the 2.12 floor). A firing timer carries\n`(timerId, generation)`; the endpoint validates the generation against current status before\nacting, stale fires **no-op**. Because status and timer are two resources with no atomic\nbridge, a **durable reconciler** on the owning endpoint repairs the pair after crash or\nleadership change WITHOUT any status\u2194schedule read the no-read timer plane cannot serve: the\nreconciler **re-emits a `.schedule` request at the current generation for every `waiting`\nstatus it owns**, and a same-`(timerId, generation)` arm is **idempotent at the timer writer**\n(it re-derives the same `.armed` message; a duplicate is a no-op replacement), so\nover-emission is harmless and a missing schedule is repaired without the reconciler ever\nhaving to observe whether one exists. Stale-generation fires still no-op at the handler. Cancellation of a timer is cleanup, never the correctness boundary.\nTimer retention MUST exceed the maximum deadline plus a recovery margin. Resume: a `resume`\ncommand presenting the checkpoint token; resume authorization is **one-use** (journaled by\ncreate-only CAS on the checkpoint token; duplicate resume is `conflict`) and holder-bound\n(\xA713.10). Expiry fails the checkpoint closed.\n\nA settlement MAY name the answer it accepted. The one-use settle fact carries an OPTIONAL\n`answerId`, and the status carries the matching OPTIONAL `settledAnswerId`; both are id tokens,\nboth are permitted ONLY on a `resumed` settlement, and an implementation MUST reject either on an\nexpiry. Their key sets are closed: an endpoint that does not know these keys MUST hard-error on a\nfact that carries one. The answer's payload MUST NOT ride either field.\n\n**Guard checkpoint**, the pre-effect authorization hook. A command carrying the governed\n`ai.cotal.guarded` trait MUST NOT effect until the guard endpoint named by the trait value\nanswered **allow** (class call). Answers: `allow | deny | hold` plus optional signed\nobligations (attenuations the endpoint MUST apply; monotonic). `hold` converts the action to\n`waiting` on a checkpoint owned by the guard decision. Timeout or unreachable guard is\n**deny** (fail closed). Ordering is guard-then-effect. Side-effecting guards own their own\nreconciliation.\n\n**Capability handle**, the one passable reference type: a signed JSON grant, RFC 8785\ncanonical, Ed25519-signed by a key in the trust-anchor registry (\xA713.10):\n\n`{ v: 1, id, space, issuer: { keyId }, holder: { id, lifecycleUid }, grants: [{ endpoint,\ninstanceId?, commands: [{ name, authz?, targetOwner?, targetActor?, targetLifecycleUid? }],\nreads?: [<record-key or event-topic subtree>] }], iat, nbf?, exp, parentDigest?, sturdy,\nepoch?, sig }`\n\nA grant entry carries **every subject-level dimension** a capability has (\xA713.9): a targeted\ncommand names its authorization mode and target components; read scopes name exact\nrecord-key / event-topic subtrees. The per-command target tuple is a **closed set of three\nlegal shapes**, no target components; `targetOwner` alone; or the full triple\n`{targetOwner, targetActor, targetLifecycleUid}`, and **every other combination is\nschema-invalid** (`contract-invalid`): in particular `targetActor` without\n`targetLifecycleUid` (a handle that pins a recyclable alias component MUST pin the lifecycle\nit means) and `targetLifecycleUid` without `targetActor` (a lifecycle restriction with no\ncompile target would otherwise be silently DROPPED into an owner-wide grant, a partial\ntuple never weakens into a broader one). The normative compiler maps a grant entry to\nexactly the subjects the equivalent minted capability would receive (never wider) it MUST\nconsume every present signed component (a component the compile target cannot express is\nschema-invalid, never ignored), and every legal entry HAS a compile target:\n\n- a **no-target** entry compiles to the untargeted or `self` form per the command's\n  contract; an `authz` field on it is schema-invalid.\n- an **owner-domain** entry (`targetOwner` alone) compiles to the mode its `authz` field\n  names, `owner` (the default), `child`, or `ledger`, and NOTHING else: each pins the\n  signed `targetOwner` in that mode's own subject form (\xA713.2), **never collapsing `child`\n  or `ledger` to `owner`** (the modes are distinct validator-primary rails and rewriting\n  one into another widens authority), and **`authz: \"any\"` is schema-invalid in a handle\n  grant entry** (`contract-invalid`): the `any` rail is operator-ceiling authority, minted\n  only as a standing capability under an operator-scoped anchor (\xA713.10), never conferred\n  or attenuated through a handle; a compiler therefore has no `any` case, and no\n  implementation choice exists between rejecting, literalizing, or widening it.\n- an **actor-pinned** entry (the full triple) compiles to the `handle`-mode form pinning the\n  full signed triple `<targetOwner>.<targetActor>.<targetLifecycleUid>` (\xA713.2); an `authz`\n  field on it is schema-invalid (the triple IS the mode).\n- an **instance** entry compiles to\n  the exact `ep.inst` rails; complete, because `(endpoint, instanceId)` is the whole instance\n  address and instance ids are never reused (\xA713.1).\n\nA capability that cannot be represented in this shape MUST\nNOT be carried by a handle.\n\n- **Two uses, both fail-closed.** *Attenuation:* presented in the `auth` slot, a handle only\n  narrows; the handler enforces `effective = presenter-cred \u2229 handle.grants \u2229\n  issuer-authority`, and additionally requires any signed target triple to match the\n  request's target and the current mapping (`expired` on mismatch); it never confers broker\n  reach. *Conferral:* a handle grants reach only by **redemption through the trusted auth\n  path** (the exchange/callout of \xA79/\xA710), which verifies the signed target triple against\n  the current mapping **at redemption time** (`expired` on mismatch) and mints a short-lived\n  credential whose grants are the intersection of issuer authority, handle grants, and the\n  redeeming holder's current lifecycle + credential; actor-pinned grants compile to\n  `handle`-mode subjects carrying the verified triple (\xA713.2), so a target lifecycle that\n  rotates after mint is caught by the endpoint's currency check; no handler-side widening\n  exists. The minted credential is **ledgered before release** in the credential ledger\n  (\xA713.1), keyed under the redeeming holder's lifecycle with the FULL presented handle\n  chain as its `sourceChain` (plus the per-ancestor `bysrc.` index keys), so\n  takeover/retirement barriers revoke it with the family and revoking ANY handle in its\n  lineage (parent or leaf) cascades to it. Chain verification itself checks the\n  revocation status of EVERY sturdy link in the chain, not only the presented leaf,\n  failing closed on any revoked ancestor.\n- **Holder-bound:** `holder` names the one `(principal, lifecycleUid)` that may present or\n  redeem it; bearer transfer exists only as an explicit issuer-signed re-issue. `space` binds\n  it to one space. A recycled alias cannot present its predecessor's handles (UID mismatch).\n- **Attenuation chain:** `parentDigest` references the parent handle; a child MUST be \u2286 its\n  parent under the **normative containment order**, per grant entry: endpoint within the\n  parent's endpoint/domain pattern; `instanceId` equal or newly pinned (never widened to\n  absent); commands a name-subset with per-command mode never higher in `self < owner < any`\n  (`child`/`ledger`/`handle` are grantable only where the parent names the same mode); target\n  components equal or newly pinned; read subtrees subject-prefix-contained, and per\n  envelope: same `space`, validity window within the parent's, `sturdy` only if the parent is\n  sturdy. The issuer of a child is the parent's holder, anchor-registered with a `handles`\n  role whose scope covers the child (\xA713.10); the same containment order defines issuer-scope\n  coverage. Presentation carries the full chain inline (`parentDigest`-linked artifacts\n  presented together, no ambient fetch); verification walks every link to a registered\n  anchor, failing closed on widening, unknown/revoked keys, or expiry.\n- **Sturdy vs live:** live handles (`sturdy: false`) bind the current process `epoch`, are\n  never persisted, `exp \u2264 24h`, and die on restart. Sturdy handles bind the lifecycle UID\n  (surviving supervised restart), persist as issuer-namespaced `handle.<issuerKeyId>.<id>`\n  records (spec create-only; status = revocation state, monotonic; \xA713.9 writer table), and\n  verifiers MUST check revocation (fail closed if unreadable). Max sturdy TTL is\n  space-configured (default 30d).\n- Handles are reusable within TTL unless a composite declares one-use (checkpoint resume);\n  the replay matrix of \xA713.10 governs every signed artifact.\n\n**Session (bidirectional stream)**, the generic composite for interactive byte/frame\nstreams (terminal attach is its first consumer; nothing terminal-specific is normative). It\nis exactly D26's cast-ingress + watch-egress composed over dedicated per-session subjects,\nno new verb and no new transport: the `in` subject is a cast-only rail (caller publishes,\nendpoint subscribes) and the `out` subject is a watch rail (endpoint publishes, caller\nsubscribes). A session is established by an ordinary command whose answer is a **session\ngrant**: a one-use,\nholder-bound handle (live: bound to the caller's lifecycle AND current process epoch,\nlive authority dies on restart, \xA713.1, so redemption fresh-checks the holder epoch and an\nunredeemed grant does not survive the caller's restart, plus the serving instance epoch) naming a fresh\nunguessable `sessionId` and the epoch-pinned session subjects\n`eps.<endpoint>.<sessionId>.<epoch>.in` (caller \u2192 endpoint) and `\u2026.out` (endpoint \u2192 caller).\nSession subjects are **core-only**, never stream-captured; the bounded flow window lives in\nmemory and a dropped frame is the composite's problem, not retention's. Redemption mints\nexact asymmetric per-session credentials: the caller publishes `in` and subscribes `out`;\nthe serving instance the reverse; no third party holds either, and no standing wildcard EPS\ngrant exists. Frames are opaque; flow control is bounded (window declared in the grant;\noverflow is `resource-exhausted`, never unbounded buffering). Close is explicit, and\nrevocation has a **durable** named authority that survives the\nserving endpoint: the trusted auth path (the exchange/callout of \xA79/\xA710) persists a **session\nledger row** at redemption, key `session.<sessionId>` in the auth store (\xA713.12), value\n`{sessionId, endpoint, serving instance + epoch, holder (principal + lifecycleUid), both\nminted credential ids, per-credential revocation marks, state, exp}` (the endpoint is in the\nrow because an `instanceId` is unique only within its endpoint, so every serving-party\noperation authenticates against the full serving identity the row pins), create-only CAS per\n`sessionId` (this CAS IS the one-use\nredemption), state monotonic\n(`active \u2192 closed | expired | superseded | retired`, all terminal), and each per-session\ncredential is simultaneously a credential-ledger row under its holder's lifecycle (\xA713.1),\nwhich is the index the \xA713.1 barriers enumerate, and a barrier that revokes a\nsession-sourced credential MUST resolve its `session.<sessionId>` row, transition it\nterminal, and revoke BOTH per-session credentials, so either side's takeover or retirement\ntears down the whole pair, not its own half. Redemption's writes are ordered by a **finalize CAS**, so no half-issued session is ever\nusable: the create-CAS writes the session row in state `issuing` (this create IS the\none-use), then both per-session credential rows are written gate-checked (\xA713.1), then the\nredemption **CAS-finalizes the session row `issuing \u2192 active`**, fresh-checking BOTH the\nholder and serving process epochs and both lifecycle gates at that CAS, and releases the two\ncredentials only on finalize success. A credential is authority ONLY once its session row is\n`active`; an `issuing` row confers nothing. Close/expiry/either barrier CAS the row to a\nterminal state (`closed`/`expired`/`superseded`/`retired`) and revoke both credential ids by\nname (the ids are known from the row, whether or not both credentials were released) so a\ncrash mid-issue leaves an `issuing` row that the expiry sweep collects (revoking both ids and\ntombstoning), never a live half-pair, and a redemption racing a close loses its finalize CAS\nand releases nothing. A revocation mark is set only by a revoke that SUCCEEDED; a terminal\nrow with an unmarked credential is retried by every later sweep pass, exactly the unconfirmed\nids, until both marks confirm, so a transient revocation failure can never quietly leave half\na pair alive. The auth path revokes BOTH per-session\ncredentials with eviction (bounded\npropagation) on any of: an **authenticated close input** on the trusted auth path itself,\na defined operation of the SAME exchange/callout surface that redemption already uses\n(\xA79/\xA710, off-broker, so no broker grant row applies): the caller authenticates as one of\nthe session's two parties (its lifecycle or per-session credential) or as the operator and\nnames the `sessionId`; the auth path verifies party membership against the ledger row\nbefore transitioning it. The in-band close frame\nis an advisory peer signal, never the revocation authority, because EPS subjects are\ncore-only and captured by nothing; expiry per the handle rules (`exp` is enforced by the\nauth path's own timer, not by the endpoint), or the serving\nepoch's supersession / lifecycle retirement via the \xA713.1 barriers (either side's lifecycle:\nholder and serving rows both index the family). Neither side can keep a\nhalf-closed session alive, and a crashed serving endpoint cannot orphan one, the ledger, not\nthe endpoint, remembers what to revoke. Ledger rows are retained at least the maximum\nsession `exp` plus a recovery margin. The session dies with the serving instance's epoch\n(the epoch is in the subject, so a restarted instance cannot resume it; a durable session is\na new establishment). Routing is authenticated broker routing end to end; there is no loopback URL\nor out-of-band transport in the contract, and cross-machine reachability is exactly broker\nreachability.\n\n**Remote manager service registration.** A remote registered user becomes a manager only through\none host-operated, typed `prepare \u2192 activate \u2192 renew` exchange. It is not a generic credential\nmint surface and is available only on the loopback/operator face to a signed-in human holding the\nclosed `manager-service` view (\xA713.1); the public exchange and managed-agent secret exchange\nrefuse every stage. All inputs and stored stage records are closed schemas. An operation is keyed\nby `{ owner, managerActor, lifecycleUid, instanceId, operationId }`, where `managerActor` and the\nlifecycle UID come from the server-authorized view, `instanceId` is opaque and collision-resistant,\nand `operationId` is caller-generated for replay convergence. A repeated operation with the same\nfingerprint returns its recorded result; a different fingerprint at the same coordinate is\n`conflict`; a retired lifecycle or instance is never revived.\n\n`prepare` fresh-checks the ledger scope and lifecycle, freezes only\n`epgate.manager.<instanceId>`, and durably stages the exact service registration, contract closure,\nstatus coordinate, requested public nkey, and credential lifetime. It releases no usable material.\n`activate` re-checks that same live ledger row and gate, creates the exact `svc.manager.<instanceId>`\nregistration, publishes only the staged immutable contract artifacts, and asks the host to sign\nNATS JWT material for that public nkey. The host writes the matching\n`epcred.manager.<instanceId>.<credentialId>` row before the gate-finalize CAS and returns the JWT\nonly after that CAS; it never returns a signing seed. `renew` is the only way to obtain successor\npublic-nkey JWT material. It re-checks the live `supervise` grant, owner, actor, lifecycle,\ninstance, current gate, and bounded renewal window, then records and releases a replacement under\nthe same family. It cannot create another instance or broaden a staged contract, record, endpoint,\nor credential grant. A crashed operation resumes only from its durable stage and operation id.\n\nRenewal is bounded and denial is fail-closed. When a manager cannot renew because its login,\nledger scope, or host service is unavailable, it reports degraded state, retains already-live\nagents only while their independently valid authority remains usable, and refuses new starts,\nrestarts, replacement credentials, and unsafe recovery. It MUST NOT turn a transient failure into\nstatic authority or kill a live agent merely to make the state look healthy. When the current\nfamily expires or is revoked, the host's verified revocation path closes it; a later restart still\nrequires a new successful prepare/activate operation. Same-owner descendant provisioning is\nhost-validated at every request, and loss of that validation also refuses a new start or restart.\n\n**Platform control registration.** A platform-run control manager registers, activates, renews,\nand retires through the same typed `prepare \u2192 activate \u2192 renew` protocol and operations as the\nremote manager service above: `session`, `retire`, `renewStandingBundle`, `renewRunDriver`, the\nhost-owned maintenance operations, retained-agent validation, the goal-index scan, admin\nauthorization, and run admission and attempt. Each request rides inside one closed\n`platform-control-authority` envelope that adds only the space, the assigned account, and the\nassignment revision. The envelope and every inner request are closed schemas. The envelope carries\nno profile name, permission set, subject, lifetime, claim, or identity assertion. An inner request\nkeeps its existing operation-specific coordinates, such as the `session` operation's requested\n`exp`, which the host caps at its own bound, and the run admission's served `run.subject`, which\nthe host re-parses and checks against the caller's issued ceiling. The host validates each one as it\ndoes under `manager-service`. No field of either selects a signing subject, permission set,\nprofile, claim, or a credential lifetime past the host's bound, and an unknown kind or field MUST\nbe refused as `bad-request` with no effect. The managed-agent enrollment, retirement-preparation, and\nruntime kinds are not carried; a host without its own storage for them MUST refuse them as\n`unimplemented`. The door is a typed in-process operation of the host's authority context. It\nexists only where the host supplies its assignment source, and no listener serves it. It needs no\nexchange capability: the host MUST NOT hand its loopback capability or account signer to a control\nmanager, and a host that runs the control manager in another process carries the closed envelope\nover its own caller-bound channel. A request carrying a human IdP token MUST be refused. It is not a\ngeneric credential-mint surface and adds no daemon, listener, or protocol.\n\nHost-owned maintenance is narrower under this view than under `manager-service`. Under\n`platform-control`, a maintenance request's `targetInstanceId` MUST equal the assigned instance id\nfor both `evict-family-principal` and `reconcile-registration`, and the host MUST observe that the\ntarget gate's principal is the platform owner plus that instance's fixed serve actor. Both checks\nrun after the assignment check and before any liveness probe, revocation, eviction, or reopen. A\nfailure is `permission-denied` with no effect. A foreign slot holder therefore blocks platform\nregistration with the existing registration refusal, and it is repaired only through its own\nowner's `manager-service` maintenance or the host operator's guarded gate repair, neither of which\nthis view reaches. `manager-service` maintenance, including its reconciliation of a foreign slot\nholder, is unchanged.\n\nRenewal and fencing are the remote manager service's, unchanged. `renewStandingBundle` returns the\nclosed five-credential family for the same caller-held nkeys and the assigned account only when the\ncurrent gate is open, its principal is the platform owner plus the fixed serve actor, its process\nepoch equals the request's, and the host-keyed current registration proof matches. A stale epoch\nis `conflict`. A revoked or advanced assignment refuses the next request, renewal included, so\nrevocation never waits on a person and renewal never authenticates one. The remote manager\nservice's degraded-state and fail-closed renewal rules apply with the assignment in place of the\nlogin and ledger scope. A start after revocation or expiry requires a fresh `prepare` and\n`activate` under a current assignment.\n\n**Virtual endpoints.** An endpoint MAY be virtual: registered (`spec.activation = on-demand`)\nwith no live instance. A virtual endpoint's commands MUST be journal-class: the buffered\ningress path is the ordinary submission plane (`epj` is durable and needs no live\nsubscriber), and the canonicalizer, which for a virtual endpoint runs wherever its\nactivator/owning authority runs, checks pool admission BEFORE deciding (an over-capacity\nsubmission is rejected `resource-exhausted` as its durable decision fact, never accepted and\nstranded), then accepts and enqueues the work into the endpoint's `epw` pool. Admission\noccupancy is the pool consumer's `num_pending + num_ack_pending`, read fresh from the exact\nper-pool consumer INFO after reconciling the canonicalizer's own outstanding acceptances\nagainst the predicate below (a repaired item is inside the count new work competes under);\nthe read fails closed (an unreadable consumer is `unavailable`, never an empty pool), and the\nsum is honest only while the pool consumer's delivery ceiling is unlimited\n(`max_deliver = -1`) AND its filter is exactly the pool's own subtree; BOTH are editable after\ncreation, so both are pinned at creation AND re-proved at every read (a message that exhausts\na finite ceiling stays stored but leaves both counters; a narrowed or foreign filter reads\nempty while stored work remains). The admission capacity comes from the endpoint's REGISTERED\nactivation policy (declared as the registration's `spec.activation` block, a closed schema\nwhose `capacity` is required; the registration path publishes each version as an immutable\n`policy` record, \xA713.7, and the govern head's selector below names the enforced one), READ\nleader-served at each decision (the read is FENCING by use, so a\nfollower Direct Get is never used; a scoped canonicalizer executes it only through the\nconfined policy reader of \xA713.8, whose request subject binds the authenticated endpoint)\nand its enforced revision RE-PROVEN after the decision's\nlater reads and carried into the acceptance commit, never a free-standing argument; the\ncarried revision is provenance, and the FENCE against the policy or lifecycle moving while\nthe acceptance is in flight is the \xA713.8 obligation row, not the carried value. The\n**endpoint-wide policy coordinate** is not a new head: it is the governance head\n`govern.<endpoint>` (\xA713.7, the endpoint's registration linearization point). To make the\nenforced policy MACHINE-SELECTABLE by any second implementer (not inferable from prose), the\ngovern head value carries a normative **policy selector**: `{ enforcedPolicyKey (the exact\nrecords key of the immutable `policy` record currently governing, \xA713.7), enforcedPolicyRevision\n(that record's STORE revision), pendingPolicyKey?, pendingPolicyRevision? }`. A canonicalizer reads\ngovern leader-served, follows `enforcedPolicyKey`, and re-proves it is still at\n`enforcedPolicyRevision`, with no per-instance guesswork; `policyRevision` throughout this\nsection IS `enforcedPolicyRevision`. **`enforcedPolicyKey` MUST name an IMMUTABLE,\nREVISION-ADDRESSED policy record, not a mutable per-instance slot** (a bare\n`svc.<endpoint>.<instanceId>.spec` overwritten on every re-registration is disqualified: the\nrecords bucket keeps history 1, so once a mutation overwrites it the OLD `enforcedPolicyRevision`\ncan no longer be read, and the drain window's claim that \"the old policy keeps governing\" would\nbe unbacked). The normative immutable form is the **`policy` record kind** (\xA713.7):\n`policy.<endpoint>.<digest-hex>`, one unsplit, create-only, NEVER-DELETED key per policy\nversion, where `<digest-hex>` is the SHA-256 hex of the record's canonical value bytes: the\nkey is self-certifying (a reader re-digests the value and refuses a mismatch), so a\ndifferent-byte overwrite is caught on read, and BOTH the enforced and the pending revisions\nstay readable throughout the drain. Immutability is upheld by the sole writer's create-only\nCAS plus that read-time self-certification, not a broker-level subtraction (\xA713.9). A\ndeployment that cannot provide an immutable policy key MUST pause admission during the\nmutation rather than claim the old value remains readable.\nA policy mutation is a re-registration under the frozen registration gate that lands in TWO\nfenced govern-head CAS steps (\xA713.9): (1) **stage** records the new registration as\n`pendingPolicy{Key,Revision}` (a NEW immutable policy key) while `enforcedPolicy...` still\npoints at the OLD immutable record, so\nthe old policy keeps governing and stays readable; (2) **promote**, only after the mutation has **drained the\nendpoint's unresolved obligations to quiescence** (\xA713.8: enumerate `oblig.*.<endpoint>.>`,\nsettle every unresolved row pinning an older `enforcedPolicyRevision` through its decision\ncoordinate, re-enumerate until none remain), moves `pendingPolicy...` into `enforcedPolicy...`\nand clears the pending slot. Admission always pins the CURRENT `enforcedPolicyRevision`,\nand **while a `pendingPolicy\u2026` is staged, proof issuance for policy-admitted decisions\nREFUSES** (`failed-precondition`: the endpoint is inside its drain window; target-bound-only\nadmissions are unaffected). The pause is what makes the drain CONVERGE under load and makes\n\xA713.8's rule (a row created after the drain's final enumeration can never admit) hold for\npolicy movement exactly as it holds for retirement; rows admitted BEFORE the stage keep their\npinned old revision readable through the immutable key, so no admission is ever judged\nagainst a policy it did not pin. The stage/drain/promote order is a durable, resumable\ngovern-head sequence, never an implied transaction. The **restart-status commit is the same two-coordinate\nclass**: before its status CAS the supervisor obtains a `self`-class obligation (\xA713.8)\nthrough the same mediator, pinning the `enforcedPolicyRevision` its thresholds were read\nunder AND the complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }`\nof the\nstatus record it will write; the status CAS is authorized only while that obligation is\n`accepted`, so a policy or lifecycle movement settles the obligation and the delayed commit\nloses a CAS, and a crash after `accepted` is finished deterministically from the pinned\nintent (\xA713.8 recovery), never a\ncarried-revision comparison. The\nrestart-intensity thresholds are read leader-served from the SAME registered policy, so neither\na caller nor a follower-stale read can loosen the window to suppress an escalation. A command\nname is declared ONCE across the whole closure; a cross-cluster duplicate is an ambiguous\nsurface and registration refuses it, and a command declared non-journal-class in ANY cluster is\nnon-journal for the on-demand registration check. The supervisor-owned status fields (the\nrestart history and the retirement mark) and the `escalated` state can be ORIGINATED only\nunder the supervisor's DISTINCT WRITE AUTHORITY (a package-private branded capability held by\nthe restart-note and the escalation reconciler, never an ambiently-mintable factory or the mere\npresence of a revision pin): an instance-side status write, whether it creates the first status\nor updates a later one, has them stripped and cannot originate `escalated`. The restart history\nand retirement mark are validated at every read boundary (a unique-epoch history, an integer\nmark present only on an escalated row), and a DEL/PURGE status marker fails closed on the\nretirement path (a deletion is never clean absence). Every status write operates on a validated DETACHED snapshot\ntaken before its first read, so a caller mutating a shared status object mid-write cannot split\nthe authenticated coordinate from the stored bytes. The activator's reply authority is its\nown CONNECTION-SCOPED inbox (`_INBOX_<connId>.>`), never the account-wide default, and its\noccupancy read re-proves the pool consumer's ack policy and pull mode alongside its editable\ndelivery ceiling and filter (a delete/recreate must not substitute a semantically different\nconsumer). A supervision clock behind the newest recorded restart is refused before the\nduplicate-note short-circuit, so a rolled-back clock never returns a stale count. The virtual endpoint's canonicalizer durable serializes admission\n(`max_ack_pending = 1`): one submission is in the count-decide-enqueue path at a time, so two\nsubmissions cannot both observe the same free slot; because MaxAckPending is also editable\nafter creation, every admission re-proves the live pin and refuses on drift rather than\ndeciding under a serialization it no longer has; pool-worker execution concurrency is an\nindependent knob, already inside the count via `num_ack_pending`. A virtual endpoint's\nregistration REFUSES if any declared command is not journal-class (an ephemeral surface\ncannot exist with no live instance). Acceptance and\nenqueue span two streams with no atomic bridge, so the enqueue is **idempotent, keyed by the\nacceptance identity, and reconciled against a decidable predicate**: the pool subject carries\nthe acceptance identity and the enqueue is a create (expected-last-sequence-for-subject 0),\nso a duplicate enqueue loses its CAS harmlessly; because the pool owner acks only after the\ncommitted terminal state (\xA713.5), an acceptance fact **with** a terminal result is settled\nand never re-enqueued, and an acceptance fact with **no** terminal result and **no** live\npool entry (a FENCING absence: the probe is the leader-served `STREAM.MSG.GET` last-by-subject\nread of the \xA713.9 work-pool reconciliation row, never a follower-servable Direct Get, because a stale\nfollower miss would re-arm settled work) is unambiguously never-enqueued-or-lost, the\nonly re-enqueueable state. A crash after the acceptance CAS but before the enqueue is\nrepaired by exactly that predicate; an enqueue without an acceptance fact cannot occur\nbecause only the canonicalizer holds the pool-write grant and it enqueues only from its own\naccepted decisions. The stored item bytes are the CANONICAL derivation of the acceptance \u2014\nthe RFC-8785 canonical JSON of exactly `{ v: 1, id, fingerprint, sourceSeq, workExpiry,\ncaller, request }` (work identity + input only; never a lease, token, or decision metadata) \u2014\nso any two conforming writers (a first enqueue and a crash repair) produce BYTE-IDENTICAL\nitems, and the create's same-subject-same-bytes idempotency holds across them; a differing\nbody under the same acceptance identity is a mixup and refuses loud. An ephemeral\ncall to a virtual endpoint with no live instance is an honest `unavailable`; nothing\nsilently buffers it. An **activator** (holder of its activation capability) watches the pool\nand starts an instance; single-writer per identity is fenced by instance-record CAS +\nepoch. The exact consumer INFO the activator watches is a request/reply snapshot with no\nbroker wakeup, so watching is bounded polling with backoff to a finite maximum interval, and\nan INFO failure is loud, never a silent skipped poll; the activator's broker authority is\nexactly that INFO read plus its mediated, target-bound start seam (no pool consume/ack, no\nstream read, no consumer create/update/delete). Passivation drains, updates status, exits;\ndurable reminders ride the timer plane.\nSupervision is restart-intensity escalation: more than `maxRestarts` (default 3) within\n`restartWindow` (default 60s) escalates; the instance stops restarting, status records\n`escalated`, the lifecycle retires terminally (\xA713.1), and the failure is loud. The restart\nhistory is DURABLE on the instance's own status record, SUPERVISOR-OWNED (the status writer\ncarries it forward through every ordinary instance-side write, so a successor's `ready`\nconvergence can neither reset nor forge it), and each note is a revision-pinned CAS: a\nsupervisor restart cannot amnesty the count and two concurrent notes cannot merge-lose a\nrestart. Each history entry is bound to the DYING PROCESS EPOCH (a real restart advances the\nepoch), so a replayed or duplicated notification of one restart is an idempotent no-op, never\na double count; and a supervision clock behind the newest recorded restart REFUSES rather\nthan silently truncating history. `escalated` is IRREVERSIBLE at the status writer (no later\nwrite, any epoch, replaces it), refuses further notes, and is excluded from every liveness\nderivation (a frozen scatter expected set never contains an escalated instance). The\nescalation commits before the lifecycle retirement runs; the retire seam MUST be idempotent,\na retirement failure leaves the escalation standing, and a reconciler retries retirement on\nalready-escalated rows until it completes, recording completion durably (nothing\nun-escalates).\n\n**Interactive session**, a one-use, holder-bound, bidirectional byte stream to a managed target\n(the `attach` reference case). Establishment is a two-step, collapsible exchange: the serving endpoint\nmints a signed **session grant** bound to `(holder triple, target (owner, actor, lifecycleUid),\nserving instanceId + epoch, expiry)` and returns it as the establishment answer, **never a transport\nURL and never logged**; the holder **redeems** it by opening the session, which consumes it (create-only\nCAS on the durable `session.<sessionId>` ledger row, \xA713.12; a second redeem is `conflict`). The grant\nis non-bearer: redemption is **presenter-equality** bound to `holder` (\xA713.10), so a leaked grant confers\nnothing. Authorization is the target command's own (`owner`/`any` + name authority, \xA713.9); a session is\nnever a path around the despawn/attach authorization.\n\nThe byte stream rides two CORE-ONLY rails, `eps.<endpoint>.<sessionId>.<epoch>.<in|out>` (\xA713.9), never\nstream-captured: the holder publishes `in` and subscribes `out`, the serving endpoint the reverse; the\nholder's grant covers exactly its own session's two subjects. **Framing** (the terminal-session profile):\napplication bytes are `{ k: \"data\", b: <standard base64> }`; control is structured JSON, `{ k: \"ready\" }`,\n`{ k: \"resize\", cols, rows }` (both positive integers), `{ k: \"end\", reason }`, `{ k: \"drop\", bytes }`.\nOrdering is per direction by publisher sequence. Flow is a bounded in-flight window per direction; output\nthe window cannot take is **dropped, counted, and surfaced** as a `drop` frame before the resumed stream,\nnever silently lost. On the holder's `ready` the serving side replays a byte-exact reconstruction of the\ntarget's current screen, then streams live output in order. A degenerate or unparseable caller frame is\ndropped, never a session teardown.\n\n**Termination is honest and distinct**: every teardown surfaces an `end` frame naming a bounded reason,\n`process-exit` (the target exited), `closed` (a party closed), `expired` (the session TTL elapsed),\n`target-despawn` (the target lifecycle retired), `manager-restart` (the serving incarnation advanced its\nepoch). The session binds the target's `(principal, lifecycleUid)` and the serving epoch (\xA713.1): a\nsuccessor incarnation (advanced epoch) refuses old-epoch grants, and a same-name successor is a distinct\nsession.\n\n### 13.7 Contracts and discovery\n\n**Clusters.** An endpoint's surface is a set of composable **capability clusters**, each\n`{ urn, revision, attributes[], commands[], events[] }`:\n\n- `urn`, reverse-DNS cluster type URN (`ai.cotal.lifecycle`, `com.acme.deploy`).\n- `attributes`, readable/watchable state; each declares a name, value schema, and record\n  derivation (which record key carries it). Attribute reads/subscribes ride the record\n  contract, never ephemeral replies.\n- `commands`, each declares name, input/output schemas, `class`, `targeted` (and if so which\n  authz modes it admits), its **capability requirement** (the named capability minting maps to\n  subjects, \xA713.9), its `effect` (below), and optional traits.\n  Each `journal`-class command **MUST** declare **`admissionCeiling`** =\n  `{ maxBytes, maxDepth, maxItems }`, the bounds its canonicalizer refuses beyond (\xA713.4\n  item 3). The ceiling is **declared, never compiled in**, because it decides what a\n  submission durably *becomes*: two implementations that agree on the wire and disagree on a\n  constant would write different permanent decisions for identical bytes.\n- `events`, name + payload schema; events ride the journal contract on the event plane\n  (`epe\u2026.ev.<cluster>.<event>`), read-contained by event-topic grants.\n\n**Effect.** A command declaration carries `effect`, one of `read` or `write`.\n\n**Reachability.** `effect` is reachable only under `protocol.v: 2` (*Version*, below). A responder\nwhose descriptor is pinned to `v: 1` cannot declare the field on the command surface a caller\nresolves against, and nothing in such a deployment consumes it, so the `v: 1` rule below is the\nwhole of what governs.\n\nNote what the pin does NOT do. A descriptor MAY inline the registered cluster artifact verbatim\n(*Descriptor and describe*, \xA713.7), and an artifact is not filtered against the parsed command\nsurface, so a key named `effect` inside one can appear on the wire under a `v: 1` descriptor. Its\npresence there is not a declaration and MUST NOT be read as one. Repeat-safety information exists\nonly at `protocol.v: 2`, and a caller that recovers it from raw artifact bytes under a `v: 1`\ndescriptor has reinstated exactly the retry this section exists to stop, while believing it read a\ndeclaration. A reference implementation that has not moved to\n`2` therefore carries its repeat-safety knowledge somewhere off the wire, as a static allowlist of\nthe commands it knows to be safe to repeat. Such an allowlist stands in for this field for exactly\nas long as no `v: 2` descriptor can exist, and it is superseded by the declaration the moment one\ncan: allowlist-says-safe and author-declares-`write` are answers to the same question, and two\nanswers to one question is one answer too many.\n\n`read` asserts that executing the command again **changes nothing the command is trying to\nchange**: the state after two executions is the state after one, and any difference between their\nresults is only the freshness a caller would see by asking twice. The state in question is not\nonly the endpoint's own \u2014 a command whose intended effect lands somewhere else is still a `write`.\n`evictPrincipal` on the delivery endpoint is the case that fixes the boundary: it drops live\nbroker connections and leaves the endpoint's own records untouched, and it is a `write`, because\ndropping those connections is the point of calling it.\n\nExactly one class of difference is excluded, and it is narrow: the incidental trace of having been\ncalled. Request ids, spans, access logs, metrics, counters, and timing are observable and are not\nwhat the command was for, so a command is not `write` merely because it can be seen to have been\ncalled. The test is not \"did anything change\" \u2014 something always does \u2014 but **would a caller who\nrepeated this command be surprised by what the repeat did**. If the answer is no, it is `read`.\n\n`write` asserts nothing and MUST be assumed unsafe to repeat.\n\nA client MUST NOT automatically re-issue a command declared `write` after any outcome that does\nnot prove non-execution (\xA713.3), **whatever `id` the re-issue carries**. The exemption is not the\ntoken but the CONVERGENCE: a re-issue is a resubmission, governed by \xA713.8 rather than by this\nrule, only while the responder will converge it onto the recorded prior decision. A re-issue the\nresponder accepts as NEW WORK is a repeat, and this prohibition binds it however the `id` was\nchosen.\n\nThat distinction is load-bearing because the two are not distinguishable by inspection. Same-`id`\nconvergence lasts only while the prior decision is retained (\xA713.8), and a caller cannot observe\nretention from outside \u2014 so a client that reuses an `id` after the horizon has issued a repeat\nwhile believing it issued a resubmission. Reusing the token is therefore not a substitute for the\nproof this rule demands: absent an outcome that proves non-execution, a client that cannot\nestablish convergence MUST treat its re-issue as a repeat and MUST NOT make it automatically.\n\n`effect` is a property of the command, not of its delivery class: `class` says how a request is\ncarried, `effect` says whether carrying it twice is safe, and the two are independent \u2014 an\n`ephemeral` command may be either.\n\n`effect` is declarative, and a declaration is a claim the endpoint author makes. It binds\nclients, not the responder: nothing in this section relieves a handler of its own correctness,\nand a `read` declaration over a mutating handler is a defect in the endpoint, not a licence.\n\n**Version.** `effect` cannot be introduced additively. A client that does not implement it\nignores it and retries exactly as it did before, and no default value repairs that direction,\nbecause the field's entire purpose is to STOP a retry an older client already performs. So it\nrides the discovery protocol's version marker rather than the unknown-field rule (\xA77).\n\nThat marker is the one that already exists: `protocol.v` on the **service record spec and the\ndescribe descriptor** (*Descriptor and describe*, below). It is deliberately not a new field on\nthe cluster document, which has no `protocol` of its own \u2014 adding one there would be subject to \xA77\nand dropped unread by exactly the clients this cut has to stop, which is the failure it is meant\nto prevent. An instance whose registered clusters declare `effect` MUST register and describe with\n`protocol.v` of `2`, and every command in every cluster it serves MUST then carry `effect`. `v:1`\ndescriptors remain valid, carry no `effect`, and give a resolving caller no repeat-safety\ninformation \u2014 it MUST treat every command served under one as `write`. There is therefore no\n\"omitted `effect`\" case under a `v:2` descriptor, and no surface in which the field is present but\noptional.\n\nA client that does not implement this section MUST refuse to resolve a descriptor whose\n`protocol.v` it does not implement, rather than ignore what it cannot honor. **That refusal is a\nrequirement this section CREATES, not one already met.** What protects an unamended client today\nis a fence on the other side of the wire: `describe`'s pinned output schema fixes\n`descriptor.protocol.v` to the constant `1`, so an unamended responder cannot publish a `v:2`\ndescriptor at all \u2014 its own reply fails output validation and surfaces as a responder bug. The\nregistry read path fails closed the same way, refusing a service record whose `protocol.v` is not\n`1`. The resolving caller does neither: it reads the describe answer without validating it, and\nthe shape it reads does not carry `protocol`. So the version marker is enforced today by the\nRESPONDER's contract and by the REGISTRY reader, and by nothing in the caller \u2014 which is safe only\nfor as long as no `v:2` descriptor can exist.\n\n**Emission.** Moving to `protocol.v: 2` **is** a non-additive discovery change, so \xA711's\nchange-process rule for one governs it and is the authority on how it is rolled out; this section\nadds only what is specific to `2` and states no cutover rule of its own.\n\nSpecific to `2`: a caller that resolves a descriptor whose `protocol.v` it does not implement MUST\nfail the resolve (`unsupported-version`) and MUST NOT invoke against it \u2014 a descriptor it cannot\nread is not a weaker descriptor, it is no descriptor, and treating it as `v:1` reinstates exactly\nthe repeat this section exists to stop. Implementing that refusal is what makes a caller count as\nhaving adopted this section for the purposes of \xA711's rule, which is the condition a responder's\ndeployment must satisfy before any responder in it registers or describes at `2`.\n\nWhy the rule lives there and not here: the condition is a property of the whole deployment, and a\nresponder cannot evaluate it from where it stands \u2014 per \xA711 there is no in-band capability\nnegotiation and no request carries a caller version, so a responder cannot tell an amended caller\nfrom an unamended one. A rule stated here would bind the one party unable to check it. \xA711 assigns\nit instead to the deployment, which can.\n\nAn **endpoint type** is a conformance set of cluster URNs. `manager` and `delivery` are\nordinary conformance sets defined by the reference implementation; core knows only\n\"endpoint\".\n\n**Schemas.** Contract schemas are JSON Schema **2020-12**, validated by a real 2020-12\nvalidator (the reference implementation pins `ajv`), under this normative resource profile: a\nschema is a **closed resource bundle**, either fully self-contained (local `$defs`/`#/\u2026`\nrefs) or referencing other contract-store artifacts **by digest** only. `$id`/`$anchor`/\n`$dynamicRef` resolve deterministically within the bundle; ambient HTTP/file/URI resolution\nMUST NOT occur. Contract identity is the **closure digest** (above): the digest of the\nmanifest naming the complete resolved closure, not of the root document alone. Registration-time bounds (loud `contract-invalid`, distinct from\ninvocation-time `bad-request`): document \u2264 256 KiB, closure \u2264 1 MiB, nesting \u2264 32, ref chain\n\u2264 32, bounded pattern complexity, compile/validation time budgets, and a bounded compiled-schema cache (reference: 256-entry LRU) (\xA713.8). Runtime\nvalidation at the serving boundary is mandatory: args before any effect, replies against the\noutput schema. Authoring tooling is free (the reference implementation authors in Zod); the\nwire artifact and validation semantics are the JSON Schema documents themselves.\n**Every command declares BOTH an input and an output schema**: a side with no payload\ndeclares the **canonical void schema**, the artifact `{\"type\":\"null\"}`, whose RFC 8785\ndigest is therefore one fixed value, so both `op` digests exist for every command (\xA713.3)\nand no shape in this section is conditional on a missing side. Validation against the void\nschema means the side's payload is absent or `null`.\n\n**Content addressing.** A contract artifact (cluster document, schema bundle member, trait\ndefinition or attachment) is identified by the SHA-256 digest of its RFC 8785 canonical JSON\n(strict RFC 8785 over I-JSON; the reference implementation pins `json-canonicalize`'s strict\npath and gates on the RFC's published test vectors, including number-serialization and\nsurrogate edges). **Two digests, never conflated.** An **artifact digest** identifies ONE\ndocument's bytes and is the value that keys its subject and every by-digest reference. A\n**closure digest** identifies a whole resolved bundle, a cluster document or a schema\nclosure, and is the artifact digest of that bundle's **manifest**: the artifact\n`{ v: 1, root: <artifact digest>, members: [<artifact digest>, \u2026] }`, `members` being every\nartifact transitively reachable through by-digest references from `root`, sorted\nlexicographically and deduplicated. The manifest is itself an ordinary artifact on its own\ndigest subject, so a closure digest is an artifact digest, nothing dispatches on which kind\na digest is. Contract identity (\xA713.7 `contractDigest`, `clusterDigests[]`, and the\n`op.inputDigest`/`outputDigest` a caller pins) is always a CLOSURE digest; a `$ref`-by-digest\ninside a schema is always an ARTIFACT digest.\n\n**Every `*Digest` field in this section is one scalar shape**, `sha256:<hex>`, lowercase\nhex, and each names exactly one input, so no field's digest is implementation-defined:\n`inputDigest`/`outputDigest`, `contractDigest`, `clusterDigests[]` = the CLOSURE digest of\nthe named bundle (above); a schema's by-digest `$ref` = an ARTIFACT digest;\n`argsDigest`/`outcomeDigest`/`resultDigest` = over the strict RFC 8785 canonical JSON of\nthat value (absent iff the value is absent); `authDigest` = over the raw UTF-8 bytes of the\n`auth` slot as carried (\xA713.3); `submissionDigest` = over the raw stored submission bytes\n(\xA713.4). Integer fields on the wire (`sourceSeq`, `revision`, `epoch`, `ts`,\n`deadlineMs`, `readinessDeadlineMs`) are non-negative integers \u2264 2^53 \u2212 1, the I-JSON\ninteroperable range, so at most 16 decimal digits, which is what makes the \xA713.12\nmaximum-fact fixture a computable worst case rather than an estimate.\n\nArtifacts live in the per-space **contract stream**: one artifact per\ndigest-keyed subject `cotal.<space>.epc.<digest-hex>` (\xA713.2), published as a single\nmessage; possible because a document is bounded at 256 KiB (below) and the operator floor\nasserts `max_payload` covers it (\xA713.12); a closure is fetched artifact-by-artifact through\nits digest references, never as one blob. Reads are the subject-scoped last-by-subject\nDirect Get on the exact digest subject, no consumer, no replay machinery, and nothing\nbody-selected (\xA713.9). Readers MUST verify fetched bytes against the digest and fail loud\non mismatch. Publication is mediated and create-only (\xA713.9): artifacts are immutable once\npublished. A single-message digest subject is readable subject-confined; a chunked object\nstore is not, because chunk replay needs a consumer whose delivery target is body-selected\n(\xA713.9).\n\n**Record kinds and key grammar.** Every record kind is registered: core kinds are defined\nby this section (writer table, \xA713.9), and each kind's registry entry pins its **key\ngrammar** (the qualifier tokens between the kind token and the `.spec`/`.status` suffix),\nits writer roles, and its mediation class; grants and merged watches are derived from that\ngrammar, so two implementations always agree on which key carries what. The core kinds'\nkey grammars, pinned here (each key then splits `.spec`/`.status` per \xA713.4, EXCEPT the\nunsplit atomic keys the table marks: the `lifecycle` head, `govern`, `uid`, `oblig`,\n`goalidx`, `goaleff`, `epname`, `epmig`, and `answer`):\n\n| Kind | Key grammar |\n| --- | --- |\n| `svc` | `svc.<endpoint>.<instanceId>` |\n| `signer` | `signer.<keyId>` |\n| `handle` | `handle.<issuerKeyId>.<id>` |\n| `contracts` | `contracts.<endpoint>` |\n| `goal` | `goal.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>` |\n| `goalidx` | `goalidx.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>` (atomic; an in-flight action's reconcile index, written create-only before the goal binds and deleted at its terminal, enumerated by a bounded boot-sweep authority so a superseded executor's orphaned goals settle; never caller-addressed). The reference local signer composition uses its ephemeral provisioner. The signerless remote-manager composition uses an authenticated host operation backed by a sealed, owner-filtered `goalidx.manager.<cOwner>.>` scan; no participant credential carries records consumer create or delete. Writer: the **goal-writer** principal (\xA713.9), which composes the commit principal with three additions, this index subtree among them, and NOT the bare commit principal, whose enumeration does not reach this kind. The two are separated because the index is created BEFORE the bind, so the principal that writes it is the one that also binds; a deployment that grants the index on the bare commit row has widened every commit principal to reach a key only the goal writer needs |\n| `goaleff` | `goaleff.<endpoint>.<cOwner>.<cActor>.<cUid>.<goalId>.<gen>` (atomic; the at-most-one-launch election for one accepted action, written create-only by the effects executor that wins it and advanced by revision-CAS through its phases). `<gen>` is the accepted submission's **EPJ `sourceSeq`**, the sequence it was delivered at, carried verbatim into the acceptance fact; the only discriminator that exists at the EARLIEST coordinate, since `goalidx` is created before the bind and therefore before any decision fact exists, so a decision sequence cannot key it. The generation token is what keeps this kind out of the one-use-forever trap: a lawful later acceptance under the same `goalId` gets a different `<gen>` and a fresh key, never a permanent tombstone. Writer: the owning endpoint's **commit path** ONLY (\xA713.9), inherited by the goal-writer principal that composes it; the generic per-kind spec/status writer row does not reach it, because this kind is unsplit and has no `.spec`/`.status` to write. The value machine, including which actor may settle a row, is *The two coordination machines* below |\n| `epname` | `epname.<endpoint>.<nameToken>` (atomic; the durable claim on one name, keyed by the NAME rather than by a caller triple, because the thing being made exclusive is the name and two callers must contend on one key). Writer: the owning endpoint's **commit path** ONLY (\xA713.9); unsplit, so create-only for the claim and revision-CAS for every state change. The state machine, its actor roles, and the claimant union are *The two coordination machines* below |\n| `epmig` | `epmig.<endpoint>` (atomic; the endpoint's cutover manifest: the inventory a migration is performed against, and the durable record of the cutover runs performed against it, so a run generation is never reused by a later run). That run generation is **scoped to cutover and is key material nowhere else**: the `<gen>` token in the `goaleff` grammar is the accepted submission's EPJ `sourceSeq` and only that, the `goal`, `goalidx`, and `goal\u2026.result` grammars carry no generation token at all, and an implementation that keys any of them from this manifest has built an election two conforming peers can never meet inside. Writer: the owning endpoint's **commit path** ONLY (\xA713.9); unsplit, and its qualifier profile is `[qEndpoint]` alone, one manifest per endpoint, never one per caller or per run |\n| `cp` | `cp.<endpoint>.<token>` |\n| `lease` | `lease.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` (the item's acceptance identity, \xA713.2) |\n| `lifecycle` | `lifecycle.<owner>.<actor>.<lifecycleUid>` (the \xA713.1 mapping detail) |\n| `lifecycle` head | `lifecycle.<owner>.<actor>`; the alias's **authoritative current mapping**, and the ONLY key `mappingRevision` (\xA713.3) counts: a **single unsplit key** (NOT `.spec`/`.status`-split; the mapping is one atomic record, and a handler's \"fresh current mapping\" read is one leader-consistent read of this key returning `{ mapping, revision }`, the revision being the STORE revision, never a value field), CAS-updated, NEVER-DELETED (the head discipline: no grant permits DEL/PURGE, true absence alone is virgin, a deletion marker refuses loudly as corruption). States `active | retiring | retired` (\xA713.1): the mapping is current ONLY at `active`; `retiring` is the op-bound containment phase, non-current and not replaceable; `retired` asserts the completed \xA713.1 barrier. Activation CASes it from none (create-only) or from a `retired` predecessor to a freshly reserved UID's mapping; two concurrent mints for one alias cannot both win the CAS; the terminal barrier CASes `active \u2192 retiring` at its bar and `retiring \u2192 retired` as its final head step. The per-UID `lifecycle.<owner>.<actor>.<lifecycleUid>` detail below is optional append-only audit, never the authority |\n| `uid` | `uid.<lifecycleUid>`; the \xA713.1 **space-global UID reservation**: a **single unsplit key**, create-only, NEVER-DELETED, value = `{ owner, actor, mintedBy }` (the reserving authority and intended alias, audit only; the KEY is the reservation). A key exists for every UID ever reserved, including burned candidates; a DEL/PURGE marker is corruption |\n| `policy` | `policy.<endpoint>.<digest-hex>`; the \xA713.6 **immutable admission-policy version**: a **single unsplit key** per policy version, create-only, NEVER-DELETED. `<digest-hex>` is the SHA-256 hex (64 chars) of the record's canonical value bytes, so the key is SELF-CERTIFYING: a reader re-digests the value it read and refuses a mismatch. Immutability is a TRUSTED-WRITER invariant (create-only CAS by the sole writer) BACKED by that read-time self-certification, not a broker subtraction (KV create/update/delete share the one subject, \xA713.9): a different-byte overwrite is refused on read, and the residual (a DEL or same-byte overwrite by a buggy/compromised writer destroying availability under history 1) fails admission closed rather than admitting a lost policy. `enforcedPolicyKey`/`pendingPolicyKey` on the govern head (\xA713.6) name keys of exactly this kind, which is what keeps BOTH the enforced and the pending policy readable through a mutation's whole drain window. Writer: the provisioner registration path ONLY (\xA713.9); a DEL/PURGE marker is corruption |\n| `oblig` | `oblig.<targetUid>.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`; the \xA713.8 **target-indexed acceptance obligation**: a **single unsplit key** whose grammar IS the deterministic acceptance identity (target lifecycle UID first, so a retirement barrier enumerates `oblig.<targetUid>.>`), create-only winner, monotonic value states, NEVER-DELETED. An admission under policy with NO target lifecycle keys the row with the fixed sentinel target token `ep` (which the \xA713.1 UID token grammar can never produce, so no collision exists): `oblig.ep.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`: excluded from retirement drains (it binds no lifecycle) and included, like every targeted row, in the endpoint's policy drain via the endpoint-position filter `oblig.*.<endpoint>.>` (\xA713.6/\xA713.8) |\n| `frontier` | `frontier.<lifecycleUid>`; the \xA713.1 **per-stream retirement frontiers**: a **single unsplit key** per retired lifecycle, create-only, NEVER-DELETED, value = `{ lifecycleUid, opId, streams }` where `streams` maps each lifecycle-bounded stream to its last sequence at retirement. Written by the terminal barrier AFTER the obligation drain, the drain's repair-principal fence, the pool cleaner, and the cleaner-credential revoke+evict, and BEFORE the gate/head terminals (\xA713.1 order), so a `retired` head implies its frontier exists. The cutoffs bound the predecessor's half-open interval `(activationFrontier, retirementFrontier]` (\xA78); they are never a successor's start (a successor captures its OWN activation frontier). Writer: the minting authority's retirement barrier ONLY; it records once, under its own operation (a foreign-op record refuses the barrier closed); a DEL/PURGE marker is corruption |\n| `govern` | `govern.<endpoint>`; the endpoint's **governance head**: a **single unsplit key** (NOT `.spec`/`.status`-split), value = the endpoint's MONOTONIC binding map, command to governed URN set, the NORMATIVE **admission-policy selector** `{ enforcedPolicyKey, enforcedPolicyRevision, pendingPolicyKey?, pendingPolicyRevision? }` (\xA713.6: `enforcedPolicyKey` is the exact records key of the immutable `policy` record currently governing admission and `enforcedPolicyRevision` its store revision, so any implementer selects the endpoint-wide enforced policy WITHOUT per-instance guesswork; a mutation stages `pendingPolicy\u2026` and promotes it into `enforcedPolicy\u2026` only after the endpoint's obligation drain, so the selector alone decides which revision governs during the drain window), plus whatever internal serialization state the provisioner's registration CAS needs (that state is non-normative: a second implementer may linearize registration with a different slot shape and conform, provided every registration contends on this head under its frozen gate through spec publication, the policy selector fields carry the meaning above, and the external guarantees hold). One of those external guarantees is LIVENESS of the linearization itself, and it is normative however the slot is shaped: an in-flight registration that stops before its spec publication MUST NOT block the endpoint's registrations permanently. Whatever state a registration holds on this head, an implementation MUST be able to decide that state ABANDONED from durable facts rather than from a liveness probe, and a later registration MUST then be able to take it. The reference implementation decides it by comparing the held state's recorded gate generation against the holder's live issuance gate: a gate that has reopened past it proves the hold can never complete, since completion requires that same generation still frozen. An implementation that cannot make that determination MUST refuse rather than take the hold, because an in-flight registration and an abandoned one are otherwise indistinguishable, and taking a live one would put two registrations through the linearization point at once. Enforcing the governed-attachment no-strip/no-downgrade mandate (Traits, below) is a HISTORY-bearing, ENDPOINT-WIDE property: a fresh instance, a remove-then-re-add, or a concurrent registration must not launder a governed binding away, so this head is also the endpoint's **registration linearization point**. Writer: the provisioner registration path ONLY (\xA713.9); NEVER-DELETED, per the `lifecycle`-head discipline |\n\n| `run` | `run.<endpoint>.<runId>`; a **workflow run's** last-value-wins state beside its append-only step journal (\xA714). `.spec`/`.status`-split, and the split is load-bearing: the spec is what the run IS, decided once at start and never rewritten (`{ v: 1, run, pins, createdAt }`, the resolved PIN SET of \xA714.3), the status is what it is DOING (`{ v: 1, observedSpecRevision, state, holder, epoch, fencingToken, journalHigh, at }`), so a lease renewal can never rewrite the pins. `<runId>` is an id token minted by the DRIVER, never caller-supplied and **never reused**: a run is never re-run under its own id (that is a fork, and a fork takes a new id), so a deleted `run` key staying closed is correct and no generation token is owed. A fork's child is a new run under a new id and this revision records no lineage on it (\xA714.3); a later revision that adds a parent field puts it on the SPEC half and never the status half, because parentage is decided at creation and a status-half lineage could name a different parent after a takeover. Writer: the run driver's commit path ONLY (\xA713.9) |\n| `answer` | `answer.<endpoint>.<token>.<answerId>`; a checkpoint's ANSWER payload beside its one-use settle fact (\xA713.6, `answerId`/`settledAnswerId`): a **single unsplit key**, create-only, never updated and never deleted, value `{ v: 1, token, answerId, value?, artifact?, by, at, supersedes? }` (`supersedes` only on an amendment, \xA714.5). **Keyed per answer rather than per presenter because a workflow checkpoint's holder is the run driver and every resolver reaches the checkpoint through it, so every presenter is the same principal**: a presenter-keyed slot collapses to one, two racing resolvers overwrite it, and the settlement then selects whichever answer was written last rather than the one that won. `<answerId>` is derived from the answer's own content (\xA714.5), so a retry after a crash lands on its own record with its own bytes; an amendment's is minted fresh per filing (\xA714.5). Writer: the run driver's commit path ONLY (\xA713.9) |\n| `notice` | `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>`; one bounded decision a workflow told one agent (`notify`, [`spec/cotal-lang.md`](spec/cotal-lang.md) \xA76.8), filed onto the run and rendered ahead of that agent's next turn, never a channel message. `.spec`/`.status`-split: the spec is the notice (`{ v: 1, run, step, addressee, fact, at }`) and is create-only, the status is its consumption (`{ v: 1, consumedAt, by, observedSpecRevision }`). **`<addresseeId>` is a digest of the agent's name and never the name, because an agent name is dotted and a dot is the key separator**: a raw name re-tokenizes the key into a key of another shape, and mangling it destroys the identity being keyed on; a reader holding the handle re-derives the same token (\xA714.5), so per-addressee enumeration stays one prefix scan. `<noticeId>` is derived from the step's request id and the addressee, so a `notify` re-run after a crash lands on the same records. Writer: the run driver's commit path ONLY (\xA713.9) |\n| `migration` | `migration.<endpoint>.<runId>.<migrationId>`; one run's move onto edited source ([`spec/cotal-lang.md`](spec/cotal-lang.md) \xA711.2): what the divergence-and-orphan check found, which refusals a person overrode, and who they were. `.spec`/`.status`-split: the spec is the REPORT (`{ v: 1, run, fromHash?, toHash, at, consumedThrough, orphans[], overrides[], actor }`) and is create-only, the status is the APPLICATION (`{ v: 1, appliedAt, by, observedSpecRevision }`) and names the driver that advanced the run. Its own kind because it is neither half of the run record: a migration is append-only history with an actor on it, and a run can migrate more than once, so the status half would let the second erase the first and the spec half cannot be written twice. **`<migrationId>` is a digest of the report's own content and never a counter**, because a migration is decided by a dry walk a crash can force to be re-run, so the same decision must land on the same record rather than filing a second one, and a counter would need a second arbiter for a fact the content already determines (\xA714.5). **The application is create-only for the same reason the notice's consumption is**: two drivers racing to advance one run both find no status and both write, and the store decides which one moved it. Writer: the run driver's commit path ONLY (\xA713.9) |\n\nThird-party kinds\nregister under reverse-DNS kind names.\n\n**The two coordination machines.** `goaleff` and `epname` carry closed value machines. A row's\nlegal field set is fixed per phase or per state, and a writer that presents a field the phase does\nnot define, or omits one it does, is refused rather than accommodated: a single broad object with\neverything optional cannot express that a field is present exactly when a launch is in flight, and\npresent-exactly-when is the only form in which those fields decide anything.\n\n`goaleff` has four phases: `claimed`, `launching`, `launched`, `settled`. Every row carries `v: 1`,\nthe electing `executor` as an incarnation `{ instanceId, processEpoch }`, the `attemptId` nonce of\nthe attempt that won the election, and `ts`. `launching` and `launched` additionally carry `addr`,\nthe allocated address `{ nameToken, lifecycleUid }`; `settled` MAY carry it; `claimed` MUST NOT.\nThe legal edges are `claimed \u2192 launching`, `claimed \u2192 settled`, `launching \u2192 launched`,\n`launching \u2192 settled`, and `launched \u2192 settled`. `settled` is terminal because no edge leaves it,\nwhich is the terminality rule itself rather than a separate check that could come to disagree with\nthe table. The `executor` and `attemptId` do not move across an edge, and an allocated `addr` is\nnever rewritten to a different one.\n\nTwo actor roles take those edges. An **executor** may take any of them and MUST be the row's own\nexecutor at the row's own `attemptId`: a re-read that finds a foreign incarnation or a foreign\nnonce is a loss, never a licence to proceed. A **sweeper** acts for an executor it believes is gone\nand MAY take only the edges into `settled`, because advancing a launch phase on a dead executor's\nbehalf is the split brain the election exists to prevent, and the resulting row is\nindistinguishable from the executor having advanced it. An actor presenting neither role is\nrefused; an unrecognized role that falls through both checks is the most permissive possible answer\nto the question of who is acting.\n\nEvery settle is gated on the goal's terminal fact **already existing**. Settling without one\npublishes a row asserting that a goal finished when nothing durable records that it did, so the\nterminal-first order is normative and the reverse order is never legal. A crash between the two is\na row left un-settled with its terminal present, which is recoverable; the reverse would not be.\n\n`epname` has seven states: `claimed`, `launching`, `live`, `preserved`, `relaunching`, `draining`,\n`released`. Every row carries `v: 1`, `ts`, `state`, and `claimant`, which is either `null` or one\nof three kinds: an **action** claim `{ goalId, gen }`, a **direct** claim\n`{ instanceId, processEpoch, opId }`, or an **incumbent** claim `{ backfillId }` recorded by a\ncutover backfill. A launch in flight (`launching`, `relaunching`) additionally carries\n`lifecycleUid`, `launchAttemptId`, and the `executor` incarnation; a name that is up (`live`,\n`preserved`) carries `lifecycleUid` and `runtimeOwner`; `draining` carries `lifecycleUid`,\n`runtimeOwner`, and `enteredAt`; `claimed` and `released` carry the base fields alone.\n\n`runtimeOwner` is the incarnation that owns the handle table for the name, and it is **moved, never\nderived**. It MOVES on the four launch-resolving edges, `launching \u2192 live`, `relaunching \u2192 live`,\n`launching \u2192 draining`, and `relaunching \u2192 draining`: the row's full `executor` incarnation becomes\nits `runtimeOwner` and `launchAttemptId` is cleared, recorded at the moment it becomes true. Both\nfields of the incarnation move together, because an `instanceId` without its `processEpoch` names a\nprocess rather than the run of it that holds the handle table. On the three edges that neither\ncreate the row nor resolve a launch, `live \u2192 preserved`, `live \u2192 draining`, and\n`preserved \u2192 draining`, it is CARRIED unchanged. The one creation edge that produces a `live` row,\nthe cutover backfill, INSTALLS it instead, read from the incumbent's own live gate row: a cutover\nthat cannot read one MUST record a casualty rather than backfill, because a `live` row whose owner\nis unknown puts an unevaluable value into the durable record that every later release reads. Except\non that edge it is never reconstructed from any other row, because a supported deployment mode has no such row to read and a\npredicate that cannot be evaluated on a supported path either refuses forever or falls back to\nabsence. An `instanceId` alone will not stand in: an identity is not an incarnation, and a\nrestarted process under the same identity holds an empty handle table, which is the absence of\nknowledge rather than knowledge of absence.\n\nSix actor roles take the `epname` edges. An **allocator** creates a claim (`\u2192 claimed`, and\n`released \u2192 claimed`, so a released name is claimable again and the row is never deleted). A\n**claimant** drives its own launch (`claimed \u2192 launching \u2192 live`) and may abandon an unlaunched\nclaim (`claimed \u2192 released`). A **holder**, identified by the row's `lifecycleUid`, drives the\npreserve cycle (`live \u2192 preserved \u2192 relaunching \u2192 live`). A **sweeper** may release an unlaunched\nclaim and may move `launching`, `live`, `preserved`, or `relaunching` into `draining`. A\n**cutover** may establish a `live` incumbent directly, which is the backfill path. An **operator**\nhas exactly one edge, `draining \u2192 released`.\n\nThat last edge is operator-only by design rather than by omission. An ordinary release would\nrequire an actor attesting that a runtime is gone, and no such actor can exist: an owner still\nalive has no per-attempt handle to attest about, and a restarted one is a different incarnation.\nThe edge is therefore removed rather than weakened, and `draining` is a state an operator clears by\nhand until a durable runtime-attempt token exists. Two consequences follow and are normative. A\ngoal reaching a `succeeded` terminal does **not** release the name it holds; and release is a\ntransition to `released`, never a delete, so the row survives to answer who held the name last.\n\n**The actor roles above are entitlements inside the value machines, not wire principals, and which\nprincipal may present each of them is unspecified: RAISED, NOT SETTLED.** The write grants on both\nkinds are the commit path and the goal-writer principal that composes it (\xA713.9). No sweeper,\noperator, allocator, or cutover principal is granted anywhere in this document, so this section\ndoes not say whether a conforming sweep runs under the commit principal or under a principal a\ndeployment would have to add. An implementation MUST NOT read a role in these machines as\nconferring a grant, and a deployment that needs a distinct sweep identity is outside what this\nversion specifies.\n\n**Descriptor and describe.** Each instance registers a **service record** (kind `svc`, key\n`svc.<endpoint>.<instanceId>`; the owner is determined by the name and recorded in the\nvalue): spec = `{ endpoint, owner, endpointType?,\nclusterDigests[], protocol: { v: 1 | 2 }, activation? }`, status = `{ epoch, state,\nobservedSpecRevision, \u2026 }` (writer table \xA713.9). The spec key's **store revision is the\ninstance's `registrationRevision`**, the value scatter freezes (\xA713.5): it advances only\nwhen the mediated registration path writes the spec key, so an advance during a scatter is\nexactly a re-registration. The `processEpoch` of the instance's issuance gate (\xA713.1) is 0 after\nthe first registration of its `instanceId`, and each later registration of it commits the previous\nepoch plus one. Epoch 0 is open and serving like any later epoch, and a consumer or sweeper MUST NOT\ntreat it as absent or not ready. `describe` is a reserved untargeted\nephemeral command every endpoint MUST serve, returning the descriptor with clusters inline or\nby digest. **Authorization-scoped answers use a trusted authorization source only**: the\nanswer is intersected against a fresh view of the caller's authority obtained from the\ndeployment's authorization ledger/callout (\xA79/\xA710), keyed by the broker-authenticated caller\nidentity, never against payload- or slot-asserted scope, which is ignored. If the trusted\nview is unavailable or stale beyond its declared freshness bound, describe fails closed\n(`unavailable`) rather than answering from a weaker source; deployments MAY declare an\nendpoint's descriptor public, in which case no view is consulted and the answer says so.\nDescriptor visibility is never inferred from reachability of `describe` alone. A KV browse\nindex (record kind `contracts`) is an advisory convenience copy; `describe` is authoritative.\n\n**Manager-service records.** A remote manager registration is one closed, opaque-instance family:\nits `svc.manager.<instanceId>` spec/status pair, its instance-bound contract closure, and its\n`epgate.manager.<instanceId>` / `epcred.manager.<instanceId>.<credentialId>` rows all name the\nsame server-authorized `{ owner, managerActor, lifecycleUid, instanceId }` tuple. The registration\nmediator MUST reject any tuple mismatch, instance collision, contract substitution, or status/gate\noperation from another principal or lifecycle. It may publish only the contract artifacts staged by\n`prepare`; it may not use manager-service authority to publish a contract for any other endpoint.\nRetiring the family retires the instance record and gate together; no stale stage, registration,\ncontract, status, or credential can activate a new lifecycle or another instance. `describe` and\nstatus report the manager instance's serving/degraded state without treating discovery as\nauthorization (\xA713.9).\n\n**Invocation binding.** The digests are not caller courtesy but a two-sided requirement\n(\xA713.3): a caller MUST pin `op.inputDigest`/`op.outputDigest` on every command except\n`describe` (the discovery bootstrap), and a serving member MUST reject their absence\n(`contract-mismatch`) before any effect; an unpinned invocation cannot silently bypass the\ndescribe\u2192invoke binding, and MUST honor pinned digests or reject `contract-mismatch`. Rolling updates keep classes contract-homogeneous: an incompatible\ngeneration registers a distinct routable identity (new endpoint name or explicit version\nlabel) until homogeneous.\n\n**Traits.** A trait attaches governed metadata to a cluster, command, attribute, or event.\nA **trait definition** `{ urn, valueSchema (digest), selector, breakingChanges, authority }`\nis content-addressed and signed: `ai.cotal.*` definitions by the space-operator authority;\nthird-party definitions by their defining owner's registered key. **Attachment authority is\ndistinct from definition authority**: every *required/governed* attachment (this revision governs\nexactly `ai.cotal.guarded` and `ai.cotal.priced`) is separately signed by the definition's\nnamed authority over `{ endpoint, command, contractDigest (the cluster document's complete\nclosure digest), traitUrn, value }`, so a self-published descriptor cannot strip, forge, or downgrade a governed\nannotation; removal or downgrade is an authorized contract revision. Enforcement is\nfail-closed at the pre-effect seam: missing, unverifiable, or stale governed attachments\nrefuse before effect. Non-governed traits are unsigned vocabulary.\n\n**Compatibility.** Cluster evolution is BACKWARD by default: within a revision line, changes\nMUST be additive and added fields MUST carry defaults; removal, rename, or semantic change\nmints a new cluster URN version. A push-time JSON-native compatibility differ + review gate\nenforce this in the reference workflow (repository tooling under `scripts/`, not shipped\nclient code). The discovery protocol itself is versioned under `protocol.v`, additively by\ndefault: a bump is reserved for a change a client cannot safely ignore, and `effect` (\xA713.7) is\nthe one such change so far \u2014 a client that ignored it would keep performing exactly the retry the\nfield exists to stop, so it refuses the document instead.\n\n### 13.8 Distributed guarantees\n\n- **Idempotency scope.** Ephemeral idempotent commands by `id` (handler-local, within result\n  retention); journaled submissions and actions by `id`/`goalId` + fingerprint within the\n  declared horizon. Exactly-once is bounded honestly: delivery is at-least-once; Cotal\n  guarantees idempotent submission/fact recording and fenced commits of Cotal-owned state; an\n  external side effect is exactly-once only when the external API honors the propagated\n  idempotency key or fencing token, else the contract documents at-least-once effects. A\n  workflow step inside a `once` scope (`spec/cotal-lang.md` \xA77.8) is dispatched at most once per\n  step key whatever the far side honors, a dispatch being one call of its handler under its request\n  id that the handler does not refuse (the handler may retry inside that call): a resume that finds\n  it begun and unsettled opens a hold under a token derived from its recorded request id instead of\n  dispatching it again, trading the run's liveness for the bound.\n- **Repeat versus resubmission.** **A command that is idempotent by `id` is NOT thereby `read`:\n  safe to resubmit is not safe to repeat.** That is the rule neither mechanism states alone, and\n  declaring such a command `read` licenses a fresh-`id` retry that duplicates the effect. The two\n  properties are independent; a command may hold either, both, or neither.\n\n  A **resubmission** is a re-send the responder CONVERGES onto the decision it already recorded; a\n  **repeat** is a re-send it accepts as new work. Reusing the `id` is how a caller ASKS for\n  convergence, and within the horizon below it is how convergence is keyed \u2014 but the `id` is the\n  request, not the answer, and a re-send under a reused token that the responder accepts as new\n  work is a repeat by this definition. `effect` (\xA713.7) governs repeats, whatever token they\n  carry. `id` governs resubmissions \u2014 and what `id` alone is worth differs by rail:\n  - **Ephemeral** \u2014 `id` is the whole key. A same-`id` resubmission within result retention is\n    the same call; an idempotent command may dedup on it and consult nothing else.\n  - **Journal** \u2014 `id` is necessary but NOT sufficient. It is one of the fields the fingerprint\n    binds, so a same-`id` resubmission converges to the first outcome only if the rest of the\n    fingerprint matches too. Same `id` with different args is neither a resubmission nor a fresh\n    call: it is a loud `conflict` (\xA713.4), because the decision subject is already occupied by a\n    fact with a different fingerprint. A caller that mutates arguments and reuses an `id`\n    therefore gets an error rather than either behaviour it might have expected from the\n    ephemeral rail.\n\n  **Both rails are bounded by a horizon, and outside it neither rule applies.** A resubmission is\n  a resubmission only while the prior decision is still retained \u2014 the idempotency horizon is\n  realized by decision-fact retention on the journal rail and by result retention on the ephemeral\n  rail, never by a clock (\xA713.4). Once the retained decision is gone, the `id` carries no history:\n  a re-send under it is a fresh call that WILL execute, and the same `id` with different args is\n  no longer a `conflict` but simply a new submission. The finite horizon is what makes the decision\n  store finite, so this is a fact callers MUST hold rather than a hole to be closed \u2014 but the hole\n  it WOULD open if `repeat` were defined by the token is closed at the definition above: a re-send\n  the responder accepts as new work is a **repeat**, so a post-horizon same-`id` re-send of a\n  `write` is exactly what \xA713.7 prohibits a client from making automatically. Reusing the token\n  buys nothing outside the horizon, and a caller that cannot establish it is still inside one has\n  not established that its re-send is safe.\n\n  Neither word is \"retry\": callers retry under a reused `id` and under a fresh one and mean the\n  same English word both times, which is the confusion this paragraph exists to remove. And the\n  dangerous reading is a REASONABLE one, not a careless one \u2014 an operator who has correctly\n  learned that a command is idempotent by `id` will retry it after a timeout, mint a fresh `id`\n  because the old request is gone, and get a second effect. Nothing in this document told them\n  those were different acts until now.\n- **Fencing and mediated commits.** Every Cotal-owned authoritative transition flows through\n  its mediated writer (\xA713.9) carrying `(fencingToken | lifecycleUid | epoch)` as applicable;\n  the writer validates token currency, unexpired lease against its own clock, lifecycle\n  currency, and epoch currency. Value-carried tokens + CAS stop conforming-but-stale writers;\n  scoped credentials + mediation stop everything else. The threat boundary of any\n  direct-owner write is explicitly downgraded (\xA713.9).\n- **CAS conflict.** Any lost CAS is a loud `conflict`; the loser re-reads and re-decides.\n- **Authority-head reservation/drain.** An authority head (the \xA713.1 lifecycle head; the\n  \xA713.6 registered admission policy) and a durable acceptance/start fact live in different\n  streams; no cross-stream CAS exists, and a revision carried inside a fact is provenance,\n  never a fence. Any durable acceptance or start that creates work bound to a lifecycle,\n  or admits work under a policy read, therefore contends with the head's movement on ONE\n  durable serialization coordinate: the **target-indexed obligation row** (kind `oblig`,\n  \xA713.7). In order: (1) BEFORE the EPF decision publish, the writer obtains the obligation\n  through the **admission mediator**. The mediator owns the `oblig.` prefix (the\n  canonicalizer holds no raw write on it), derives the coordinate from the\n  broker-authenticated request subject (never from a body field), and IMMEDIATELY before\n  the create performs the FENCING currency reads it will pin: for a target-bound\n  admission a leader-served read of the target's lifecycle head, REFUSING unless the state\n  is `active` (a `retiring` or `retired` target admits nothing); for a policy-admitted\n  decision a leader-served read of the governance head (\xA713.6) that FIRST refuses if a\n  `pendingPolicyKey` is present (the endpoint is inside its drain window; the drain-window\n  admission pause is a normative step of THIS algorithm, not only a \xA713.6 property, so any\n  conforming mediator refuses without needing to infer it) and only then follows\n  `enforcedPolicyKey`, self-certifies it (\xA713.7), and pins its `enforcedPolicyRevision` as\n  `policyRevision`. Refusing at the create-fence (not only at the post-create recheck) is\n  also what bounds the row set: a request that could not create its row leaves no\n  never-deleted `oblig` debt behind, so a long or crashed drain cannot accumulate an\n  unbounded set of rejected rows. An admission with no target lifecycle keys the\n  row under the fixed sentinel target token `ep` (\xA713.7). It then creates the row\n  create-only at the deterministic acceptance-identity\n  key `oblig.<targetUid>.<endpoint>.<cOwner>.<cActor>.<cUid>.<id>`. The KEY never contains\n  `sourceSeq`, delivery attempt, mapping revision, or writer op id (a redelivery of the\n  same logical acceptance MUST land on the SAME key); where a digest stands in for the\n  tuple it is a versioned, collision-resistant digest of exactly that tuple, never\n  delimiter-ambiguous concatenation. The VALUE pins the first winner under a CLOSED\n  per-class schema: every row carries `{ state: provisional | accepted | rejected |\n  terminal, decision: epf | self, opId }` plus the currency pins taken above\n  (`mappingRevision` iff target-bound, `policyRevision` iff policy-admitted; at least one\n  present); an `epf`-class row (a canonical acceptance) adds `{ fingerprint, sourceSeq,\n  route }`; a `self`-class row (a guarded record commit, e.g. the restart-status CAS,\n  \xA713.6) adds the COMPLETE commit intent `{ commitKey, commitBaseRevision, commitValue,\n  commitDigest }`: the exact record key its accepted state authorizes, the store revision of\n  that record the commit CASes FROM, the value it commits, and that value's digest.\n  `commitValue` is a CLOSED discriminated union, so two implementations resolve and replay the\n  SAME value: `{ enc: \"b64u\", bytes }` carries a JSON encoding of the committed value,\n  base64url-encoded (RFC 4648 \xA75, no padding), or `{ enc: \"ref\", key }` names an\n  IMMUTABLE, create-only records key (the \xA713.7 `policy` kind or another never-overwritten\n  key) whose stored value IS the commit value; a mutable or absent `ref` target\n  refuses at recovery, fail-closed. Never only a digest (a digest cannot reconstruct the\n  value a crash recovery must re-write). `commitDigest` is the RFC-8785 CANONICAL content\n  digest of the committed value, `sha256:<hex>` (the same `*Digest` scalar shape \xA713.7 uses\n  everywhere; over the CANONICAL value, never a non-canonical storage stringify, so the\n  landed/not-landed comparison is insensitive to how the store serializes the record). A\n  crashed writer's commit is thus deterministically finishable from the row alone (below). The\n  `decision` class is fixed by the TRUSTED operation kind, never caller-selectable. A\n  create loser leader-reads the winner: the FULL pinned identity must match to join (an\n  `epf`-class row on coordinate + fingerprint + route; a `self`-class row on the ENTIRE commit\n  intent `commitKey` + `commitBaseRevision` + `commitDigest`, so two different desired values\n  or base revisions never join under one `commitKey`); any\n  mismatch is `conflict`, never a second obligation. (2) **Proof issuance is a post-create\n  currency recheck, and admission is proof-gated**: after winning or joining the create,\n  the mediator leader-reads the SAME coordinates AGAIN, and only if the target head is\n  still `active` at the pinned `mappingRevision` AND (for a policy-admitted decision) the\n  governance head STILL stages no `pendingPolicyKey` and the enforced policy is still at\n  the pinned `policyRevision` does it return the opaque admission proof; otherwise it\n  IMMEDIATELY settles its own provisional through the row's decision coordinate (below) and\n  refuses. The recheck reads the SAME govern head the create-fence read, so a\n  `pendingPolicy` staged in the window between the create and the recheck also fails\n  proof issuance, not merely a moved `enforcedPolicyRevision`.\n  No target-bound or policy-admitted EPF acceptance may publish, and no `self`-class\n  guarded commit may run, without an unexpired proof issued under this rule. This is the\n  structural half of the head fence: an obligation created in the window between a fresh\n  `active` read and a head or policy movement exists durably, but its proof can never\n  issue, so it can never admit; it is inert cleanup debt any later drain settles. (3) The\n  EPF decision CAS runs as\n  specified (\xA713.4), publishing with the WINNER's pinned acceptance identity and\n  `sourceSeq`, whichever delivery is processing; a `self`-class writer instead advances\n  its own row `provisional \u2192 accepted` (revision-pinned) and performs its guarded commit\n  only while the row is `accepted`. (4) On acceptance the SAME key advances\n  `provisional \u2192 accepted` and is retained until the accepted route is\n  terminal and cleaned: the only enumerable record of accepted work is never\n  erased at the moment it wins. States are monotonic (`provisional \u2192 accepted \u2192\n  terminal`, or `provisional \u2192 rejected`), the row is NEVER-DELETED, and a DEL/PURGE\n  marker is corruption. The stored `opId` is not a bearer capability: a resuming writer\n  re-authenticates as the same endpoint-scoped principal through the mediator and joins\n  by acceptance identity + fingerprint; any opaque reservation token the mediator issues\n  is target/endpoint/connection-bound, bounded-lived, and checked against the CURRENT\n  obligation state; the durable obligation is the authority, never possession of its\n  identifier. **The decision coordinate is per-class** and is where every unresolved row\n  settles: an `epf`-class row settles through the EPF decision subject's create-only CAS\n  (read the winner; if absent, create-only publish the terminal rejection so a delayed\n  acceptance CAS loses; the mediator holds that rejection-publish authority and executes\n  it for its own recheck refusals and on behalf of the drains, \xA713.9); a `self`-class row\n  settles on ITSELF: while still `provisional`, the drain CASes `provisional \u2192 rejected`\n  (the writer's `provisional \u2192 accepted` CAS and the drain's rejection contend on the ONE\n  row, exactly one wins, and a delayed guarded commit finds its authority gone). An\n  `accepted` `self`-class row is NOT stuck and does NOT block quiescence: because the row\n  pins the complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }`,\n  either\n  the writer's own resume OR a drain reconciler drives it `accepted \u2192 terminal`\n  deterministically. Read the record at `commitKey`: if its value canonically digests to\n  `commitDigest` the commit landed, CAS the row `accepted \u2192 terminal`; if it is still at\n  `commitBaseRevision` the commit did not run, re-apply it by CASing the resolved\n  `commitValue` (decode `b64u`, or leader-read the immutable `ref` key's value, verifying its\n  canonical digest against `commitDigest` BEFORE writing) at\n  `commitBaseRevision` then CAS the row terminal; if the\n  record has moved PAST\n  `commitBaseRevision` to a foreign value the intended commit can never land (the guarded\n  CAS would lose), so CAS the row straight to `terminal` as superseded. Quiescence therefore\n  means NO `provisional` and NO un-driven `accepted` `self`-class rows remain: an accepted\n  commit is always completable from the row alone, never an unrecoverable orphan. **Reclamation is never\n  clock-only**, and because the EPF writer need not be the retiring lifecycle (a\n  cross-endpoint canonicalizer publishes decisions bound to a foreign target, and revoking\n  the TARGET's credential family disarms nothing that writer holds), target-side\n  revocation alone is NEVER the reclamation condition. An unresolved `provisional` is\n  reclaimed only by: settling it through its decision coordinate; or revoking +\n  verified-evicting the WRITER's own commit authority; or the target head being\n  non-current AND the drain below having completed to quiescence under the create fence +\n  proof gate. A timeout alone never frees a slot\n  while the writer retains publish authority. **Drain to quiescence**: after the head\n  CASes to `retiring` (\xA713.1), and equally when a policy mutation must enforce a new\n  revision (\xA713.6, enumerating `oblig.*.<endpoint>.>`), the drain enumerates the prefix\n  (`oblig.<targetUid>.>` for retirement), settles every\n  unresolved row through its decision coordinate, completes accept-side reconciliation\n  (enqueue/goal/terminal, \xA713.6) for accepted rows, then RE-ENUMERATES, and records its\n  cleaner and frontier completion (or treats the new policy as enforced) only when an\n  enumeration finds no unsettled row. A provisional whose pinned `mappingRevision` or\n  `policyRevision` is no longer the live coordinate is settled as REJECTION, never treated\n  as still open for acceptance. A row created after the final enumeration cannot admit\n  (its proof can never issue, step 2) and is settled by any later enumeration;\n  an acceptance published after the recorded cleanup frontier from a\n  stale `active` read is non-conformant even if later effect resolution would reject it.\n  Whether the obligation is released once the route is settled under ordinary policy\n  movement (`release-after-accept`) or survives as cleanup debt the terminal barrier must\n  observe (`promote-to-lifecycle-obligation`) is fixed by the TRUSTED operation kind,\n  never caller-selectable. The admission-policy specialization additionally binds\n  identity at the read: the confined policy reader's request subject pins the\n  authenticated canonicalizer endpoint AND the requested policy endpoint, requires their\n  equality, derives the reply rail from that authenticated subject, and returns\n  `{ policy, revision }` with an opaque proof binding `{ space, endpoint, policy\n  revision, obligation/op id }`; endpoint A can never obtain, or replay, endpoint B's\n  admission proof.\n- **Retry/backoff.** Only idempotent-at-scope operations are retried: exponential backoff,\n  base 250 ms, factor 2, cap 15 s, full jitter, bounded by the caller deadline.\n- **Deadlines.** Mandatory on call, scatter, claims, checkpoints, timers, sessions. Reference\n  default call deadline 15 s; defaults are overridable, never removable.\n- **Cancellation ordering.** First terminal fact at the mediated commit point wins.\n- **Watch recovery.** Fell-behind \u21D2 snapshot re-read then resume; bounded relist; no silent\n  gap-skipping.\n- **Ordering/partitioning.** Per-subject only; the subject is the partition key.\n- **Retention floors.** Submissions \u2265 recovery/redelivery lag (\xA713.12; native dedupe is not\n  relied upon, \xA713.4); facts/tombstones \u2265 idempotency horizon;\n  results \u2265 result retention; receipts \u2265 receipt retention; timers \u2265 max deadline + recovery\n  margin. **Pool coupling:** every accepted pool item carries an **absolute work expiry**\n  (`workExpiry`, set at acceptance in the AcceptanceFact, NOT a per-message age a\n  reconciliation re-publish would reset; a re-enqueue re-publishes with the SAME `workExpiry`,\n  and the item is dead once it passes, leased or not). The EPW stream's max age is \u2265 the\n  maximum `workExpiry` + recovery margin, and a pool item's decision and `wrk` terminal facts\n  are retained \u2265 that same bound, so a live (or crash-recovering) item can never outlive the\n  facts that identify it as accepted or settled: a decision that expired under a still-live\n  item would let a reused id collide with the old enqueue, and an expired `wrk` under a\n  lost owner ack would make settled work unrecognizable on redelivery. A reused `id` becomes\n  new work only after the old item's `workExpiry` AND its facts' retention have both passed.\n  An endpoint MUST refuse to start against a store below its declared floors.\n- **Backpressure and budgets.** Bounded consumer pending (default 1024), bounded\n  virtual-endpoint pools and session windows, flow control on watches; overload is\n  `resource-exhausted`. Schema compile/validate budgets (reference: 100 ms / 10 ms) and\n  bounded regex; over budget is `contract-invalid`/`bad-request`.\n- **Timers.** Broker message schedules at the 2.12 floor; same-subject replacement only (at\n  the mediated `.armed` subject, \xA713.12); generation- and scheduler-origin-validated firing\n  (stale or foreign-origin \u21D2 no-op); durable reconciliation repairs\n  status\u2194schedule divergence; replication and offline-assets downgrade fail loud at the\n  broker floor gate.\n\n### 13.9 Authority boundary\n\nThe credential is the coarse boundary; every subject in \xA713.2 is default-deny. Every\n**statically expressible** authorization dimension is broker-enforced through the subject\ngrammar: caller identity + lifecycle, endpoint,\ncommand, the target components each mode pins statically (\xA713.2: the full triple for `self`,\nthe caller's own, and for `handle`, redemption-pinned; the owner for\n`owner`/`any`/`child`/`ledger`), serve identity, reply\n**attribution**, and plane writer ownership.\nReply **addressing** is the one deliberate exception: it is capability-by-secret (the\nper-request nonce, \xA713.2), not a broker grant, and it is sound precisely because serve\ncredentials cannot plain-subscribe the class rail (queue-qualified grants, \xA713.2), so nonces\nare visible only to the instance the queue selected (plus every instance on a scatter, which\nis scatter's definition). Target enforcement is stated per mode, never as a blanket claim:\n`self` is broker-confined end to end including the lifecycle UID; `handle` is broker-confined\non the full redemption-pinned target triple, with the validator re-checking only mapping\ncurrency; `owner`/`any` are broker-confined on the target owner and validator-primary on the\nactor and UID currency; `child`/`ledger` are validator-primary within their distinct broker\nrails. The **named dynamic relations** (static-mesh\nown-child, fresh-ledger escalation, target-mapping currency, authorization epochs after\nacceptance) are trusted-validator-primary by design, fail-closed, and operate only within\nthe broker ceiling. Handlers only narrow. **The process epoch fences only the five planes\nwhose subjects carry it** (reply, `epe`, `ept`, `eps`, `epr`). Request-ingress subjects and durable record\nkeys cannot carry it; the caller cannot know it, and a restart-stable key must not change,\nso those two classes are fenced by the mechanism each admits: records by mediation (writer\ntable below), ingress by credential revocation with verified eviction (\xA713.1), never by\nsubject.\n\n**Caller grants.** Minting maps each named capability to exact endpoint+command subjects:\npublish on the request forms (class + instance) with the authz-mode/target pattern the\ncapability specifies, subscribe on the caller's own reply rail, publish on matching `epj`\nsubmission subjects for journaled commands, and the exact record-key / event-topic subtrees\nfor attribute/event read capabilities (per-goal containment rides the caller triple in the\ntopic). The caller's lifecycle UID token is pinned in every granted subject, so a credential\nis dead against its principal's next lifecycle by construction. Wildcards are bounded: `*` in\nthe command position only when the capability covers every command of the endpoint; `*` in\nthe endpoint position never, outside operator/admin profiles; `child`/`ledger` mode subjects\nare never covered by an `owner`-mode wildcard. `describe` is granted by default for all\nendpoints; a space MAY narrow it. Because the subject shape is verb-invariant (\xA713.2), one\npublish row covers call and cast of a command. Minted credentials MUST stay within the\ndeployment's JWT size envelope, and the envelope is validated against a **normative\nmaximum-capability fixture**, not an adjective: the reference fixture is an agent holding\nevery baseline grant plus capabilities on 3 endpoints x 12 commands each, each targeted\ncommand in both `self` and `owner` modes, plus journaled submissions and per-goal read\nscopes for all of them. Minting MUST fail loud before emitting a credential that exceeds the\npolicy gate (reference: 16 KiB); the transport bound is the CONNECT control line\n(`max_control_line`, \xA713.12) and the policy gate MUST be the tighter of the two. The mint\nMUST also refuse, before any issuance record is written, a user JWT whose byte size exceeds the\ncontrol line minus the CONNECT envelope (`MAX_MINTED_JWT_BYTES`), so a composition of individually\nvalid grants can never produce a credential the broker drops silently. The fixture\nset additionally includes a **maximum-command serve credential** (a 12-command endpoint's\nper-command rows, below); the \xA713.12 operator assertion uses the largest encoded CONNECT\nline in the set.\n\nThe agent baseline includes the self-targeted manager command `run-answer`. Its grant is only the\n`self` request form. The manager MUST authorize a baseline managed seat only when an open `ask` or\nescalated checkpoint is named by a pending relay addressed to that exact caller incarnation, and\nMUST refuse every other run or pause. A caller holding the explicit `run` capability may use the\nsame self-targeted form for ordinary run answers. The request never carries the answerer's name.\nThe amend form of `run-answer` (\xA714.5) addresses a settled pause instead, and the manager MUST\nauthorize it for a baseline managed seat only when the accepted answer it supersedes was recorded\nunder that seat's own name.\n\n**Serve grants.** Serving is granted authority, dual to calling. On the **subscribe side**\nan instance's credential binds its registered service name, stable instance id, and\n**registered command set**, one queue-qualified subscribe row per registered command\n(matrix below), never a bare `>` tail spanning commands the instance did not register. The\nper-command enumeration is affordable precisely where the caller-side equivalent is not:\nserve credentials are one per instance, a handful per space, with no capability-count\nscaling pressure. The subscribe side deliberately does NOT bind the epoch; a caller cannot\nname the serving epoch, so no request subject carries it and **ingress cannot be\nepoch-fenced by subject**; the fence for a superseded subscriber is the \xA713.1 takeover\nbarrier (revoke + cluster-verified eviction), not a grant shape. On the **publish side** the\ncredential binds the epoch everywhere it is real: the epoch-pinned reply prefix, the\nepoch-pinned `epe` event plane, its `ept` timer schedule requests, and its `epr`\nrecord-write ingress. Session subjects are\ndeliberately absent from the standing serve grant: both sides of a session hold only\nredemption-minted per-session credentials (\xA713.6); no standing EPS grant exists on either\nside. The credential also carries the record keys the writer table assigns it and, where\nthe endpoint owns a work pool, the pool's consumer + ack grants (\xA713.5; matrix below).\nNothing else. Every \"binds X\" in this paragraph has a matrix row below that actually binds\nX. Serve\ncredentials are re-minted on takeover (new epoch, \xA713.1 barrier); a superseded credential's\nreplies and commits are rejectable by epoch. Core names require operator provisioning\nauthority; reverse-DNS names bind to their registered owner. The registry is discovery; the\nserve grant is the authority: a foreign credential cannot subscribe a class rail, answer as\nan instance, or enter a frozen scatter set.\n\n**Remote manager-service grant.** The server-authored `manager-service` view is an\ninstance-scoped authority family, not a reusable host profile. Its generated grant is the exact\nunion of the one manager instance's serve rows, its one service registration/status mediator,\nits staged contract-publication row, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>`; no wildcard may span an instance, manager actor,\nowner, endpoint, record kind, contract digest, or credential id. The trusted auth path alone owns\ngate/ledger writes and all host signing. The manager service's descendant-provision request is\nmediated by that host path and MUST re-derive the requested agent's owner from the authenticated\ncaller, require it to equal the manager-service owner, and fresh-validate the active grant before\nminting any child material. It is never a raw provisioner, stream, KV, consumer, signer, or\ncross-owner control grant. The registration and renewal operations are typed/idempotent as \xA713.6\nrequires, and their stage records remain inaccessible to every ordinary agent, observer, admin,\nor managed-agent exchange.\n\n**Platform control grant.** The `platform-control` view's generated grant is the remote\nmanager-service grant above with the platform owner token as owner: the union of the one assigned\ninstance's serve rows, its one service registration/status mediator, its staged\ncontract-publication row, `epgate.manager.<instanceId>`, and\n`epcred.manager.<instanceId>.<credentialId>`, with no wildcard spanning an instance, manager actor,\nowner, account, endpoint, record kind, contract digest, or credential id. Descendant provisioning\nMUST re-derive the requested agent's owner from the authenticated caller and require it to equal\nthe platform owner token. Serve-time admin authorization answers `authorized: true` only for a\ncaller whose owner equals that token; a human `admin` scope never authorizes against it. It is\nnever a raw provisioner, stream, KV, consumer, signer, launch, or cross-owner control grant.\n\n**Platform readiness read.** A platform composition learns whether its assigned control manager\ninstance is serving through the auth context's readiness read. The trusted auth process answers over\nits own self-minted reader connection and hands out neither that connection nor its credential. The\nreader's grant is the `describe` and `status` request rows on `ep.inst.manager.<instanceId>` for the\none assigned instance under the reader's own caller triple, the subject-scoped contract-store Direct\nGet, its own reply rail, and its own `_INBOX_<connId>.>`. It holds no other command, instance, class\nor scatter route, no other store read, no KV write, and no signer. The read observes the current\nassignment on every call, refuses any other instance, and refuses an instance whose gate names\nanother principal. The reader renews as the other self-minted authority connections do: a\nshort-lived user JWT re-minted in process at half-life and presented on reconnect.\n\n**The ownership matrix (normative).** Every profile \xD7 resource \xD7 transition is classified\n**mediated** or **direct**, in an independently reviewed matrix from which grants are\ngenerated (never the reverse). Each row names the writer PROFILE, the exact subject/API\nnamespace (including the queue qualifier where one applies; the grant grammar has a queue\ndimension, \xA713.2), the operation, and the enforcement class; **read, consume, ack, and\ndelete authority are rows in the same table**, never prose that \"follows\" it. Every\ncredential and every audit probe is generated from these rows.\n\n**Consumer-name grammar (normative).** Every consumer a row names has a pinned name grammar\n(dash-form, \xA72; `<e>` is the endpoint-name token, `<uid>` the holder's lifecycleUid or\ninstanceId): `canonD = canon_<e>` (the canonicalizer durable), `poolD = pool_<e>_<pool>`\n(the pool durable, **pre-created by the provisioner** with exact filter\n`cotal.<space>.epw.<e>.<pool>.>`, the \xA78 item-3 pattern: the bare create form is\nbody-filter-selectable and is granted to NO ONE on control-surface streams), `timerD =\ntimerw_<space>` (the timer writer durable), `recwD-k = recw_<space>-<kind>` (one record\nwriter durable PER RECORD KIND, \xA713.9), `effD = eff_<e>` (the endpoint's ONE shared\neffects durable; below), `goalD = goal_<uid>-<e>` (the caller's own goal-result durable).\nEvery composite name is **collision-free by construction**, and\neach derivation states why: `pool_<e>_<pool>` parses uniquely from its LAST `_` because a\npool token contains no `_` (`[a-z0-9-]`) while `<e>` may (a dash separator would be\nambiguous, both tokens admit `-`); `dec_<uid>-<e>` parses from its FIRST `-` because\n`<uid>` is `[a-z0-9]` and contains none, and `goal_<uid>-<e>` likewise; `eve_<uid>-<e>-<gid>-<n>`\ncarries TWO `-`-adjacent soft components (`<e>` and `<gid>`), so `<gid>` is constrained\nSEPARATOR-FREE (`[a-z0-9]`, no `-` or `_`): then `<uid>` (leading, `-`-free), `<n>` (trailing\ndigits) and `<gid>` (separator-free) are each a single token off their edges, leaving `<e>` as\nthe only `-`-bearing component with an unambiguous extent (`eve_<uid>-a-b-c-0` can ONLY be\nendpoint `a-b`/gid `c`, never endpoint `a`/gid `b-c`). `rec_<uid>-<gid>-<n>` has one soft\ncomponent `<gid>` bounded by `-`-free `<uid>` and digit `<n>`. Without the separator-free `<gid>`\nthe two grants above would collide on one durable name. A derivation that cannot state its\ncollision-freedom argument is non-conformant. Reader consumers use **mint-time-enumerated LITERAL names**, and every one\nis **pre-created by the provisioner at capability mint as a PULL durable with its exact\nfilter; the holder receives BIND-ONLY grants** (INFO/MSG.NEXT/ACK, never CREATE or\nDELETE): `decD = dec_<uid>-<e>` (one per journal capability), `goalD = goal_<uid>-<e>`\n(one per action capability),\n`eveD = eve_<uid>-<e>-<gid>-<n>` and `recD = rec_<uid>-<gid>-<n>` (one per granted subtree;\n`<gid>` is the **grant id**, a short stable SEPARATOR-FREE (`[a-z0-9]`) id the provisioner\nassigns per minted capability grant, so two independent capability mints for one lifecycle UID\nnever collide AND the `<e>`/`<gid>` boundary stays unambiguous, and `<n>` is\nthe subtree's zero-based index within THAT grant, sorted lexicographically at mint; the\ndeprovision key is `<uid>-<gid>`, so revoking one capability deletes exactly its own reader\ndurables and cannot reach a sibling capability's). Two reasons, both\nload-bearing. A NATS wildcard replaces a\nWHOLE dot-separated token and never matches inside one, so an embedded `*` in a name token\n(e.g. `dec_<uid>-*`) is a literal character, not a glob; every name token in a grant is\nfully literal.\n\n**Mediated reads (normative).** No untrusted capability holder is granted **any** raw\nJetStream read of a control-surface stream, not a consumer create, not a bind-only pull,\nnot a `DIRECT.GET`. Every JetStream read is request/reply where the server delivers stored\nbytes to a **caller-chosen destination the broker does not confine to the caller's\n`pub.allow`**: a push consumer's `deliver_subject`, a pull `MSG.NEXT` request's reply\nsubject, and a `DIRECT.GET` request's reply subject are all set in the request body, and the\nserver's internal client publishes there regardless of the requester's publish permissions.\nA holder with only `MSG.NEXT` or\n`DIRECT.GET` on its own filtered reader can therefore route stored bytes onto a victim's DM,\nreply, or record subject, a confused deputy no filter tail, literal name, or pull-vs-push\nchoice prevents, because the destination is the vulnerable field, not the filter. Untrusted\ncallers instead read exactly as the \xA78 durable backstop already does, through a **trusted\nread path**, never a self-bound consumer: a caller receives its decisions, goal results,\nevent catch-up, and record reads over its OWN confined rails, a live core subscription to a\nsubject inside its `sub.allow` (bytes land only on the caller's own subscription), or a\nmediator that owns the reader consumer, re-authorizes each read against the caller's current\ngrants, and returns bytes over the caller's own attribution-pinned reply rail\n(`ep.reply.\u2026<caller triple>.<nonce>`: the mediator holds the publish grant, the caller the\nread grant, and the nonce confines addressing, \xA713.2). The mediator IS a trusted\nsingle-purpose principal (the delivery/read daemon, \xA78/Appendix B) that delivers only to the\nre-authorized caller and never proxies to an arbitrary subject; raw\nconsumer/`DIRECT.GET`/`STREAM.MSG.GET`\nauthority stays with trusted single-purpose infra principals (canonicalizer, commit\nprincipal, record writer, timer writer, the read mediator, the auth path) that deliver to\nthemselves. A registered endpoint MAY also mediate its own callers' goal-result reads through\nits separate trusted commit/read connection. Each request MUST be authorized by the requesting\nconnection's broker-enforced command grant on its authenticated caller triple. User-auth revocation\nhas the same bearer-lifetime bound as other live endpoint commands; renewal requires a fresh\nexchange and connect that re-authorize the caller. This read does not claim a per-request ledger\ncheck. The endpoint and full caller triple MUST come from the broker-authenticated request\nsubject; caller input supplies only the goal id. The response MUST\nuse the derived attribution-pinned caller reply rail, never a caller-supplied destination. This\nhosting choice grants no raw read to the endpoint's serve credential or to its callers. The\nexisting trusted reader's body-selected, space-wide leader-read residual MUST remain documented.\nThis contract fixes the boundary; untrusted callers never hold raw reads; reads are mediated onto\nconfined caller rails, and leaves the read-command wire shape (batching, cursors, flow control) to\nthe reference implementation.\n**Subject convention:**\napplication subjects in rows are written relative and are prefixed `cotal.<space>.` on the\nwire; **JetStream API tails (extended-create filter tails and `DIRECT.GET` subject\ntails) are always spelled in FULL** (`cotal.<space>.\u2026`/`$KV.\u2026`/`$O.\u2026`), because the API\nsubject embeds the stored subject verbatim and a relative tail matches nothing (the\nstreams capture `cotal.<space>.ep*.>`, \xA713.12).\nThe grep tests the matrix MUST pass: the only `CONSUMER.CREATE` grants below belong to\ntrusted provisioning/infra profiles and each carries a full literal filter tail; every\nconsumer-name token in a grant is a LITERAL (no embedded `*`); every filter or Direct-Get\ntail is fully qualified; **no UNTRUSTED profile (agent/observer/admin) holds any\n`CONSUMER.CREATE`/`MSG.NEXT`/`DIRECT.GET`/`STREAM.MSG.GET` on a control-surface resource** (an\naudit MUST run this over Appendix B too, not only this matrix; the profile tables are\ngenerated from these rows, so a generated grant that contradicts the matrix fails the build);\nand the ONLY `STREAM.MSG.GET` (body-selected) grants that exist at all are the leader-served\nreads of named TRUSTED single-purpose profiles, each granted to no other profile - every one\na FENCING read (read service, below) except where its row names it a CAS-PINNING read, a\nleader-served currency read whose FENCE is the pinned CAS write it feeds (\xA713.1: a read is\nnever a fence): the auth path on `KV_cotal_auth_<space>`, the lifecycle mapping-reader and\nthe provisioner-registration principal on the `cotal_records_<space>` heads, the endpoint's\ncanonicalizer on `EPF_<space>`/`EPW_<space>`, the endpoint's commit principal on its own\n`EPF_<space>` fact families AND on `KV_cotal_records_<space>` (its goal/checkpoint FENCING\nspec-and-currency reads: the terminal-commit's spec read and the epoch/deadline reads the\nread-service clause names), each record kind's spec/status writer principal on\n`KV_cotal_records_<space>` (its fresh lifecycle-mapping `processEpoch` currency read, the\nwriter-table stale-writer fence; per \xA713.1 a mapping yields a current epoch ONLY at\n`state: \"active\"`, and `retiring`/`retired` alike refuse the write), and the space's timer writer on\n`KV_cotal_records_<space>` (its fresh generation/deadline check before arming, a FENCING\nread) and on `EPT_<space>` (`$JS.API.STREAM.MSG.GET.EPT_<space>`, the armed-subject's own\nlast-by-subject sequence read: CAS-PINNING, the leader-served input to the arm's\n`Nats-Expected-Last-Subject-Sequence` publish, whose broker CAS - not the read - is the\nfence, the same \xA713.1 complementarity class as the FIRE handler's status CAS). The timer\nFIRE handler holds no records `STREAM.MSG.GET`: its settlement is a revision-pinned status\nCAS, so a stale read loses the CAS loudly (\xA713.1 complementarity), never mis-fires (the\nmatrix rows below). The body-selected form is not\nsubject-confinable by the broker, so each of these grants trades broker confinement for\nprofile trust; the trade is acceptable exactly because every holder IS a trusted\nsingle-purpose principal for whom read-your-writes is a correctness requirement, not a\nhazard (on the `allow_direct=false` buckets a leader-consistent get is precisely a\n`STREAM.MSG.GET`). Every OTHER subject-scoped read is NON-fencing and uses the\nlast-by-subject `DIRECT.GET.<stream>.<subject>` form, which the broker confines by subject\ntokens. (The pre-v0.4 messaging-surface CHKV/DLVKV reads in Appendix B are the v0.3 binding,\noutside this matrix; their confused-deputy exposure is the \xA79 in-scope-for-v0.4 remediation.)\n\n**Read service (fencing reads are leader-served).** A read is FENCING when its result, a\nvalue, a revision, OR an authoritative ABSENCE, gates a subsequent CAS or authorizes an\neffect; fencing is defined by USE, never by subject family. A CAS loser reading the winner,\na terminal-commit's spec read, and the work-pool re-enqueue predicate (accepted, with the\nauthoritative absence of BOTH a committed terminal and a live `EPW` entry, \xA713.6) are all\nfencing: a stale follower read that misses a committed terminal while the `EPW` entry is\nlegitimately absent re-arms settled work. A fencing read MUST be leader-served, meaning one\nof `STREAM.MSG.GET`, a get against a bucket with `allow_direct=false`, or delivery\nserialized by the authoritative primary stream/consumer (an authoritative `MSG.NEXT`, e.g.\nthe accepted-fact effects row and the auth path's snapshot enumeration below), and it MUST\nbe served against the AUTHORITATIVE stream or bucket for its key, never a mirror, a sourced\nstream, or a cross-space replica (\"leader-served\" means that authoritative primary; a\nmirror's own leader can lag its source). `allow_direct=true` and Direct Get exist for\nNON-fencing, subject-confined reads only; a client MUST NOT let a fencing read silently\nride Direct Get because the bucket allows it. This does not weaken \xA713.1's rule that a read\nis never a fence: the fence itself stays a CAS or create-only write; leader service is what\nkeeps the read's result from silently falsifying the CAS or effect it feeds.\n\n| Transition | Writer profile | Exact namespace (per space/endpoint) | Class |\n| --- | --- | --- | --- |\n| Request publish | capability holder (agent, per capability) | per \xA713.2 form: `ep.{one,all}.<endpoint>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>.*` and `ep.inst.<endpoint>.<instanceId>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>.*`, mode/target tokens literal per the minted capability (`handle`: the full redemption-pinned triple) | direct, untrusted input, broker-confined |\n| Reply subscribe (caller) | capability holder | `ep.reply.*.*.*.<cO>.<cA>.<cUid>.*` (exact arity) | direct read; own rail only |\n| Serve subscribe | the endpoint's serve credential | per registered command: `\"ep.one.<endpoint>.<command>.> <endpoint>\"` (queue-qualified ONLY), `ep.all.<endpoint>.<command>.>` plain, `ep.inst.<endpoint>.<instanceId>.<command>.>` exact (never a cross-command `>` | direct) name/instance/command-pinned; epoch deliberately absent (\xA713.1 barrier is the fence) |\n| Reply publish | the endpoint's serve credential | `ep.reply.<endpoint>.<instanceId>.<epoch>.*.*.*.*` | direct; attribution-pinned; addressing by nonce |\n| Versioned-rail request, reply, serve (\xA713.15) | as the four rows above | the same rows with `ep.v1` for `ep` and one more pinned token: the caller's `<generation>` literal in its request-publish and reply-subscribe rows (`ep.v1.reply.*.*.*.<cO>.<cA>.<cUid>.<generation>.*`), a spanned token in the serve credential's reply-publish row (`ep.v1.reply.<endpoint>.<instanceId>.<epoch>.*.*.*.*.*`) and its three serve-subscribe shapes per command | direct; broker-confined on the generation exactly as on the caller triple |\n| Issuance (\xA713.15) | the `issuer` principal (one-shot, minted per issuance or per lifecycle terminal by the party holding the space signer) | `$KV.cotal_issued_<space>.>` and `$KV.cotal_accepted_<space>.>` publish, `STREAM.INFO`/`STREAM.MSG.GET` on `KV_cotal_issued_<space>`, its own ordered consumers on that store, and ONE leader-served `STREAM.MSG.GET` on `KV_cotal_auth_<space>` for source liveness; NO auth-store write, no rail row | mediated; create-only CAS on evidence, revision-CAS on the attempt row |\n| Run admission (\xA714.8) | the `run-admitter` principal (one-shot, 60 s, minted per run by the hosting endpoint or the local operator) | exactly `$KV.cotal_admission_<space>.admission.v1.<endpoint>.<runId>` and `\u2026.revoked.v1.<endpoint>.<runId>` publish plus `STREAM.MSG.GET` on that store; nothing else | mediated; create-only |\n| Run admission read (\xA714.8) | the `run-mediator` and `run-operator` principals | `STREAM.MSG.GET` on `KV_cotal_admission_<space>` (leader-served; body-selected, stream-wide, the same residual as every records reader); the `run-driver` holds NO row on this store | mediated read; fail-closed |\n| Journal submission append | capability holder | `epj.<endpoint>.<command>[.<mode>[.<target tokens per mode>]].<cO>.<cA>.<cUid>` | direct, explicitly untrusted input |\n| Canonicalizer consume | the endpoint's canonicalizer principal (singleton, \xA713.4) | its durable on `EPJ_<space>`: `$JS.API.CONSUMER.CREATE.EPJ_<space>.<canonD>.cotal.<space>.epj.<endpoint>.>` (full-tail single filter), `$JS.API.CONSUMER.INFO.EPJ_<space>.<canonD>`, `$JS.API.CONSUMER.MSG.NEXT.EPJ_<space>.<canonD>`, plus `$JS.ACK.EPJ_<space>.<canonD>.>` (ack/term after durable decision only, and, for pool-admitted acceptances, after the enqueue, \xA713.4) | mediated |\n| Canonical decisions + quarantine + goal-bind | the endpoint's canonicalizer principal | publish `epf.<endpoint>.dec.>`, `epf.<endpoint>.quar.>`, and `epf.<endpoint>.goal.*.*.*.*.bind` (the per-goal first-wins bind, \xA713.4, create-only CAS per subject; the `.bind` leaf is disjoint from the commit principal's `goal\u2026.result`/status writes, so no writer overlap) | mediated |\n| Canonicalizer CAS-winner + terminal read | the endpoint's canonicalizer principal | leader-served `$JS.API.STREAM.MSG.GET.EPF_<space>` (body-selected `last_by_subj`; these reads are FENCING, read service above, so the follower-served `$JS.API.DIRECT.GET.EPF_<space>.\u2026` form is NOT granted; the body-selected form is the broker-confinement-for-profile-trust trade above) over exactly its families: `epf.<endpoint>.dec.>` + `epf.<endpoint>.quar.>` (observes the winning fact on redelivery, \xA713.4) + `epf.<endpoint>.wrk.>` (READ-ONLY: the reconciliation predicate's terminal probe, \xA713.6; `wrk` writes stay with the commit principal, row below) + `epf.<endpoint>.goal.*.*.*.*.bind` (the goal-bind CAS winner: on a lost `.bind` create the canonicalizer reads the existing bind to decide same-fingerprint retry vs. `conflict`, \xA713.4) | mediated |\n| Caller durable reads (decisions, goal results, receipts, event catch-up, record reads/watches) | the **read mediator** owns the reader consumers; a registered endpoint MAY mediate its own callers' goal results through its separate trusted commit/read connection; the **caller** holds only its own reply rail | **Mediated (normative above).** The caller holds NO consumer/`DIRECT.GET` grant on EPF/EPE/EPC/records. It issues a read command and receives its own caller-scoped facts (`dec`/`goal\u2026result`/`receipt` under its triple, \xA713.2), event catch-up, and record snapshots over its attribution-pinned reply rail `ep.reply.\u2026<cO>.<cA>.<cUid>.<nonce>`; the read mediator re-authorizes each read against the caller's current grants before delivering; registered-endpoint goal reads use the connection-grant authorization and bearer-lifetime bounds specified above. Live progress is the caller's own core subscription to granted `epe` subtrees within `sub.allow` (bytes land only on its own sub). Reader consumers (`decD`/`goalD`/`eveD`/`recD`) are owned and bound by the mediator, never the caller | mediated read; confined to the caller's own rails |\n| Accepted-fact consume (effects) | every instance's serve credential, on the endpoint's ONE shared durable | **bind-only** on the provisioner-pre-created pull durable `effD = eff_<e>` (exact filter `cotal.<space>.epf.<endpoint>.dec.>`, `AckExplicit`): `$JS.API.CONSUMER.INFO.EPF_<space>.<effD>`, `$JS.API.CONSUMER.MSG.NEXT.EPF_<space>.<effD>`, `$JS.ACK.EPF_<space>.<effD>.>`; instances **pull-compete on the shared durable** so each accepted decision is delivered to exactly one live instance (at-least-once): a per-instance consumer over the class-wide decision subtree would be broadcast, and every instance would duplicate the external effect. Effects consume canonical facts, never raw submissions (\xA713.4); a rejected/quarantined decision is ack-skipped, and so is any acceptance whose `route` is a pool (\xA713.4, the pool's worker path executes it; effects MUST NOT). **Ack barrier:** an effecting instance MUST ack a `dec` message ONLY after its effect is durably recorded, for an action command the terminal `goal\u2026.result` fact; for a **non-action `route:\"effects\"` journal command** a generic per-request **effect fact** `epf.<endpoint>.eff.<cO>.<cA>.<cUid>.<id>` (create-only CAS, written by the effecting instance's commit path before ack; every `route:\"effects\"` acceptance has exactly this durable effect-complete marker), never before; an ack-before-effect would let a crash drop journal work the at-least-once contract promised. A crash before the ack redelivers the decision to another competing instance, which observes the existing terminal fact (idempotent) or effects it | direct read, endpoint-scoped, work-shared |\n| Result/receipt/terminal/resume facts | the endpoint's commit principal | enumerated fact families, no subtraction and **never `dec.>`/`quar.>`** (canonicalizer-only): publish `epf.<endpoint>.goal.*.*.*.*.result` (the goal terminal result; the `.bind` leaf under `goal.>` is the canonicalizer's, row above), `epf.<endpoint>.eff.>` (per-request effect-complete fact for non-action `route:\"effects\"` commands, create-only CAS, \xA713.9 ack barrier), `epf.<endpoint>.receipt.>` (caller-scoped subjects, \xA713.2), `epf.<endpoint>.wrk.>` (per-item terminal, create-only CAS), `epf.<endpoint>.cp.>` (one-use resume CAS); read-back is FENCING (read service above: it gates create-only CAS emission and idempotent re-commit decisions), leader-served `$JS.API.STREAM.MSG.GET.EPF_<space>` (body-selected `last_by_subj` over exactly these five families; the follower-served per-family `DIRECT.GET` form is NOT granted) | mediated |\n| Live event progress (caller) | capability holder (per read capability) | a caller-owned **core subscription** to the granted `epe` subtrees (fully-qualified `cotal.<space>.epe.\u2026` in `sub.allow`, Appendix B), incl. per-goal `epe.<endpoint>.*.*.goal.<cO>.<cA>.<cUid>.>`; safe because a core sub delivers only to the caller's own subscription, never a caller-chosen subject; durable catch-up/replay is the mediated read above, not a self-bound consumer | direct read; own subscription only |\n| Claim / action / checkpoint commits | the owning endpoint's commit path | its own record keys (`goal`/`cp`/`lease`/`goaleff`/`epname`/`epmig` grammars, \xA713.7, per the writer table; the three coordination kinds are enumerated HERE because a shared registry profile does not confer a grant; a kind absent from this enumeration is default-denied however it is registered, and that default-deny binds every principal in this table, including the composed profile in the row below) + the enumerated commit fact families of the Result row above, never `dec.>`/`quar.>`; its goal/checkpoint FENCING reads (the terminal-commit's spec read, epoch/deadline currency) are leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` (read service above; the records bucket's Direct Get is NON-fencing only) | mediated (validates fencing, lease clock, lifecycle, epoch) |\n| Goal-writer commits (journal-class actions) | the **goal-writer** principal: the commit principal of the row above, composed with three additions and nothing else | the composed profile is exactly (i) everything the commit row grants, inherited rather than restated, (ii) the per-goal first-wins bind leaf `epf.<endpoint>.goal.*.*.*.*.bind`, (iii) the reconcile index subtree `goalidx.<endpoint>.>` in the records bucket, key-pinned to this endpoint, and (iv) a currency read of its OWN issuance gate `epgate.<endpoint>.<instanceId>` before the first terminal-fact CAS, so a superseded writer declines to commit. That read carries the NAMED RESIDUAL this section requires of every bucket-blind read: the auth store is not Direct-Get enabled, so the read is a leader-served body-selected `STREAM.MSG.GET` that cannot be key-pinned to the single gate key, and the profile can therefore read any row of that bucket's gate and ledger METADATA, never bearer bytes. It is the same residual class the one-shot serve-executor profile carries, here on a standing connection, and it is a fast-fail belt rather than the fence; the durable fence is barrier revocation. `goalidx` is enumerated HERE and NOT on the commit row, because the index is written create-only BEFORE the goal binds, so the principal that writes it is the one that also binds; granting it on the bare commit row would widen every commit principal to a key only this profile needs. This profile holds NO records consumer create: the sweep that enumerates the index runs over the provisioner (row below), never over this standing connection, which is why an index write grant is not an index enumeration grant | mediated (as the commit row, plus the bind's create-only CAS per subject) |\n| Contract-artifact publication | the contract publisher principal | publish `epc.<digest-hex>` (`epc.*`), create-only per subject (`Nats-Expected-Last-Subject-Sequence: 0`; a digest subject is written at most once); read-back via the reader row below | mediated, immutable once published |\n| Contract-artifact read | trusted infra directly (`DIRECT.GET.EPC_<space>.cotal.<space>.epc.>`); untrusted callers via the read mediator | contract artifacts are content-addressed and public (verify-on-read is the tamper boundary, \xA713.7), so exposure is not the risk; the confused-deputy INJECTION is, so an untrusted caller's artifact fetch is mediated onto its own reply rail exactly like any other read; trusted infra fetches directly | mediated for callers / direct for infra |\n| Record write ingress (`epr`) | the owning instance | publish `epr.<endpoint>.<instanceId>.<epoch>.<kind>.<qualifier...>`; the instance's ONLY path to `svc`/`goal`/`cp` status writes; the epoch token is pinned by the serve credential, so the record writer reads the writing epoch from the broker-authenticated subject, never from payload | direct; epoch-pinned ingress to the mediated writer |\n| Record writer consume + `spec`/`status` writes | the kind's separately scoped spec/status writer principal (writer table); **one principal and one consumer PER KIND**, never a single writer draining every kind | consume: `$JS.API.CONSUMER.CREATE.EPR_<space>.<recwD-k>.cotal.<space>.epr.*.*.*.<kind>.>` (full-tail single filter on the `<kind>` token of \xA713.2's `epr` grammar; `recwD-k = recw_<space>-<kind>`) + `$JS.API.CONSUMER.INFO.EPR_<space>.<recwD-k>` + `$JS.API.CONSUMER.MSG.NEXT.EPR_<space>.<recwD-k>` + `$JS.ACK.EPR_<space>.<recwD-k>.>`; write: `$KV.cotal_records_<space>.<that kind's \xA713.7 key grammar>.{spec,status}`; its writer-table stale-writer fence (the FRESH lifecycle-mapping `processEpoch` currency read; current ONLY at `state: \"active\"`, \xA713.1, so a `retiring` or `retired` mapping refuses the write) is leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` (a FENCING read, read service above); the kind token in the ingress subject is what keeps the writer separation the writer table declares | mediated per kind below, no row left open |\n| Reader/pool/effects consumer provisioning (one-shot, at capability mint / endpoint setup) | the provisioner | exact full-tail extended creates for every pre-created durable this matrix names: `$JS.API.CONSUMER.CREATE.EPW_<space>.<poolD>.cotal.<space>.epw.<e>.<pool>.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<effD>.cotal.<space>.epf.<e>.dec.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<decD>.cotal.<space>.epf.<e>.dec.<cO>.<cA>.<cUid>.>`, `$JS.API.CONSUMER.CREATE.EPF_<space>.<goalD>.cotal.<space>.epf.<e>.goal.<cO>.<cA>.<cUid>.>` (per action capability), `$JS.API.CONSUMER.CREATE.EPE_<space>.<eveD-n>.<granted full-tail subtree>`, `$JS.API.CONSUMER.CREATE.KV_cotal_records_<space>.<recD-n>.$KV.cotal_records_<space>.<granted subtree>` (the reader-config seam is an ALLOWLIST: the `<granted subtree>` kind token MUST be a registered caller-readable record kind, so it REFUSES every authority-control kind (`oblig` above all, plus `govern`/`policy`/`uid`/`frontier`) and every unregistered kind, and for a dual-token kind whose atomic head is authority (`lifecycle`, head `lifecycle.<owner>.<actor>`) it admits only a filter strictly deeper than the head, never one that can match the head key itself; so no reader durable is ever pre-created over the `oblig.` subtree the sealed records scanner owns nor over an authority head, nats-server#8274), every create PULL, every filter a full literal tail; plus matching `CONSUMER.DELETE` for deprovisioning (lifecycle-keyed names, \xA713.1) | mediated, trusted provisioning only |\n| Events | the owning instance | `epe.<endpoint>.<instanceId>.<epoch>.>` | direct; subject-confined, epoch-pinned |\n| Timer schedule request | the owning instance | publish `ept.<endpoint>.<instanceId>.<epoch>.*.schedule` (never `.armed`/`.fire`); a request carrying any scheduling header is rejected by the timer writer (\xA713.2) | direct; epoch-pinned; captured by the schedules-DISABLED request stream |\n| Timer request consume + arm | the space's timer writer principal (singleton infra, like the delivery daemon) | consume: `$JS.API.CONSUMER.CREATE.EPT_REQ_<space>.<timerD>.cotal.<space>.ept.*.*.*.*.schedule` (full-tail single filter) + `$JS.API.CONSUMER.INFO.EPT_REQ_<space>.<timerD>` + `$JS.API.CONSUMER.MSG.NEXT.EPT_REQ_<space>.<timerD>` + `$JS.ACK.EPT_REQ_<space>.<timerD>.>`; arm: publish `ept.*.*.*.*.armed`, deriving `Nats-Schedule-Target` = the sibling `.fire` from the authenticated request subject tokens ONLY, stripping/rejecting every client scheduling header, and **fresh-checking the authoritative timer generation/deadline before arming** (a FENCING read: leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` on the checkpoint record, read service above); the arm also reads the armed-subject's own last sequence via `$JS.API.STREAM.MSG.GET.EPT_<space>` and publishes with `Nats-Expected-Last-Subject-Sequence` pinned to it - that read is CAS-PINNING, not fencing: the broker CAS is the fence and a delayed writer's stale read loses it loudly (\xA713.1 complementarity, the FIRE handler's class); a redelivered or delayed stale-generation request is discarded, never armed, so it cannot overwrite the current schedule and silently lose the live deadline (\xA713.2, \xA713.6, \xA713.12) | mediated |\n| Timer fire consume | the owning instance | its own `ept.<endpoint>.<instanceId>.<epoch>.*.fire` (fired messages validated against its authoritative schedule state AND the broker-authored scheduler-origin header = its exact sibling `.armed`, \xA713.12); no client credential holds `.armed` or `.fire` publish | direct read |\n| Session `.in` publish | the session's caller (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.in` exact | direct |\n| Session `.in` subscribe | the serving instance (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.in` exact | direct read |\n| Session `.out` publish | the serving instance (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.out` exact | direct |\n| Session `.out` subscribe | the session's caller (per-session credential) | `eps.<endpoint>.<sessionId>.<epoch>.out` exact | direct read |\n| Session ledger (one-use redemption, credential ids, revocation state, authenticated close) | the trusted auth path (\xA79/\xA710) | `$KV.cotal_auth_<space>.session.<sessionId>`, create-only CAS per `sessionId`, monotonic state (\xA713.6) | mediated |\n| Credential ledger (issuance gate, descendant enumeration, lineage index, revocation) | the trusted auth path (\xA79/\xA710) | writes: `$KV.cotal_auth_<space>.cred.<lifecycleUid>.<credentialId>` + `\u2026.gate.<lifecycleUid>` (the issuance gate, revision-pinned CAS is the mint fence, \xA713.1) + `\u2026.epgate.<endpoint>.<instanceId>` + `\u2026.epcred.<endpoint>.<instanceId>.<credentialId>` + the exact `\u2026.eprepair.<endpoint>.<instanceId>` interrupted-repair cursor (the disjoint endpoint families, \xA713.1: same protocol, explicit prefixes, never arity; the repair executor is pinned to one exact cursor key) + `\u2026.stage.>` (implementation staging/tombstone fences; NEVER under `cred.`/`epcred.`, \xA713.1) + `\u2026.srcgate.<issuerKeyId>.<id>` (per-handle source gate, \xA713.1) + `\u2026.bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>` (the per-ancestor lineage index) + `\u2026.session.<sessionId>` (create-CAS `issuing`, finalize-CAS `active`, \xA713.6) + `\u2026.plane` (the ONE plane-ownership claim row, \xA713.13: create/revision-CAS by the barrier profile only, exact arity, never `plane.>`); reads: **leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_auth_<space>`** (with `allow_direct=false` a KV get is exactly this body-selected `last_by_subj` call against the stream LEADER; read-your-writes, not a follower-served `DIRECT.GET`; the body-selection is safe here because this profile IS the trusted auth path, and it is granted to no other profile) for gate/session/row state, which is why the mint and session fences are revision-pinned CAS *writes* rather than reads (a read is never a fence, \xA713.1); and **fence-free prefix enumeration through the SEALED auth-ledger scanner, never a runtime consumer create**: no standing or runtime-reachable auth credential (the takeover/retirement/handle-revocation barrier, the session sweep, any replayable executor) holds `$JS.API.CONSUMER.CREATE` on `cotal_auth_<space>`, because a consumer-create request BODY is not subject-ACL confinable: an extended `CONSUMER.CREATE.<stream>.<name>.<filter>` grant still admits a body with `durable_name` (equal to the subject name token) and a push `deliver_subject`, a DURABLE exporter of every current and future row that SURVIVES the credential's connection close and revocation; a subject ACL cannot constrain that body, so the only safe runtime grant is none. The dynamic-enumeration `CONSUMER.CREATE` lives in exactly ONE profile, a SEALED scanner the trusted auth process opens for itself and NEVER hands out: its credential, connection, and identity seed reach no caller, child, log, or persistence (a process-memory compromise reaches it, the SAME residual class as the account signing seed the process already holds; never broker confinement, never a network-reachable JWT). The scanner is pinned to ONE literal consumer name under a FORCED config: pull (no `deliver_subject`), ephemeral (no `durable_name`), `AckPolicy.None`, `DeliverPolicy.LastPerSubject`, memory storage, bounded inactivity; re-read and bind-verified before use and unconditionally deleted after, with every scan over the stream serialized on that one name, and the injected scanner bonded to its exact space so a hand-assembled or foreign-space scanner never enumerates. The scan is FENCE-FREE by construction: under the history=1 store a same-subject `active\u2192revoked` overwrite EVICTS the pre-scan revision, so a sequence/`STREAM.INFO` cutoff would DROP that subject and leave its holder un-revoked; a LastPerSubject read carries no upper cutoff and, draining to a freshly re-observed zero pending (never a stale local count), returns each subject's CURRENT last, so a concurrent overwrite is SEEN, never dropped. It enumerates exactly `cred.<lifecycleUid>.>`, `bysrc.<issuerKeyId>.<id>.>`, `stage.>` (operation-intent discovery), or `session.>`. The barrier's family enumeration and the expiry sweep are executable reads, not prose. No profile OTHER than the sealed scanner and this trusted write path holds ANY grant on `cotal_auth_<space>` | mediated |\n| Remote manager-service registration and renewal (\xA713.1/\xA713.6) | the trusted auth path is the sole gate/ledger writer and host JWT issuer; a user manager presents only the server-authored closed view | exactly one staged `{ owner, managerActor, lifecycleUid, instanceId }` family: `svc.manager.<instanceId>`, the stage-pinned contract artifacts, `epgate.manager.<instanceId>`, and `epcred.manager.<instanceId>.<credentialId>`. `prepare` freezes/stages; `activate` creates the matching service record and releases host-signed material only after ledger + gate finalization; `renew` is bounded, rechecks the live ledger scope, and can replace material only inside that family. Descendant provisioning is a mediated same-owner request revalidated by the host. No row grants signer material, generic stream/KV/consumer authority, another instance, or a public/managed-agent exchange path | mediated, closed family; revocation/renewal failure denies new authority and unsafe restarts while retaining live agents only within their independently valid lifetimes |\n| Auth-ledger enumeration (the SEALED scanner profile, the credential-ledger row's enumeration seam) | the trusted auth process's DEDICATED self-minted scanner principal; opened for the process itself, NEVER handed out (full rationale in the credential-ledger row above) | exactly `$JS.API.INFO` + `$JS.API.STREAM.INFO.KV_cotal_auth_<space>` + `$JS.API.CONSUMER.CREATE.KV_cotal_auth_<space>.cotal-ledger-scan.$KV.cotal_auth_<space>.>` + `$JS.API.CONSUMER.INFO.KV_cotal_auth_<space>.cotal-ledger-scan` + `$JS.API.CONSUMER.MSG.NEXT.KV_cotal_auth_<space>.cotal-ledger-scan` + `$JS.API.CONSUMER.DELETE.KV_cotal_auth_<space>.cotal-ledger-scan` + its connection-scoped `_INBOX_<connId>.>` subscribe, and NOTHING else (no records-stream grant, no KV write, no `DIRECT.GET`, no `$JS.ACK`: an `AckPolicy.None` scan acks nothing); `cotal-ledger-scan` is the ONE pinned literal consumer name every auth-stream scan serializes on, and this profile plus the records scanner below are the ONLY DYNAMIC-ENUMERATION `CONSUMER.CREATE` holders on the two authority streams (the provisioning row's pre-created full-tail reader durables, CREATE+DELETE by the provisioner and INFO/MSG.NEXT/ACK bind by the read mediator, are the one other records-stream consumer authority, and the reader-config seam REFUSES an authority-control record kind so no reader durable can target the `oblig.` subtree the records scanner owns), re-audited mechanically per this section's closing clause | mediated |\n| Obligation enumeration (the SEALED records scanner profile, the acceptance-obligation row's enumeration seam, ONE instance per space) | the trusted process's DEDICATED self-minted records-scanner principal; opened for the process itself, NEVER handed out (full rationale in the acceptance-obligation row below; every scan over the literal name serializes process-wide per space, so a second instance can never interleave with a live scan and hand back a partial result, and the scanner handle is immutable once branded) | exactly `$JS.API.INFO` + `$JS.API.STREAM.INFO.KV_cotal_records_<space>` + `$JS.API.CONSUMER.CREATE.KV_cotal_records_<space>.cotal-records-scan.$KV.cotal_records_<space>.oblig.>` (the CREATE filter is confined to the `oblig.` subtree) + `$JS.API.CONSUMER.INFO.KV_cotal_records_<space>.cotal-records-scan` + `$JS.API.CONSUMER.MSG.NEXT.KV_cotal_records_<space>.cotal-records-scan` + `$JS.API.CONSUMER.DELETE.KV_cotal_records_<space>.cotal-records-scan` + its connection-scoped `_INBOX_<connId>.>` subscribe, and NOTHING else; `cotal-records-scan` is the ONE pinned literal consumer name, disjoint from the auth scanner's (one scanner instance, lock, and literal name PER STREAM) | mediated |\n| Work-pool enqueue | the endpoint's canonicalizer (from accepted decisions only) | `epw.<endpoint>.>` publish, create-per-subject (`Nats-Expected-Last-Subject-Sequence: 0`; the acceptance identity is the subject, \xA713.2) | mediated |\n| Work-pool reconciliation probe | the endpoint's canonicalizer | leader-served `$JS.API.STREAM.MSG.GET.EPW_<space>` (body-selected `last_by_subj` on the exact item subject; the probe is FENCING, read service above: a follower-served `DIRECT.GET` that misses the live entry re-arms settled work, so that form is NOT granted) + the CAS-winner read row above (`dec` + `wrk` last-by-subject), together they decide the \xA713.6 predicate: accepted, **`now < workExpiry`** (an expired item is never re-enqueued; it is terminally settled `expired` with its `wrk` fact and acked without effect), no terminal, no live entry \u21D2 re-enqueue for the item's REMAINING TTL; a worker likewise MUST check `now < workExpiry` before lease/effect and refuse expired work | mediated |\n| Virtual-endpoint activation watch | the endpoint's activator principal (holder of its activation capability, \xA713.6) | exactly `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>` (the per-pool occupancy snapshot; request/reply, so watching is bounded polling) PLUS its own connection-scoped reply inbox `_INBOX_<connId>.>` (never the account-wide default); the instance START is a mediated, target-bound seam resolved by the supervisor's own authority, never a broker grant; NOTHING else: no `CONSUMER.MSG.NEXT`/`$JS.ACK` (watching is never draining), no `STREAM.MSG.GET.EPW_<space>` (no reconciliation authority), no consumer create/update/delete, no `epw.>` publish | mediated |\n| Work-pool consume + ack | the pool's owning endpoint ONLY (workers hold NO pool grant, \xA713.5) | **bind-only** on the provisioner-pre-created exact-filter `poolD` (grammar above): `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>`, `$JS.API.CONSUMER.MSG.NEXT.EPW_<space>.<poolD>`, `$JS.ACK.EPW_<space>.<poolD>.>` (ack only after committed terminal state); NO consumer create, NO stream-wide read | mediated |\n| Lease issue / fencing advance | the pool's owning endpoint (`lease` command) | its `lease` record keys (\xA713.7 grammar), via the record-writer seam | mediated |\n| Lifecycle mapping / teardown | minting manager's commit path; lifecycle-pinned deprovisioner | the **unsplit** alias CAS head `$KV.cotal_records_<space>.lifecycle.<owner>.<actor>` (one atomic key, NOT `.spec`/`.status`-split; the authoritative current mapping and the only `mappingRevision` source, activation/retirement serialize here by CAS, \xA713.7; NEVER-DELETED, three states `active | retiring | retired`, transitions only inside the \xA713.1 operations) + the create-only space-global UID reservation `$KV.cotal_records_<space>.uid.<lifecycleUid>` (\xA713.1: won BEFORE any gate or head write; NEVER-DELETED); leader-consistent current-mapping read `$JS.API.DIRECT.GET` is NOT used for authority reads of this key (the records bucket may follower-serve; a fresh mapping read is a leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` last-by-subject get on the head key; leader-served for read-your-writes, granted to the trusted mapping-reader/mediator profile, not a follower-served `DIRECT.GET`; that reader profile ALSO holds exactly `$JS.API.STREAM.INFO.KV_cotal_records_<space>` so it can shape-prove at bind time that the stream it leader-reads is the primary, un-mirrored, non-evicting records store (\xA713.12); a reader that cannot prove its store's shape MUST refuse to serve authority reads); optional append-only per-UID audit `$KV.cotal_records_<space>.lifecycle.<owner>.<actor>.<lifecycleUid>`; teardown: exact lifecycle-keyed names only | mediated / broker-pinned delete |\n| Acceptance obligation (reservation/drain, \xA713.8) | the admission mediator (per endpoint; the canonicalizer holds NO raw `oblig.` grant) | create-only winner + monotonic revision-pinned CAS on `$KV.cotal_records_<space>.oblig.<targetUid>.<endpoint>.<cO>.<cA>.<cUid>.<id>` (\xA713.7; the key derives from the broker-authenticated request subject plus the create-fence currency reads of \xA713.8, never from a body field; proof issuance only after the post-create recheck); its winner/settle reads are FENCING, leader-served `$JS.API.STREAM.MSG.GET` on the obligation key and on the EPF decision subject; its currency reads are FENCING, leader-served `$JS.API.STREAM.MSG.GET` on the target's `lifecycle` head AND on the endpoint's `govern` head (\xA713.6: the govern head read is what surfaces both a staged `pendingPolicyKey` (which pauses policy-admitted proof issuance) and the enforced policy selector the mediator follows to the immutable `policy.<endpoint>.<digest-hex>` version; the mediator reads govern and policy for its OWN endpoint only, the confined-reader identity bind) PLUS the immutable `policy.<endpoint>.>` version it names; PLUS create-only publish on the endpoint's EPF decision subjects for the TERMINAL REJECTION settle only (\xA713.8: its own recheck refusals and the retirement/policy drains, which settle through it); the broker cannot distinguish a rejection payload from an acceptance, and rejection-only is NOT subject-expressible (both decisions MUST share the create-only decision subject for first-wins settlement), so this grant's residual is explicit per D32: a compromised mediator can forge a decision for ITS endpoint INCLUDING AN ACCEPTANCE, an escalation to injecting executed work, never merely reject/stall (the same class of trust already placed in that endpoint's canonicalizer), and never beyond its endpoint (the decision-publish row is endpoint-literal); obligation enumeration (the \xA713.1 retirement barrier's `oblig.<targetUid>.>` discovery + quiescence recheck, and the mediator's own `oblig.*.<endpoint>.>` policy-movement drain, \xA713.6) runs through a SEALED records scanner, the same seal as the auth-ledger scanner above: this profile holds NO `$JS.API.CONSUMER.CREATE` (nor INFO/MSG.NEXT/DELETE) on `cotal_records_<space>`, because a consumer-create request BODY is not subject-ACL confinable: an extended `CONSUMER.CREATE.<records>.<name>.<oblig filter>` grant still admits a body with `durable_name` and a push `deliver_subject`, a DURABLE exporter of the whole `oblig.` subtree that SURVIVES the credential's connection close and revocation (nats-server#8274; reproduced live against the prior grant). The fence-free `LastPerSubject` enumeration `CONSUMER.CREATE` lives in exactly ONE profile: a sealed records scanner the trusted process opens for itself and NEVER hands out (its credential, connection, and seed reach no caller; the same process-memory residual class as the auth-ledger scanner), pinned to ONE literal consumer name under a FORCED pull/ephemeral/`AckPolicy.None`/`DeliverPolicy.LastPerSubject`/memory config, bind-verified before use and unconditionally deleted after, its CREATE filter confined to the `oblig.` subtree, and the injected scanner bonded to its exact space so a hand-assembled or foreign-space scanner never enumerates; its fencing `STREAM.MSG.GET` rows are stream-level grants whose read exposure is space-wide, explicit per D32 (the terminal-cleanup row's same read residual); its reply inbox is connection-scoped (`_INBOX_<connId>.>`, never the account-wide default); the rows are NEVER-DELETED, a WRITER discipline the broker cannot fully enforce: the raw KV publish grant is operation/header-blind, so a compromised mediator can overwrite its own endpoint's row to a valid `terminal` value (hiding cleanup debt) or emit DEL/PURGE markers, where every reader refuses a deletion marker loud as corruption (\xA713.12 retention floor) and the records stream denies stream-API message-delete/purge, leaving the valid-row overwrite as a second explicit D32 residual, exactly parallel to the decision-forge residual and confined the same way (its own endpoint's rows only) | mediated |\n| Terminal pool cleanup (\xA713.1 barrier) | the retirement cleaner profile: minted per (retirement `op` \xD7 endpoint), its grant listing the EXACT pools of this operation's EFFECTIVE INVENTORY, DISCOVERY-ONLY: the target's accepted `oblig.<lifecycleUid>.>` pool routes (the barrier takes no caller-supplied hint, so every listed pool is one the target holds accepted work on), never a pool wildcard, never space-wide EPW rights, DISTINCT from every owner/agent/endpoint profile (never the revoked owner's credential), bounded-lived and, once the pool is proven quiescent (every prior owner ACK drained through `AckWait`, and a fresh consumer read shows zero `num_pending`/`ack_pending`; a fire-and-forget ACK confirmed with `AckSync`, never assumed), REVOKED and cluster-verified-EVICTED (its own principal) BEFORE any frontier records (\xA713.1 order), so no in-flight cleaner can ACK a redelivery after the alias is reused | runs only AFTER the target's obligation drain reached quiescence (\xA713.1 order) and BEFORE the frontiers; bind-only on each named pool's provisioner-pre-created durable: `$JS.API.CONSUMER.INFO.EPW_<space>.<poolD>`, `$JS.API.CONSUMER.MSG.NEXT.EPW_<space>.<poolD>`, `$JS.ACK.EPW_<space>.<poolD>.>` (re-proving at bind, per the work-pool row, that the durable's filter is exactly the named pool's subtree, pull mode, unlimited delivery ceiling), plus its own connection-scoped reply inbox `_INBOX_<connId>.>` (never the account-wide default) and leader-served terminal-observe reads `$JS.API.STREAM.MSG.GET.EPF_<space>` on `wrk.>`/`dec.>` item subjects, a STREAM-level grant whose read exposure is space-wide, explicit per D32; the cleaner holds NO lease or records authority, NO `wrk` (or any EPF/EPW) publish, NO consumer create/update/delete, NO raw stream DELETE: for each delivered message it hands the item's coordinates and requested disposition to the retirement settlement executor (next row; cleaner-supplied coordinates never authorize, the executor re-derives them from the durable acceptance), then re-reads and codec-validates the executor's lease-derived terminal, and ACKs ONLY a message whose item is durably terminal (a live, unexpired, foreign-target item is NEVER settled or ACKed, and the barrier refuses to close frontiers while one remains unsettled); this profile's explicit D32 residuals are terminal-free ACK suppression across its WHOLE EFFECTIVE INVENTORY (every discovered pool: a raw `$JS.ACK` cannot be broker-conditioned on a prior terminal, so compromise can silently drop effective-inventory-pool deliveries without settlement) and the space-wide `STREAM.MSG.GET` read exposure; it can forge NO terminal and mutate NO lease (it holds no write grant at all) | mediated |\n| Retirement settlement (\xA713.1 barrier executor) | the retirement barrier's op-bounded executor: a DISTINCT per-operation principal (`local.epexe_<opId-hash>`, CONNZ principal-tagged) minted per (op \xD7 endpoint) over this operation's EFFECTIVE INVENTORY bound to the durable intent (`opId`, target lifecycle; the pools are the target's accepted `oblig.<uid>.>` routes, DISCOVERY-ONLY (no caller-supplied hint)), its settlement code running on ITS OWN connection, live only for that operation and revoked + cluster-verified-evicted by the barrier at the same fence as the cleaner, BEFORE any frontier records; never the cleaner profile, never the barrier's standing connection, never a standing grant | the settlement seam is EFFECTIVE-INVENTORY-CLOSED: for every item the cleaner hands it, the executor re-derives the authority coordinates from the item's durable acceptance decision (a FENCING leader-served read; cleaner-supplied coordinates never authorize) and refuses a ref whose endpoint or pool is outside its EFFECTIVE-INVENTORY spec (the discovered pools), a decision that is not an accepted pool admission, an `expired` request before the item's OWN `workExpiry`, and a `retired` request for an accepted target that is not the intent's lifecycle (the confused-deputy closure: a cleaner chooses refs but can never borrow this authority beyond that effective inventory or the retirement lifecycle); it settles by CASing the item's `lease.<endpoint>.<pool>.<acceptance>.spec` record to a settled state, where the ONLY settlements it may INITIATE are `expired` (bound to the item's own horizon) and `retired` (re-bound to ITS operation's retiring target through the acceptance) and an ALREADY-settled lease DOMINATES (a crashed owner's `committed` lease is derived and its terminal published verbatim, never overwritten, never contradicted), then publishes/observes the exact lease-derived `wrk` terminal create-only (first terminal wins, \xA713.8 cancellation ordering) for the cleaner to validate; its authority is lease-record CAS plus `epf.<endpoint>.wrk.<pool>.>` publish on its effective-inventory pools plus the leader-served fencing reads its own code path performs (`STREAM.MSG.GET` on the facts stream and on the records store, plus the records store's bind-probe `STREAM.INFO` and `$JS.API.INFO`; NO work-stream read: the settlement path always settles or expires through the lease key before any EPW live-entry probe, so that read is unreachable and ungranted) and its connection-scoped reply inbox, and NOTHING else (no consumer authority anywhere, no work-enqueue publish, no auth-store access), and it carries the write residual the bounded cleaner does NOT: KV subject permissions cannot distinguish CAS from overwrite or DEL/PURGE markers, and the `wrk` publish is payload-blind, so a compromised executor can forge a lease settlement or work terminal within its WHOLE EFFECTIVE INVENTORY (every discovered pool; the per-item checks above bind honest execution, not a compromised bearer), explicit per D32, op-bounded and effective-inventory-confined, never standing, never beyond that inventory | mediated |\n| Drain commit applier (\xA713.8 accepted-self recovery) | a per-op, per-repair principal (`local.epapl_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints ONLY after the commit key passes the CLOSED self-commit class: the key's kind must resolve in the canonical frozen kind registry to a NON-authority definition whose targeted `spec`/`status` half is registered to the \xA713.8 commit-path writer, at exact arity (which structurally excludes every authority HEAD, including the 3-token lifecycle head) with every qualifier token validated; a key outside the class refuses BEFORE any credential exists (the confused-deputy closure: a forged accepted-self row cannot turn `oblig.`/`govern.`/`policy.`/`uid.`/`frontier.`/a lifecycle head/an unregistered kind into a granted coordinate) | exactly ONE `$KV.cotal_records_<space>.<commitKey>` publish row plus its connection-scoped reply inbox; NO reads, NO wildcards. It executes the mediator-validated command verbatim: the resolved, canonically digest-verified intent bytes at the pinned base revision, written by guarded CAS; a CAS loss reports the another-writer conflict and the drain's re-enumeration re-classifies (landed / superseded), never a blind retry. NAMED residual: KV subject permissions cannot distinguish CAS from overwrite or DEL/PURGE, so within its one granted key a compromised applier can overwrite or delete for the credential's short life \u2014 the confinement is the exact key, the closed class, and the op-bounded lifetime, never write semantics. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Drain route reconciler (\xA713.8 accepted-pool repair) | a per-op, per-repair principal (`local.eprec_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints only to execute a MEDIATOR-DERIVED closed repair command: the mediator reads the item's durable acceptance decision itself (a leader-served fencing read), binds it to the obligation row (fingerprint/sourceSeq/route/horizon), and derives the exact EPW item subject plus the canonical acceptance item bytes (\xA713.6); the executor re-validates the exact six-token item shape for its own space and holds NO derivation authority (row-supplied coordinates or bytes never reach a grant) | exactly ONE `cotal.<space>.epw.<endpoint>.<pool>.<cOwner>.<cActor>.<cUid>.<id>` create-only publish row plus its connection-scoped reply inbox; a lost create is benign (a concurrent enqueue won; the drain re-reads establishment either way, so a no-op executor still fails closed); the payload-blind enqueue residual is confined to the one item subject for the credential's short life. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Drain effects canceller (\xA713.8 option-(i) retirement cancel) | a per-op, per-repair principal (`local.epcan_<opId-hash>`, CONNZ principal-tagged) the retirement drain mints only to execute a MEDIATOR-DERIVED effects-cancel repair: the mediator reads and row-binds the acceptance decision itself and derives the exact completion subject (the `eff` marker or the goal `result` coordinate; the executor re-validates that exact shape for its own space); the cancelled terminal is built by the CORE validated builders, which refuse a foreign or absent target \u2014 a retirement cancels only ITS OWN target's accepted work \u2014 and never fabricate success (the effects union's `cancelled` member, or the goal union's first-class `cancelled` state with the digest-bound retirement attribution) | exactly ONE completion-subject create-publish row plus its connection-scoped reply inbox; CREATE-ONLY, so first-terminal-wins is structural (a racing real completion that landed first wins and the cancel loses its create harmlessly; the drain re-reads the winner either way, so a no-op executor still fails closed); the payload-blind single-subject create residual is confined to the one marker for the credential's short life. RETIREMENT-FENCE residual (\xA713.1/\xA713.13): no credential-ledger row backs this bearer, so the retirement fence guarantees KILL-LIVE (cluster-verified eviction of any live connection before the frontier), never deny-new \u2014 the connection is minted non-reconnecting so a KICK is durable in one round, and a fresh connect with a still-unexpired held bearer+seed after that point-in-time scan is the accepted residual, dominated by data-account signing-seed compromise (signing-key rotation is the only true deny-new) | mediated |\n| Auth endpoint rail (the `auth` listener, \xA713.2) | the auth service's dedicated LISTENER credential: serve + derived replies on the `ep.one.auth` class rail, standing with the plane. The surface is GENERIC \u2014 \"retire a lifecycle (owner, actor, lifecycleUid)\" \u2014 never caller-specific; the TARGET rides the subject as the `handle` triple (`ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.<nonce>`) and caller attribution is the SUBJECT-derived, broker-ACL-enforced caller triple. The reply target is DERIVED from the parsed request (responder instance + caller triple + nonce), so no caller- or payload-supplied reply target can arrive at all \u2014 the bound-reply rule became structural rather than a check. Serve-time authz is the RAIL-TIME serve-issuance-gate check, fresh per request: ONE leader-served `STREAM.MSG.GET` of `epgate.<serveEndpoint>.<serveInstanceId>` \u2014 coordinates the caller NAMES but which do NOT authorize \u2014 requiring (a) the row is present and not `retired`, (b) `row.principal == principalKey(callerOwner, callerActor)` (THE PRINCIPAL CROSS-CHECK: a caller may only be authorized by its OWN serve registration; naming a foreign row buys a refusal, never an authorization), and (c) `row.processEpoch == serveEpoch` (a superseded predecessor after a restart is refused). An absent or TTL-expunged row reads ABSENT and refuses fail-closed. This binding is ALIAS-LEVEL, not incarnation-level: the gate is keyed by the PERSISTED `instanceId` and its row carries no lifecycle uid, so a same-principal predecessor presenting the current epoch still passes \u2014 binding the publishing incarnation would require a gate-row schema change. The four-outcome idempotence table answers in operator vocabulary (already-retired = success; the same stable opId resumes; a foreign operation refuses naming it; a stale incarnation refuses naming the current one), and every refusal is a COMPLETE no-op stated as such | subscribe `ep.one.auth.>` QUEUE-QUALIFIED (queue group `auth`; \xA713.9 forbids a plain subscribe of the class rail) + publish `ep.reply.auth.<instanceId>.<epoch>.*.*.*.*` (REPLY PLANE ONLY: the request and reply planes are disjoint in the grammar, so the listener credential cannot express a request subject at all \u2014 the self-forge is closed structurally, not by carving replies out of a shared subtree) (replies ONLY: the handler only ever responds on the DERIVED reply subject, and the reply plane cannot express a request subject at all, so a request is unpublishable by the listener credential, closing the self-forge where a compromised listener publishes a request as an authorized caller and passes its own subject-derived check) + `$JS.API.INFO` + the ONE serve-issuance-gate read row + its connection-scoped inbox; NO store writes, NO consumer authority, NO scanner/plane reach \u2014 every executing right stays with the plane's own registry and retirement deps (the drain rides the plane's ONE sealed records scanner) | mediated **NOW A CONFORMING ENDPOINT (Cotal #399, closed): the plane registers `svc.auth.<instanceId>`, publishes contract artifacts, and serves the reserved `describe`, so a generic client discovers and invokes this command the way it would any other registered endpoint (the two rows immediately below). The rail answers the v1 envelope; a legacy `{op,args}`/`{ok,data,error}` body is refused `unsupported-version`.** |\n| Retirement requester (per-despawn, \xA713.2) | an EPHEMERAL one-shot credential the space manager mints per despawn (`retirement-requester` profile, five-minute window): request + reply ONLY, for exactly ITS OWN caller triple AND exactly ONE grant-pinned TARGET incarnation (the `handle` triple is literal in the grant; the per-request nonce is the only wildcard token), so a leaked requester cannot be re-aimed at another lifecycle. The manager derives a STABLE opId from the retiring lifecycleUid, so a despawn retry, a same-name-spawn nudge, and the auth service's boot resume all drive the SAME operation. The requester holds no executing right \u2014 a leaked credential can only ask the rail to retire a lifecycle, and the rail's fresh serve-issuance-gate check (including the principal cross-check) + idempotence table bound what that ask can do | publish exactly `ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.*` (its minting manager's own caller triple, its one target) + subscribe its own reply-plane filter `ep.reply.*.*.*.<cO>.<cA>.<cUid>.*` and its connection-scoped inbox; nothing else | mediated **`handle`-MODE DEVIATION, stated explicitly (Cotal #399): this row is NOT redemption-minted.** `handle` is normatively redemption-minted only - its triple pinned at redemption from an issuer-signed capability artifact, carrying attenuation, conferral through the trusted auth service, and ledgered `sourceChain` lineage. **This path has NO issuer-signed artifact, NO redemption step and NO `sourceChain`**: the row is built directly from the minting manager's own coordinates under root authority. `handle` is used because it is the ONLY mode with arity 3 (every other mode resolves against the CURRENT mapping, the wrong semantics for retiring a NAMED incarnation), and the reader-facing invariant - the validator re-checks only currency - IS honoured by the serve-time mapping check. What is absent is delegation lineage and artifact revocation; there is no independent issuer/holder boundary on this one-shot path whose revocation would change this requester's authority. Genuine redemption-shaping is tracked at #399. |\n| Registered auth instance (Cotal #399, the M4 conformance closure) | the auth service's own boot registration, over the plane's registration credential (\xA713.1) | the plane registers `svc.auth.<instanceId>` through the standard `registerServiceInstance` path (the same record shape and registration barrier every other endpoint uses), publishes its `retire-lifecycle` contract artifacts to the content-addressed contract store, and serves the reserved `describe` alongside the command: a generic client's `resolveService` now discovers this endpoint, its closure digests, and its current instance/epoch the way it would any other registered service, closing the round-8 `#399` gap named in the two preceding rows | subscribe `ep.one.auth.>` QUEUE-QUALIFIED (queue group `auth`) + describe reply on the same reply-plane rows as any other registered endpoint + the registration-barrier and contract-artifact publish rows shared by every `registerServiceInstance` caller; no additional store authority beyond that shared registration path | mediated |\n| Retirement requester, describe + registered-endpoint call (Cotal #399, the M4 conformance closure) | the same `retirement-requester` profile above, now calling through the generic client (`resolveService` + `invokeCommand`) instead of a hand-built subject | in addition to the exact-mode `retire-lifecycle` request row already granted above, the profile carries the baseline wildcard-endpoint `describe` row (`epDescribeAllGrantRow`, pinned to this caller's own triple) and a bounded contract-store direct-get row (`$JS.API.DIRECT.GET.<EPC stream>.<space>.epc.>`) so the requester can resolve the endpoint's registered contract digests before it calls; the request itself is still minted in `exact` mode, target-pinned to the one incarnation named at mint time | publish the same exact-mode request row as above + the describe wildcard row + the contract-store direct-get row; subscribe its own reply-plane filter and connection-scoped inbox; nothing else | mediated |\n| Governance head (registration linearization) | the provisioner-registration principal | the **unsplit** governance head `$KV.cotal_records_<space>.govern.<endpoint>` (\xA713.7): it reads the head FRESH under the frozen registration gate (a FENCING read, read service above: leader-served `$JS.API.STREAM.MSG.GET.KV_cotal_records_<space>` last-by-subject on the head key, never the follower-served `DIRECT.GET` the records bucket would allow) and is the head's ONLY writer (slot-take CAS in phase 1, promote CAS after the spec publish); the SAME principal holds the write on `$KV.cotal_records_<space>.policy.<endpoint>.>` (each immutable policy version is published exactly once, before the stage CAS that names it). The immutability of a policy version is a TRUSTED-WRITER INVARIANT, not a broker-enforced subtraction: KV create/update/delete all publish to the one `$KV.\u2026policy.<endpoint>.<digest>` subject, and NATS subject permissions cannot distinguish the create-CAS header or the `KV-Operation` header, so a subject grant cannot forbid an overwrite or DEL. The invariant is upheld by the writer's create-only CAS plus every reader's SELF-CERTIFICATION (\xA713.7: the value must digest to the key), so a changed-byte overwrite is REFUSED on read; the residual, confined to this prefix, is that a buggy or compromised provisioner could still DEL or same-byte-overwrite an enforced version and (history 1) destroy its availability, at which point admission pauses fail-closed rather than admitting under a lost policy. No agent, endpoint, observer, admin, or host profile holds any grant. The head is NEVER-DELETED (the `lifecycle`-head discipline): no grant permits DEL/PURGE on `govern.>`; a reader treats only TRUE ABSENCE as a virgin head, and a deletion marker refuses loudly as corruption (\xA713.12 retention floor), never as absence | mediated |\n\nTerminal pool cleanup settlement is lease-fenced across the two profiles above: the executor\nCASes the item's lease (or observes the winning settled lease), publishes/observes the exact\nlease-derived `wrk` terminal, and only then does the cleaner, after re-reading and\ncodec-validating that terminal, ACK the delivery. A `wrk` create that bypasses the lease CAS is\nnon-conformant: it can contradict a racing commit.\n\nAn `eff` completion fact `epf.<endpoint>.eff.<cO>.<cA>.<cUid>.<id>` is a CLOSED two-member\nunion carrying a REQUIRED `outcome` discriminant on EVERY member (the goal union's `state`\nbar, applied to effects: a member is never structurally assignable to the other, and every\nreader is forced to read the outcome). The RAN member is\n`{ v: 1, id, fingerprint, caller, sourceSeq, ts, outcome: \"ran\" }`; the RETIREMENT-CANCELLED\nmember is `outcome: \"cancelled\"` plus exactly `cancelled: { opId, target }` \u2014 the same\nidentity spine, plus the binding to the retiring target's lifecycle and the retirement\noperation that cancelled it. A fact missing the discriminant, or claiming one outcome while\ncarrying the other's fields, refuses. A reader that sees `cancelled` KNOWS the effect did not run; the member is never\na forged success. Both members' caller triple and `id` are bound by the subject, and their\n`fingerprint` and `sourceSeq` MUST equal the accepted decision's. The cancelled member may be\nwritten ONLY for an acceptance whose own `target` names the retiring lifecycle (a retirement\nnever cancels a foreign target's work), publishes CREATE-ONLY on the SAME subject the real\nmarker would use \u2014 so first-terminal-wins is structural: a racing real completion that lands\nfirst wins and the cancel loses its create harmlessly, and vice versa \u2014 and is produced by\nthe drain's per-op canceller profile (\xA713.9). An ACTION needs no new member: the `goal\u2026.result`\nunion already carries the first-class `cancelled` outcome state, and a retirement-cancelled\ngoal terminalizes through it with the same acceptance-fingerprint binding and the retirement\nattribution in its digest-bound payload (`data.cancelledBy = { opId, target }`). An\neffects-route drain compares the PARSED fact against the acceptance and treats EITHER bound\nmember as established; an action's drain instead requires the parsed `goal\u2026.result` fact whose\n`fingerprint` matches the acceptance. Subject presence alone never proves completion: a bare,\nmalformed, or mismatched fact refuses the drain loud (\xA713.8).\n\nRaw `STREAM.MSG.GET` and `CONSUMER.MSG.NEXT` authority carries a caller-selected reply subject.\nFor every trusted profile holding those APIs, D32 includes confused-deputy response injection:\ncompromise can direct fetched API/message bytes onto a foreign subject even though its\nconnection-scoped inbox prevents subscribing there. This is injection, not foreign read access,\nand requires a future fixed-destination mediation boundary to remove.\n\nDeletes beyond these rows: only the lifecycle-keyed deprovisioner (exact names, \xA713.1) and\nstream retention.\n\nA **mediated** row means the raw storage grant is held only by a narrowly scoped writer\nprincipal (per endpoint, never a universal writer), with authenticated caller binding,\nidempotent request semantics, and bounded failure/backpressure; CAS headers, fingerprint\nrules, schema validity, and digest-correct bytes are *enforced* there. A **direct** row means\nthe broker guarantees writer/key containment only, and the row **explicitly downgrades**\nCAS/schema/header/byte correctness to a conforming-client guarantee; readers of direct-row\nstate fail loud on invalid content. No profile (agent, observer, admin, host) holds generic\n`$JS.API.>`/`$KV.>`/`$O.>` authority over control-surface state, for the contract store that\nmeans the REAL subjects and APIs: **write** on `cotal.<space>.epc.>` belongs\nto the contract publisher alone (create-only per digest subject); **read** is the\nsubject-scoped last-by-subject Direct Get of the reader row above, never a body-selected\nform and never a consumer, because there is nothing to replay: one message per digest\nsubject IS the store, with verify-on-read as the tamper\nboundary; and the **stream-management surface** of `EPC_<space>`\n(`$JS.API.STREAM.{UPDATE,DELETE,PURGE,MSG.DELETE}.\u2026`) is held by NO profile, publisher\nincluded, stream lifecycle belongs to space setup under operator provisioning authority\nonly, which is what \"immutable once published\" rests on (a `$OBJ.>` deny matches no NATS\nsubject and audits nothing).\nThe matrix is re-audited mechanically (decoded-credential fixture + live positive/negative\nprobes, with predicates over the real `$O.`/`$JS.API` subject forms) at every phase that\nadds a resource or changes ownership.\n\n**Writer table (core kinds, mediation decided, D7: authoritative CAS/schema record writes\nare mediated by separately scoped spec/status writer principals; an endpoint holds no raw\noverwrite grant on its own record keys).** `svc`, spec: the provisioner/registration path,\n**mediated** (CAS + schema enforced at registration); status: the owning instance's commit\npath, **mediated** with **epoch currency enforced at the writer**: the writing epoch is\nread from the broker-authenticated `epr` ingress subject (\xA713.2, the instance's serve\ncredential pins the epoch token there, so a stale process CANNOT claim the successor's\nepoch: the value is attested by the grant, never by payload), and the writer validates it\nagainst a FRESH read of the authoritative lifecycle mapping's `processEpoch`,\nrejecting a non-current epoch (`expired`), monotonicity against the stored status epoch\nalone is NOT sufficient, because between the takeover CAS (mapping N\u2192N+1) and the completed\nrevoke/evict barrier the superseded N would still equal the stored status epoch and pass a\nbelow-stored check, and additionally rejects a below-stored epoch (`conflict`). The record\nkey is restart-stable and\ncannot carry the epoch (\xA713.1), so this epoch-pinned-ingress-plus-fresh-equality mediation\nis the record's only stale-writer fence.\n`signer`, spec+status: the space operator's registry tooling as the scoped writer\nprincipal, **mediated**. `handle`; keys are **issuer-namespaced**,\n`handle.<issuerKeyId>.<id>`, so two issuers can never collide or cross-revoke; spec: the\nissuer through the record-writer seam, create-only; status/revocation: issuer or space\noperator, **mediated and monotonic** (revoked never un-revokes; the signature stays the\ncontent authority; mediation enforces key grammar, CAS, and schema). `contracts` index, the instance, **direct** (explicitly advisory and\nnon-authoritative; `describe` is authoritative; readers fail loud on invalid state).\n`goal`/`cp` projections, status: the owning instance's commit path, **mediated**. Lifecycle\nmapping records (\xA713.1), the minting manager's commit path, **mediated**, CAS-only. The\n`govern` head (\xA713.7), the provisioner-registration principal, **mediated**, CAS-only (the\nmatrix row above).\nCanonical acceptance, work-pool enqueue, lease state, and contract-artifact publication,\n**mediated** per the matrix above.\n\n**Trait seam.** Core owns the fail-closed pre-effect verification interfaces (guard call,\npriced-proof verification, governed-attachment verification); policy engines, token formats,\nand payment rails remain extensions behind those seams.\n\n### 13.10 Receipts and signing trust anchors\n\n**Receipts.** A receipt binds a request to its outcome, signed and non-repudiable, for\nmetering, disputes, and pipeline causality; payment semantics stay opaque to core.\n\n`Receipt` = `{ v: 1, requestId, sourceSeq (the accepted submission's sequence, the\nexecution identity its subject carries, \xA713.2), space, endpoint, command, instance: { id, instanceId, epoch },\ncaller: { id, lifecycleUid }, schemaDigests: { input, output }, argsDigest, outcome: { ok,\ncode? }, resultDigest?, ts, signer: { keyId }, sig }`, canonical JSON, Ed25519-signed\n(`space` per the unconditional artifact rule below).\nLifecycle and epoch are recorded as **evidence**, never redemption authority. A command\ncarrying `ai.cotal.priced` MUST verify an independently verifiable payment proof in the\n`auth` slot before effect (never a bare \"settled\" assertion) and emit a receipt fact\n(`epf\u2026.receipt.<cOwner>.<cActor>.<cUid>.<id>.<sourceSeq>`, the caller- and\nexecution-scoped subject of \xA713.2; receipts are create-only per subject). A priced command\nis therefore journal-class: its receipt derives its identity from the accepted submission's\ndecision fact and its outcome from the committed terminal, never from emitter-supplied\nparameters, so a command with no acceptance fact has no receipt to emit; a conforming\nimplementation refuses to serve `ai.cotal.priced` on an ephemeral command (an\nadmission-time refusal at serve construction, never a first-request surprise). Receipt\nretention: default 90 d, \u2265 the idempotency horizon (outcome-stated by the \xA713.12 retention\nfloor).\nVerification: signature against the anchor registry + digest recomputation; forged or\nrequest-mismatched receipts fail loud. Receipts MAY be emitted for unpriced commands.\n\n**Trust anchors.** One per-space registry covers every signed artifact of this section,\nauthorization slots, capability handles, checkpoint resumes, trait definitions and\nattachments, session grants, receipts. Anchors are `signer.<keyId>` records: spec =\n`{ keyId, publicKey (Ed25519), owner (the principal or reverse-DNS domain the key belongs\nto), roles \u2286 [handles, traits, receipts, resume, sessions, authz-slots, obligations,\npayments], scope: per-role structured ceilings, for a `handles`-role key the **full grant\ndimensions**, in the handle-grant shape itself: the endpoints/domains, and per entry the\nmaximal commands, authorization modes, target patterns, instance ids, and read subtrees the\nkey may issue for (a handles- or receipts-role key without a dimension ceiling has that\ndimension closed, not open); for other roles the endpoints/domains it may attest for,\nvalidFrom, validTo }`, status = revocation. `issuer-authority` is defined by exactly this\nrecord: a verifier resolves the artifact's keyId FRESH at verification and enforces the role\nAND its scope under the \xA713.6 containment order (`handle.grants \u2286 anchor.scope`), a\nhandles-role key scoped to `com.acme.>` cannot issue for `manager`, a receipts-role key\nscoped to one endpoint cannot attest as another, and a handles-role key whose scope names no\n`handle`-mode targets cannot issue actor-pinned grants. Verification (fail closed): resolve the key,\nreject unknown keys, out-of-window use, role mismatch, or revocation (immediate for new\nverifications; effected work is not retroactively unwound). Rotation registers a successor\nand closes the predecessor's window; overlap is permitted for handoff. Third-party trait\nauthorities register under their reverse-DNS domain claim. Trust roots never merge across\nspaces.\n\n**Signature encoding (normative, D28).** For every signed artifact: the signature input is\nthe UTF-8 bytes of the RFC 8785 canonical JSON of the artifact **with its `sig` field\nabsent**; the signature is Ed25519 (nkeys); `sig` carries it base64url-encoded (unpadded).\nVerification recomputes the canonical form, resolves `signer.keyId`/`issuer.keyId` in the\nanchor registry, and fails closed on any mismatch.\n\n**Replay and claims matrix (normative, per artifact type).** Every row below additionally\nand unconditionally requires `space`, the signing `keyId` (`issuer`/`signer` per shape), and\n`sig` (the \xA713.10 encoding): an artifact missing any of the three is invalid before its\nreplay rule is ever consulted, and each artifact type is a discriminated schema, a verifier\ndispatches on the type, never duck-types the claims.\n\n| Artifact | Required claims | Replay rule |\n| --- | --- | --- |\n| Capability handle | id, space, issuer, holder (principal+UID), structured grants, iat, exp (nbf, parentDigest, epoch as applicable) | reusable within TTL, holder-bound; revocable if sturdy |\n| Checkpoint resume | checkpoint token, goal id, holder (principal+UID), iat, exp, nonce | **one-use** (journaled by create-only CAS); duplicate = `conflict` |\n| Session grant | sessionId, subjects, holder (principal+UID+processEpoch), serving instance+epoch, window, iat, exp, nonce | **one-use** redemption (holder epoch fresh-checked), then live; dies with either side's epoch |\n| Guard obligation | goal/request id, attenuations, iat, exp | bound to its goal/request; reusable within it |\n| Payment proof | per the priced contract's declared policy | default one-use per request id |\n| Trait attachment | endpoint, command, contractDigest, traitUrn, value, signer, ts | revision-bound evidence; replaced only by an authorized contract revision |\n| Receipt | per \xA713.10 shape (ts, signer; no exp/nonce) | evidence, never authority; replay-irrelevant |\n\nEvery verifier rejects out-of-window use (where `exp` applies), wrong-holder presentation,\nand unknown/revoked keys.\n\n### 13.11 The hard cut\n\nThis section is an intentional hard cut on the pre-1.0 line per \xA711. The version marker is\nthe grammar itself: the `ep`/`epe`/`epf`/`epj`/`ept`/`epw`/`eps` subject kinds and the\nversioned envelope are disjoint from every v0.3 control subject and shape, and the old rails\nare removed, subjects, envelopes,\nhandlers, credential grants, minting paths. No compatibility adapter, dual serving, or\ntranslation window exists. A credential minted before the cut can publish only into dead v0\nsubjects: nothing subscribes them, no post-cut handler is reachable from them, no trusted\nreply can be elicited (a pre-cut grant matches no endpoint-surface subject by construction,\nverified adversarially with captured pre-cut credentials from every old profile). The one\nstructural exception is the pre-cut `admin` profile, whose space-wide `P.>` subscribe\npredates and therefore MATCHES the new rails: **admin credentials MUST be re-minted at the\ncutover** to the post-cut admin shape (Appendix B: messaging-plane subjects only, no\n`ep*`/`eps`/`epc` subscribe), and the pre-cut admin credential is revoked with the cut;\nthe hard-cut guarantee is not honest without it. The wire\n`protocolVersion` (\xA76, \xA711) targets `0.4` at the completion of this revision's migration, per\nthe \xA711 convention that the advertised version is the migration's normative target, and a\nv0.4-conformant participant MUST advertise it (the optional-field era ends at the marker\nboundary); `1.0` is a separate, later stability declaration (\xA711).\n\n### 13.12 NATS + JetStream binding\n\n**Broker floor.** The control surface REQUIRES NATS server \u2265 2.12 (message schedules, atomic\ncreate-CAS, counters) AND a `max_control_line` large enough for the deployment's\nmaximum-capability CONNECT line. The two floors are checked at the tier that can see them:\n\n- **Clients** check the server version from the pre-auth INFO and fail loud below 2.12 or\n  when schedules are unavailable (including the offline-assets downgrade mode). The\n  control-line limit is NOT discoverable pre-auth; an oversized CONNECT is silently dropped\n  and looks like a network fault, so a client's obligation is bounded reconnect attempts\n  plus the named diagnostic on a repeated pre-auth drop (\"CONNECT may exceed the broker's\n  max_control_line; have the operator verify it\"), never an infinite retry loop.\n- **Operator tooling** (doctor/setup) asserts the cause before any credential is minted:\n  read `max_control_line` over the system account (`$SYS.REQ.SERVER.PING.VARZ`) from\n  **every server of the cluster the credential may connect to**; the ping is fanned out,\n  the response set is checked complete against the expected server count, and a partial\n  response set is a FAILED assertion, never a pass, and require, on each server,\n  `max_control_line \u2265 (largest encoded CONNECT line of the \xA713.9 fixture set) + margin`.\n  The fixtures are **byte-reproducible** (concrete maximum-length identities, the full\n  grant set at the policy ceiling, the maximum-capability agent credential and the\n  maximum-command serve credential, the encoded credentials, the resulting CONNECT\n  lengths), so the floor is a measured quantity; the reference deployment's configured value\n  is 65536; a derived number, not an assertion. The 16 KiB policy gate remains a distinct\n  mint-time cap on credential authority, refused loudly at minting. The same assertion pass\n  checks `max_payload \u2265` the largest serialized **bounded decision fact** fixture (the\n  maximum `RejectionFact`/`QuarantineFact` under the token and detail bounds, \xA713.4) AND\n  `max_payload \u2265` the 256 KiB contract-artifact document bound plus envelope margin\n  (\xA713.7; a contract artifact is one message on its digest subject), so\n  \"the rejection fact always fits by construction\" and \"an artifact is a single message\"\n  are measured floors, not assumptions.\n\nNo sweeper fallback exists. Only 2.12 schedule semantics are assumed (same-subject\nreplacement; NOT the 2.14 stop-plus-publish path).\n\nPer-space resources, created at space setup (`STREAM.CREATE` remains denied to agents):\n\n| Resource | Captures / holds | Retention notes |\n| --- | --- | --- |\n| `EPJ_<space>` stream | `cotal.<space>.epj.>` (submissions, untrusted) | Limits; **native dedupe not relied upon**; submitters never set `Nats-Msg-Id` (\xA713.4; stream-wide header dedupe is a cross-caller suppression vector on a shared untrusted stream). A zero duplicate window is NOT server-accepted (`0` normalizes to the 120 s default; the minimum is 100 ms), so the config sets the server minimum and the guarantee is the header rule: a hostile header suppresses only another non-conformant header-bearing write; retention \u2265 recovery/redelivery lag |\n| `EPF_<space>` stream | `cotal.<space>.epf.>` (canonical facts) | Limits; acceptance via create-only CAS (`Nats-Expected-Last-Subject-Sequence: 0`); `allow_direct=true` (NON-fencing subject-confined reads only: every \xA713.9 matrix fact read is FENCING and leader-served `STREAM.MSG.GET`, \xA713.9 read service); retention \u2265 horizons, outcome-stated by the retention floor below |\n| `EPE_<space>` stream | `cotal.<space>.epe.>` (events, progress) | Limits; space policy |\n| `EPT_REQ_<space>` stream | `cotal.<space>.ept.*.*.*.*.schedule` (instance schedule REQUESTS, \xA713.2) | Limits; message schedules **DISABLED**; client-set scheduling headers are inert bytes here; retention \u2265 writer recovery lag |\n| `EPR_<space>` stream | `cotal.<space>.epr.>` (record-write ingress, \xA713.2) | Limits; epoch-pinned publish grants (\xA713.9); consumed only by the record writer; retention \u2265 writer recovery lag |\n| `EPT_<space>` stream | `cotal.<space>.ept.*.*.*.*.armed` + `\u2026.fire` (authoritative schedules + fires, \xA713.2) | `AllowMsgSchedules`; only the timer writer publishes `.armed` (\xA713.9); each schedule targets its sibling `.fire` subject (ADR-51 forbids target = publish subject); retention \u2265 max deadline + margin |\n| `EPW_<space>` stream | `cotal.<space>.epw.>` (work pools; one item per subject, \xA713.2) | WorkQueue; provisioner-pre-created non-overlapping exact-filter per-pool consumers (\xA713.9) with **`max_deliver=-1` pinned** (a finite delivery ceiling strands exhausted items outside `num_pending`/`num_ack_pending` and falsifies the \xA713.6 admission occupancy; the occupancy reader re-checks the pin at every read because MaxDeliver is editable post-create); **`allow_direct=false`**: EPW has NO non-fencing subject-confined reader (pool workers drain the WorkQueue via `CONSUMER.MSG.NEXT`, never a subject read), and its ONLY subject read is the reconciliation probe, which is FENCING and MUST be leader-served `STREAM.MSG.GET` (\xA713.9 read service; an acked item leaves the WorkQueue, an in-flight one remains readable, which is exactly the \xA713.6 predicate, and a stale follower miss would re-arm settled work). Disabling Direct Get on EPW makes that leader-served requirement STRUCTURAL: no reader (including virtual-endpoint activation reconciliation, \xA713.6) can take the follower path even by mistake. This differs from EPF, which keeps `allow_direct=true` because it DOES have non-fencing subject readers (the \xA713.9 last-by-subject fact reads); EPF's fencing CAS-winner read opts into the leader by caller choice |\n| `WFJ_<space>` stream | `cotal.<space>.wfj.*` (the workflow STEP JOURNAL, \xA714.4: **one subject per RUN, `cotal.<space>.wfj.<runId>`, not one per entry**) | Limits, file storage, **no `max_age`** and no finite count/byte limit that evicts (an evicted prefix is not a shorter journal, it is a run that re-performs effects it already performed, and a run that sleeps for a month resumes by re-reading it; retirement is by subject purge, deliberately); **`allow_direct=false`** (a resume must read its own predecessor's last appends, and Direct Get is follower-servable, so a stale miss there reads as \"this step never ran\"). Deliberately outside the `ep*` plane letters: the journal is a runtime layer over the control surface, not part of the endpoint contract. Every append is fenced by `Nats-Expected-Last-Subject-Sequence` on the run's own subject (\xA714.4); a run's driver holds publish on exactly its own run's subject plus a per-takeover replay durable filtered to it, and there is no space-wide `wfj.>` publish grant |\n| (sessions: core-only, no stream) | `cotal.<space>.eps.>` | never captured; bounded in-memory window |\n| `cotal_records_<space>` KV | records: the \xA713.7 core-kind key grammars (`svc`, `signer`, `handle`, `contracts`, `goal`, `cp`, `lease`, `lifecycle`, `govern`, `uid`, `policy`, `oblig`, and the \xA714 kinds `run`, `answer`, `notice`, `migration`) | per-key CAS; `.spec`/`.status`-split keys EXCEPT the unsplit atomic keys `lifecycle.<owner>.<actor>`, `govern.<endpoint>`, `uid.<lifecycleUid>`, `policy.<endpoint>.<digest-hex>`, and `oblig.>` (\xA713.1/\xA713.7/\xA713.8/\xA713.9); `allow_direct=true`, but the heads and every fencing read are leader-served `STREAM.MSG.GET` (\xA713.9 read service). **No age retention on authority keys:** `lifecycle` heads, `govern`, `uid` reservations, `policy` versions, and `oblig` rows are NEVER-DELETED (no grant permits DEL/PURGE; an age-evicted reservation would reopen UID reuse, an evicted obligation would orphan accepted work); a deletion marker on any of them refuses loudly as corruption, never as absence. **Shape is proved at bind, not assumed:** the stream MUST be primary (never a mirror/sourced copy) and MUST carry no bucket-wide silent-eviction limit (no `max_age`, no finite `max_msgs`/`max_bytes`: under `DiscardOld` a finite global limit evicts a prior authority key's latest row the moment an unrelated key is written); every trusted consumer of this store (the minting authority, the mapping reader, the mediator) verifies exactly this via `STREAM.INFO` when it binds and refuses to serve otherwise |\n| `cotal_auth_<space>` KV | the credential ledger (`cred.<lifecycleUid>.<credentialId>` + issuance gates `gate.<lifecycleUid>` + the disjoint endpoint families `epgate.<endpoint>.<instanceId>` / `epcred.<endpoint>.<instanceId>.<credentialId>` + the staging family `stage.>` + source gates `srcgate.<issuerKeyId>.<id>` + lineage index `bysrc.\u2026`, \xA713.1) + session ledger (`session.<sessionId>`, \xA713.6) | trusted auth path ONLY; no agent, endpoint, observer, admin, or host profile holds any grant (\xA713.9 matrix); **`allow_direct=false`** (every fence is a leader-served revision-pinned CAS write; Direct Get's follower/mirror reads would defeat read-your-writes, \xA713.1); CAS + monotonic states. **No bucket-wide age retention:** `gate.`, `epgate.`, `srcgate.`, and `session.` authority keys persist until their lifecycle/handle/session is explicitly terminal (an age-evicted `open` gate would silently reopen minting, or drop a `frozen`/`retired` fence); only `cred.`/`epcred.`/`bysrc.` rows carry a per-key TTL bounded by the credential TTL (NATS per-key message TTL, \u2265 2.12), never a bucket MaxAge; `stage.` rows follow their operation's retention, never a ledger row's. **Shape is proved at bind** (the records-store rule above, plus `allow_direct=false`): primary, un-mirrored, no bucket `max_age`, no finite `max_msgs`/`max_bytes`; the trusted auth path verifies this via `STREAM.INFO` when it binds and refuses to serve otherwise |\n| `cotal_issued_<space>` KV | issued-authority evidence (\xA713.15): `v1.<owner>.<actor>.<uid>.<generation>` (immutable evidence), `attempt.v1.\u2026` (the one-field attempt row), `bysource.v1.<sha256>.\u2026` (the reverse index from a source gate to the issuances depending on it) | Limits, file storage, no age eviction, **`allow_direct=false`** (every read is a fence); create-only evidence, revision-CAS attempt; never deleted while the issuance or anything admitted under it is resumable. Immutability is BROKER-ENFORCED the way the EPC store's is: `allow_rollup_hdrs=false, deny_delete=true, deny_purge=true`, set once at creation and verified by every provisioner that binds, so a holder of the issuer's own key row cannot replace evidence or empty the bucket with a `Nats-Rollup` header, a message delete, or a purge |\n| `cotal_accepted_<space>` KV | accepted rows (\xA713.15): `accepted.v1.<acceptedToken>`, one per issuance, written by the issuer at release | Limits, file storage, `allow_direct=true`: the client's per-key `DIRECT.GET` is the discovery read; create-only, with the same three broker-enforced flags as the evidence store |\n| `cotal_admission_<space>` KV | run admissions and revocations (\xA714.8): `admission.v1.<endpoint>.<runId>`, `revoked.v1.<endpoint>.<runId>` | Limits, file storage, no age eviction, `allow_direct=false`; both keys create-only and the marker permanent, BROKER-ENFORCED by `allow_rollup_hdrs=false, deny_delete=true, deny_purge=true` (a run-admitter's own key row admits no `Nats-Rollup` replacement of the admission, and no purge empties another run's row); retained while the run, its program, its journal or its lineage is resumable |\n| `EPC_<space>` stream | `cotal.<space>.epc.>` (content-addressed contract artifacts, one per digest subject, \xA713.7) | Limits, no age eviction (artifacts are permanent); create-only mediated publication (`Nats-Expected-Last-Subject-Sequence: 0`); `allow_direct=true` (the subject-scoped last-by-subject read IS the fetch path; non-fencing, verify-on-read); permanence is BROKER-ENFORCED: `deny_delete=true, deny_purge=true` (the broker rejects the message-delete and purge APIs even from a stream-API-holding principal). Permanence is the COMBINATION of these flags, the retention floor's no-early-removal rule (below: the flags alone stop delete/purge but not age eviction or a whole-stream teardown), verify-on-read pinning WHAT a subject carries, and the stream-management surface held by no profile (\xA713.9); no single flag makes deletion structurally impossible |\n\n**Retention floor (one-use-identity facts).** A stream or bucket whose messages carry\none-use identity, that is decision facts realizing the \xA713.4 idempotency horizon, goal\nterminal facts and tombstones (\xA713.6), receipt facts (\xA713.10), and the never-deleted\nauthority heads (`lifecycle`, `govern`, the auth-bucket gates), MUST retain every protected\nmessage until its governing horizon, stated by OUTCOME: NO removal cause may drop a\nprotected fact early. That forbids not only age eviction below the horizon but every\nconforming alternative that erases it while `MaxAge` still passes: a finite\n`MaxMsgs`/`MaxBytes`/`MaxMsgsPerSubject` with `DiscardOld`, a per-message TTL,\nrollup/compaction, or a retention-policy change; for these families finite count/byte\nlimits MUST fail loud or `DiscardNew` rather than evict protected history, and message TTL\nand rollup MUST be disabled on protected subjects (a per-key TTL is permitted only on\nnon-protected keys, e.g. the auth bucket's `cred.`/`bysrc.` index rows above, never on a\nprotected fact, head, or gate). NO principal, including operator, setup, and system tooling,\nnot only \xA713.9 profiles, may `MSG.DELETE`/`PURGE`, `STREAM.DELETE`, or issue a\n`STREAM.UPDATE` that weakens any of these limits; the never-deleted heads and gates carry\nan UNBOUNDED horizon. A KV writer MUST NOT publish a DEL/PURGE marker for a never-deleted\nkey, and a reader that encounters one treats it as corruption, never as absence. (Root can\nalways destroy a broker; such an act is explicitly non-conformant, not outside this\nclause.) `CONSUMER.DELETE` is distinct and permitted: it removes a reader cursor and can\nnever mutate stored facts. Concretely: `EPF_<space>` retention \u2265 max(idempotency horizon,\nresult retention, receipt retention), because the acceptance fact is the durable\nreconstruction source for receipts, while the raw submission stream is age-evicted by\ndesign.\n\nClaim pools are pull consumers on `EPW` with `AckExplicit`, held **only by the pool's owning\nendpoint** (\xA713.5): `ack_wait` is the broker's redelivery-to-owner timer and nothing more;\nthe authoritative lease token and deadline live in the owner's lease record, never in the\nitem value (stored bytes are work identity and input only), and the owner acks only after\nthe committed terminal state. Filtered replay of events/facts uses pinned single-filter\nconsumer creates (the CHAT-history containment mechanism, \xA78/\xA79). Timer scheduling is\n**mediated** (\xA713.2, \xA713.9): instances publish only `.schedule` REQUESTS into the\nschedules-disabled `EPT_REQ` stream, where a client-set `Nats-Schedule-Target` (or any\nscheduling header) is inert bytes and the timer writer rejects a request carrying one, this\ncloses the ADR-51 confused deputy, in which a direct publisher confined only to \"some\nsubject the schedules stream captures\" could target ANOTHER instance's `.schedule` (installing\nor replacing its schedule state, since schedule headers are copied to the target verbatim) or\nits `.fire`. The timer writer alone publishes the authoritative schedule on `.armed`, with\n`Nats-Schedule-Target` = the sibling `\u2026.fire` subject derived from the authenticated request\nsubject's own tokens; and **fire handling is the trusted seam** behind it, a `.fire`\nconsumer acts only on a fired message matching a current authoritative\nschedule it owns (`timerId` + generation + deadline, \xA713.2) AND whose broker-authored\nscheduler-origin header (`Nats-Scheduler`, the schedule's subject, set by the server on\nfire) equals its own exact sibling `.armed` subject, discarding anything else as\nforged. Replacement is the writer's same-subject publish on `.armed` (server rollup); fired\nmessages appear on `.fire` carrying `(timerId, generation)`.\n\n### 13.13 Plane ownership (the sealed-scanner claim)\n\nAt most ONE authority plane per space may hold the sealed scanners (\xA713.9's seventh-round\nseal). The scanners' serialization is process-local, so two same-space auth processes would\ninterleave the literal enumeration consumers' critical sections and return PARTIAL\nenumerations: a drain declares quiescence over undrained obligations and the retirement\nfrontiers close over live work. The exclusion is broker-visible, not host-local:\n\n- **The claim row.** One exact, never-deleted auth-KV key (`plane`, subject\n  `$KV.cotal_auth_<space>.plane`) holds `{ v, generation, claimId, state: held | released,\n  ledger, records, openedAt }`, where `ledger`/`records` are the two ownership-bearing sealed\n  scanner connections' broker identities `(serverId, cid, userNkey)`. The barrier profile is\n  the row's SOLE writer, at exact arity (never `plane.>`); reads are leader-served. The\n  barrier's own identity is deliberately NOT in the row: barrier liveness is irrelevant to the\n  literal consumers and could only falsely block a reclaim.\n- **Open order.** Ensure stores; open BOTH candidate scanner connections NON-RECONNECTING (the\n  tuples must be stable and disappearance must be final) and keep them INERT (no scan\n  capability exists or escapes); take the claim by broker-atomic create (virgin key) or\n  revision-CAS (a `released` row, or a `held` row proven dead as below). Only the WINNER\n  constructs the branded scanners; a loser closes both candidates and refuses with\n  operator-legible copy. The brief dual connected-credential window before the CAS is inside\n  the trusted signing-seed residual; there is no dual SCAN authority because the capability\n  does not exist before the win.\n- **Plane credentials.** The two plane-owned scanner connections authenticate with\n  NON-EXPIRING user JWTs, for exactly these two connections and no other profile: an expiring\n  credential would have the broker hard-disconnect at expiry, and a renewal cannot be\n  presented without the reconnect the non-reconnecting shape forbids \u2014 an expiry would fence\n  the plane on a timer. The credentials never leave process memory, and the account signing\n  seed co-resident in the same memory is strictly stronger authority, so the marginal\n  exposure is the existing trusted-process residual class; revocation remains service-stop +\n  seed rotation. Every other authority credential keeps the short-expiry + in-process-renewal\n  boundary.\n- **Reclaim is liveness-only.** A `held` row is reclaimed only when BOTH claimed tuples are\n  conclusively ABSENT under a COMPLETE connection sweep, adjudicated by the delivery daemon's\n  read-only oracle over the privileged delivery-admin rail (the auth process holds no `$SYS`;\n  the D5 rail split). The closed oracle verb takes exactly the two claimed tuples and returns\n  two bound verdicts (`live | gone | unknown`) plus sweep completeness, echoing the queried\n  identities; any live, unknown, incomplete, malformed, or foreign-echo answer REFUSES the\n  takeover (at most one plane: dual-refuse is safe, dual-proceed is not). There is NO TTL, NO\n  heartbeat, and NO \"did the last sealed scan finish\" bit: a mid-scan crash drops the\n  non-reconnecting connections, a complete sweep proves them gone, and the successor's\n  fail-closed pre-clean (\xA713.9) makes its full re-scan safe. A paused-but-live process still\n  holds its TCP connections and therefore still holds the plane (no pause hazard).\n- **The single-server proof.** Connection absence alone cannot distinguish a RESTARTED\n  claimed server (`server_id` is per-broker-run; genuinely gone, and requiring its reply\n  forever would turn every whole-stack crash into a permanent reclaim wedge) from a\n  PARTITIONED one (live, unreachable; treating its absence as death authorizes a split-brain\n  steal). A `gone` verdict is therefore valid ONLY under the single-nats-server-process\n  boundary, proven per observation from the responding server's OWN topology declaration in\n  the `$SYS` reply envelope \u2014 never inferred from which servers happened to reply: every\n  reply must declare NO cluster membership and exactly one distinct server may have replied.\n  Any cluster self-report, multi-server observation, or reply without the declaration reads\n  `unknown` and refuses. Only a SUCCESSFUL, well-formed page counts toward the sweep: a reply\n  carrying an API error, a malformed or empty server envelope, a non-string cluster\n  declaration, an envelope/data server-id mismatch, or a structurally incomplete data page\n  poisons the whole observation (every verdict `unknown`). Each sweep's reply inbox carries a\n  per-call collision-resistant nonce, so concurrent sweeps can never satisfy or falsely\n  complete each other's rounds; and the auth plane closed-parses the oracle's result (exact\n  keys at every level) before reasoning over it. NAMED residuals: a leafnode- or\n  gateway-extended account is outside the cluster self-report, so such topologies are out of\n  contract for the space's account; a backup restored onto a fresh broker can present a\n  still-running foreign predecessor's `serverId` as dead. A clustered/multi-server deployment\n  requires an authoritative server incarnation/roster authority in place of this proof.\n- **Holding invariant.** The winner re-validates the claim (state `held`, its `claimId`, its\n  `generation`, AND both pinned scanner tuples \u2014 a row rewrite preserving the identifiers but\n  swapping a tuple is a lost claim, never \"still ours\") BEFORE every sealed scan (refuse to\n  enumerate) and AFTER it (discard the enumeration), inside the serialized critical section.\n  An owned scanner disconnect is a FENCING event, and the fence is FATAL to the WHOLE\n  authority plane: scan exposure is invalidated immediately, the sibling closes, every\n  authority operation (connect authorization, credential mint) refuses from that moment, and\n  the service goes DOWN loud rather than serving from a half-dead plane a successor may be\n  reclaiming; a still-live sibling correctly blocks a successor until it is closed or proven\n  absent.\n- **Clean close.** Scan-capable clients close FIRST, then the row CASes `held \u2192 released`\n  (never released while either scanner can still act), then the barrier. A crash leaves\n  `held`; the successor reclaims through the oracle. A `released` row is claimed without an\n  oracle round.\n- **Operator faces.** The three refusal states carry DISTINCT copy: a live peer (\"stop the\n  other auth process\", with the space and connection identities), an inconclusive observation\n  (fail-safe wait/retry wording that never says \"stop the other process\"; when the oracle rail\n  is down it names the delivery daemon and the restart order), and a mid-life scanner death\n  (a deliberate fail-closed stop naming the restart path). An unparseable claim row refuses\n  loudly and is never overwritten automatically.\n- **Host belt.** Launchers additionally claim an exclusive per-space pidfile, published\n  ATOMICALLY and PRE-POPULATED: the claimant writes its pid to a unique temp inode, then\n  publishes it as the slot with an atomic no-overwrite `link(2)` \u2014 no create-then-write window\n  exists for a sibling to misread, and an empty slot is impossible to publish. A live holder\n  is yielded to; a provably dead holder's slot \u2014 and an empty (pre-protocol crash shape) one \u2014\n  is reclaimed exactly once; unattributable content is never stolen. A cheap belt only, never\n  the exclusion.\n\n### 13.14 Conformance (control surface)\n\nA conformant endpoint (v0.4) MUST:\n\n1. Serve only under a credential whose serve grants match its registered name, stable\n   instance id, and registered command set (publish-side grants pinned to the current\n   epoch); register its service record before serving; advance the epoch by CAS on takeover\n   and stop serving when superseded; a takeover is complete only after the \xA713.1 barrier\n   (revoke + cluster-verified eviction of the superseded credential).\n2. Answer `describe` authoritatively, intersected only against the trusted authorization view\n   (or declared-public), failing closed when that view is unavailable.\n3. Publish contract artifacts content-addressed and immutable; validate args/replies at\n   runtime within the schema profile and budgets.\n4. Reply only on the reply rail derived from the authenticated request subject; ignore\n   payload/transport reply targets; let attribution ride the reply subject.\n5. Enforce the envelope invariants (version/op/class/target/sender, catalog codes, monotonic\n   attenuation); treat the subject, never the body, as the authorization boundary; resolve\n   targets by `(alias, lifecycleUid)` against current mappings immediately before effect.\n6. Route effects by delivery class; journaled effects only from canonical accepted facts\n   through the mediated writer; fingerprint-bind ids first-wins; hold the declared horizons,\n   retentions, and floors.\n7. Validate every Cotal-owned commit through the mediated path (fencing token + unexpired\n   lease + lifecycle + epoch as applicable); lose CAS loudly.\n8. Implement advertised composites per \xA713.6: the single action vocabulary, authorization\n   linearized at acceptance, one-use resumes, generation- and scheduler-origin-validated\n   timers (a fire counts only against its own sibling `.armed`, \xA713.12) with durable\n   reconciliation, fail-closed governed traits, bounded sessions.\n9. Fail loud below the broker version floor (from the pre-auth INFO), with bounded\n   reconnects and the named pre-auth-drop diagnostic (\xA713.12); the `max_control_line` floor\n   is asserted by operator tooling (\xA713.12), never by the client, which cannot inspect it.\n10. Connect successfully while presenting the normative maximum-capability credential\n    fixture for its profile (\xA713.9), the only test that exercises the control-line bound.\n\nA conformant caller (v0.4) MUST: hold a lifecycle-pinned credential and never present another\nlifecycle's artifacts; choose ids/goalIds/nonces within the token grammar and the 1024-byte\nsubject bound and reuse ids only per the idempotency rules; declare `class` and\n`replyExpected` and honor `contract-mismatch`/`conflict`; freeze scatter expectations from the\nregistry and classify partial results; verify digests of fetched artifacts and signed\nartifacts against the anchor registry, failing closed; refuse to resolve a **describe descriptor**\nwhose `protocol.v` it does not implement (the marker rides the descriptor and the service record,\nnever the cluster document, which carries no `protocol`), and never automatically repeat a `write`\ncommand (\xA713.7) \u2014 whatever `id` the re-issue carries \u2014 except on an outcome that proves\nnon-execution (\xA713.3).\n\n### 13.15 Issued authority\n\nThe caller triple (\xA713.1) says WHO is calling. It does not say what the credential they are\ncalling with was granted, and a host that performs an effect on a caller's behalf needs that:\nthe ceiling as the issuer accepted it, immutable, and bound to the request by the broker rather\nthan by anything the caller or a mutable ledger says. This section defines that binding.\n\n**The reference.** An issued authority is `{ space, owner, actor, uid, generation }`: the\ncaller triple plus a **generation**, 32 lowercase hex characters of issuer-chosen entropy (at\nleast 128 bits). A generation is an identifier, never a bearer secret. It is chosen by the\nissuer, never by the client, and is never reused: a reference is created once or refused.\n\n**The rail.** An issued credential's request-publish and reply-subscribe rows ride the\nversioned rail (\xA713.2), with its generation pinned literally beside its triple. A request\narriving on `ep.v1` therefore carries a broker-confined generation, and a request arriving on\nthe legacy rail carries none. A body field, a header, or a policy reference supplied by the\ncaller establishes no binding.\n\n**Issuance.** Before an issued credential's material is returned, the issuer MUST persist its\n**evidence** in `cotal_issued_<space>`: `{ version: 1, ref, sources, permissions, expiresAt? }`,\nwhere `permissions` is the credential's final effective permission ceiling (publish and\nsubscribe, each an explicit `all`, `none` or `patterns` allow plus a deny list, imported from the\nnative permission fragment so an omitted list can never read as a narrow one) and `sources` are\nthe gate coordinates the issuance depends on. Issuance is `prepare \u2192 release`: the evidence and\na `prepared` attempt row are written create-only, the issuer performs its own finalization, and\nthe attempt row is CAS-advanced to `active` at the revision the prepare observed. A prepare that\nloses its create is refused; a release whose CAS loses is `aborted`. The evidence store is\nappend-only at the broker (\xA713.12: unlimited per-key history, no rollup header, no message delete,\nno purge), and the evidence and source-index rows are read as the FIRST message on their key, so a\nlater write on the same key by a holder of the issuer's bucket-wide row is inert to every\nresolver; only the attempt row advances, by CAS. The issuer also writes the\n**accepted row** (`cotal_accepted_<space>`, keyed by a token the launching party chose) naming the\nreference, create-only. A client learns which generation it was bound under by reading that one\nrow over a per-key `DIRECT.GET` grant its ceiling carries; it never trusts what it proposed or\nwhat a file says, and it refuses a row naming another owner, actor or lifecycle.\n\n**Renewal.** A renewal of an issued credential keeps its generation only when the ceiling being\nminted is byte-identical (RFC 8785) to the recorded evidence; a changed ceiling is refused as a\nrenewal and is a fresh issuance on a fresh generation, which the client adopts only through a\nnew connection. Refreshing a credential file never switches the generation of an already\nconnected transport.\n\n**Resolution.** A host that admits an effect under an issued authority resolves it: the\nevidence exists, the attempt row is `active`, the evidence is unexpired, every source is live,\nand a second read of the attempt row returns the same revision. Any other outcome refuses. The\none source shape this revision issues against is a static incarnation's credential ledger family\n(`cred.<lifecycleUid>` on `cotal_auth_<space>`), whose liveness is its issuance gate not being\n`retired`; a lifecycle terminal retires every issuance indexed to that family\n(`bysource.v1.\u2026`), so a retired incarnation's generations refuse to resolve afterwards.\n\n**User-auth issuance.** On a user-auth space the issuer of an interactive actor's `manager-caller`\nview connection is the auth service, at its callout, and the material is the user JWT the callout\nreturns. The callout issues that view when the bearer's actor-ledger row is an interactive row, and\nthe issued view carries the per-key accepted-row read beside its instance-pinned rows. It chooses\nthe generation, persists evidence whose permissions are the set it signs and whose one source is\nthat row, `{ space, bucket: \"cotal_actors_<space>\", key: \"actor.<owner>.<actor>.<lifecycleUid>\" }`,\nreleases it, and writes the accepted row, all before it returns the JWT. The accepted token is the\nfirst 32 lowercase hex characters of SHA-256 over `\"cotal.accepted.v1\\0\"` followed by the\nconnection's inbox nonce: the client chose the nonce and derives the token from it, and no token is\nread from a request body. The source is live while the auth service's actor ledger holds a row for\nthat owner and actor carrying that lifecycle UID; a revoked row, or a re-grant under another UID, is\na dead source at the next resolution. Only the auth service attests this shape; every other host\nrefuses it as a coordinate it cannot attest. A reconnect under the same nonce finds the existing\naccepted row. When the row names the same triple and the ceiling being minted is byte-identical to\nthe recorded evidence, the callout renews that generation; otherwise it refuses the connect, and the\nclient adopts a fresh generation only through a new connection under a new nonce. A managed row's\nview, the `agent` profile and every other view keep the legacy rail.\n\n**Compatibility.** A command whose semantics require the binding (this revision: `run-start`,\n\xA714.8) MUST refuse a legacy-rail request with `permission-denied` carrying the detail kind\n`ai.cotal.ep.unbound-caller-authority` naming the caller triple, never route it through the\nhost's own authority. Every other command serves both rails unchanged. Origin (that a request on\na generation-pinned subject was published by the grant holder) is a property of the grant set,\nnot of this section: no peer-held profile pairs a write with a raw stream read on one stream, and\nmediated reads remain the remedy.\n\n### 13.16 Delegated user intent\n\nA host platform that runs a `platform-control` service view MAY let that view's manager (the\nholder) execute one launch or one retirement that a signed-in user asked for, while the intent and\nthe resulting agent stay the user's. This subsection adds no exchange view, profile, holder grant or\nstanding delegation, and changes no other clause. A host that does not implement the\n`platform-control` service view, or holds no intent store, MUST refuse both requests below as\n`unimplemented`, and stock dispatch MUST refuse both kinds as `unimplemented`.\n\n**Admission.** A user admits an intent with one closed `delegated-user-intent` request on the host's\nauthenticated human route, the transport the `manager-service` typed requests use. The host MUST\nverify the user's IdP token, derive the owner from the verified subject as it does for a signed-in\nhuman, and read the named actor's ledger row fresh; the row MUST carry `spawn`. The host MUST NOT\nstore, forward or record the token, and MUST NOT read, require, synthesize or write `supervise`. The\nrequest carries the space, the assigned account public key, the user's actor, one platform control\ninstance id, a request id, and one operation: `launch` with one managed-agent enrollment target\nminus its token digest, or `retire` with one `{ owner, actor, lifecycleUid }`. An unknown field,\nincluding an owner, IdP token, scope, serve epoch or token digest, MUST be refused as `bad-request`\nwith no effect. For a launch, the host MUST read the account's platform-control assignment and that\ninstance's manager gate fresh and refuse unless the assignment is `assigned` for this account and\nnames that instance and the gate is open under the platform serve principal, and the requested scope and channel lists MUST lie within\nthe user's actor row under the managed-agent envelope rule. For a retirement, the target owner MUST\nequal the derived owner, and the target lifecycle MUST be one that the host's own record shows a\ndelegated launch on that instance produced and enrolled, for a launch target whose actor equals the\nretirement target's actor; the host MUST compare the launch's target actor, never the user actor\nthat admitted the launch. Any other lifecycle MUST be refused. The host generates\nthe intent id from at least 128 bits of entropy, never from caller input. It binds the account, the\ninstance id, the assignment's lifecycle UID and revision, the gate's process epoch (null for a\nretirement whose launching holder is gone), the one target, the user's principal `<owner>.<actor>`\nas parent, and an expiry at most 300 seconds ahead, and creates the record create-only.\n\n**Execution.** The holder executes an intent with one closed\n`manager-delegated-user-intent-execution` request on the host platform's own route for that holder;\nthe `platform-control` envelope does not carry this kind and refuses it as an unknown kind. The\nrequest names the intent id, the space, the fixed `cli` actor constant that keys the registration\nproof, the account, the assignment revision, the instance id, the manager lifecycle UID, the serve\nepoch, the registration proof, the identities, and one target: the launch target's actor with the\nSHA-256 digest of an actor token the holder generated, or the retirement's `{ owner, actor,\nlifecycleUid }`. The host MUST read the record fresh and refuse as `failed-precondition` an absent\nrecord, an admitted record past its expiry, and a consumed record unless the request is a retry of\nthe execution that consumed it (below). It MUST refuse as `permission-denied` any difference from\nthe record in account, instance id, manager lifecycle UID, assignment revision, operation, serve\nepoch or target. It MUST re-read the assignment and refuse as `permission-denied` one that is\nabsent, revoked, or differs from the record in space, account, instance id, manager lifecycle UID or\nassignment revision. It MUST re-read the gate, refuse a gate whose principal is not the platform\nserve principal, refuse a gate epoch other than the request's as `conflict`, and require the\nhost-keyed current registration proof. Every check completes before any effect. The host then MUST\nCAS the record from `admitted` to `consumed` at the revision it read, and that same write MUST pin\nthe execution: the request id, the serve epoch, the lifecycle UID (host-selected before the CAS for\na launch, the target's for a retirement), the launch's token digest or the retirement's\noperation id, and the host incarnation `{ instanceId, processEpoch }` that executes it. A lost CAS is `conflict` and nothing is enrolled or retired. Because the reads are not\nfences (\xA713.1), the host MUST repeat the assignment and gate checks for a launch after the CAS and\nbefore any effect, and on a refusal MUST compensate the launch (below) before it ends the record\n`aborted`; a change that lands after that second read is ordered after the execution. An intent\nexecutes at most once and confers nothing after it executes.\n\n**Recovery.** From the CAS on, the host owns the pinned execution, whoever presented it. It MUST\ndrive every consumed record to one outcome, `enrolled`, `retired` or `aborted`, at the pinned\nlifecycle UID, including after a restart or a lost answer. For a launch, the host's first effect\nafter the post-CAS checks MUST be the issuance activation of the alias at the pinned lifecycle UID\n(\xA713.1), before any ledger row or durable, so that UID has an active head and an open issuance gate\nbefore anything is granted under it. Every launch that ends without `enrolled` after its consuming\nCAS MUST be compensated before it is marked `aborted`, whichever flight observed the refusal,\nbecause a flight that resumes the execution cannot tell whether an earlier flight began the\nactivation: the retirement sequence below at that UID, with that UID's activation completed or\nadopted immediately before the terminal barrier. Before that activation the compensator MUST read\nthe head and the issuance gate at that UID. Once a retirement there has begun, because the head is\nretiring or retired at that UID or the gate is frozen or retired by `managedRetirementOpId` of that\nUID, the compensator MUST NOT run or adopt an activation and MUST go to the terminal barrier, which\nresumes that operation from its durable intent.\nOnly the barrier's answer that the lifecycle is retired at that UID is terminal confirmation; a\nnot-started answer MUST NOT be read as one. When that activation is refused because the alias is\nactive or retiring at another UID, the record MUST keep no outcome and the compensation MUST be\nretried. A request\nwhose request id and serve epoch, and a launch's token digest, equal the pin is a retry of that\nexecution: it passes the same checks except the consumed state, writes no second CAS, and MUST\nreceive that execution's answer. The alias stays held until the record has an outcome, and after a\nsweeper's claim until the release below.\nThe host MUST run each execution in one in-process flight keyed by the intent id, and a retry MUST\njoin that flight or read the record's outcome; a retry MUST NOT run the post-CAS checks, the\nenrollment writer or the retirement sequence itself. Every record write after the consuming CAS\nMUST be a revision-pinned CAS, and a flight MUST answer only from an outcome its own write set or\nfrom the outcome it reads after that write lost, never with material it did not commit. Recovery\nfollows the executor and sweeper roles of \xA713.7. Only the pinned incarnation is the executor, and\nonly the executor MAY run the enrollment writer for the record. Any other incarnation, including\nthe same instance after a restart advanced its process epoch, is a sweeper. A sweeper MAY act only\non a consumed record with no outcome whose executor it believes gone, because that instance's\nserving issuance gate is absent, not open or at another process epoch. It MUST first claim the\nrecord with a revision-pinned CAS that names its own incarnation and changes nothing else, and\nMAY then take only the terminal edge that removes authority: the compensation above, then\n`aborted`, for a launch, or the retirement sequence below, then `retired`, for a retirement. The\nsequence's terminal barrier freezes the issuance gate at that UID before it retires the lifecycle\n(\xA713.1), so an executor that a wrong belief left running can mint nothing there and cannot set the\noutcome. A consumed record holds its target alias `(owner, actor)` from the consuming CAS, and an\noutcome its executor writes releases it. After a sweeper's claim the alias MUST stay held after the\noutcome until the executor's own flight, having stopped before any further effect and revoked any\ngrant at the pinned UID, records the release, or until an operator releases it by hand; no door\nreleases it. Before each effect and before its outcome write, the executor MUST re-read the record\nand stop on a claim it did not write. While an alias is held, the host MUST refuse a launch\nadmission for it and MUST refuse, from either enrollment door, any enrollment of it other than the\nholding execution's own, as `failed-precondition` with no write.\n\n**Ownership.** A delegated launch MUST be enrolled under the record's owner with the record's\nparent, through the same writer, managed-agent envelope walk, lifecycle-keyed durables and\nmembership the host uses for that user's own managed-agent enrollment, with the host selecting the\nlifecycle UID. It MUST NOT be enrolled under a platform owner token or any owner other than the\nrecord's, and the manager MUST refuse material naming another owner. The holder is not on the\nagent's delegation chain and gains no ledger row, scope or grant from the launch.\n\n**Retirement.** A delegated retirement runs in order: revoke the managed grant at the target\nlifecycle UID only and complete the resumable release with that UID unchanged; close the provider\nhandle the host's runtime record holds for that UID, holding the alias while that record is\n`create-unknown`; run the auth-owned terminal barrier with `managedRetirementOpId(lifecycleUid)`\nthrough the same operation the host's managed retirement door runs; free the alias only after\nterminal confirmation. The launching holder is gone when its assignment is absent, revoked or at\nanother revision, its gate is not open, or its gate epoch is not the launch's. A retirement admitted\nwhile the launching holder is gone is bound to no live epoch, and the host MUST execute it itself\nthrough the same sequence; a retirement bound to a holder that is gone before it executes expires\nunexecuted. Once a holder's execution has consumed a record, the host MUST finish the sequence\nwhether or not the holder remains. A failed or uncertain step keeps the alias held, and a retry is\nthe same operation.\n\n**What stays.** Under the `platform-control` view itself the holder still enrolls, retires,\nvalidates and authorizes only same-owner descendants, and a `u_` principal's spawn request or admin\nauthorization against a platform manager is refused as before. A spawn the holder starts without a\nconsumed intent is not delegated and gains nothing from this subsection. A delegated agent is not\npreserved across a holder restart and is never restarted, because a restart would re-present a\nconsumed intent.\n\n### 13.17 Managed lifecycle handoff\n\nThis section is additive. It covers one case: a managed\nagent already enrolled through the \xA713.1 managed-agent enrollment operation, whose child runs where\nthe enrolling manager's filesystem is not visible (a sandbox, a container, another host).\n\n**One enrollment.** The child MUST NOT request enrollment, agent provisioning, or an enrollment\nredeem, and MUST NOT mint an actor token or a lifecycle UID. It presents the lifecycle UID the host\nselected at enrollment. A launch that needs any other UID or token is a new enrollment, not a\nhandoff.\n\n**Custody.** The raw actor token stays in the custody of the manager that generated it until that\nmanager releases it to the lifecycle's own child, and only to that child. The manager MUST NOT send\nit to the host or to any party other than the runtime transport that delivers it into that child,\nand the host's ledger keeps only its SHA-256 digest. The manager MUST NOT copy, link, or name any\nfile from its own workspace, secret store, launch material, or temporary directory into the child.\n\n**The handoff.** The manager releases one closed handoff document, `kind`\n`cotal-managed-handoff/v1`, carrying by value: `space`, `owner`, `actor`, `lifecycleUid`, `server`,\n`tlsRequired`, `authProvider`, `idp { url, issuer, audience }`, `exchangeUrl` (the enrollment's pinned\nexchange base), `sentinelCreds`, `actorToken`, `subscribe`, `allowSubscribe`, `allowPublish`, and an\noptional `policy { events: \"required\" }`. It MUST NOT carry a signing seed or key, an issuer or\ncallout record, the auth service's loopback capability, the owner-derivation secret, a provisioner,\ndeprovisioner, delivery, membership, supervisor, or other manager credential, a control token, or a\npath on the manager's filesystem. A reader MUST refuse an unknown field. The runtime delivers the\ndocument into the child as one private (0600) file named by `COTAL_MANAGED_HANDOFF_FILE`, never in\nargv or in an inherited environment value. The child's entry point MUST read the file into memory,\nremove it, and drop the variable before it does anything else, including parsing or refusing its\nown arguments, printing help, loading extensions, or refusing an unsupported runtime version, so\nevery outcome leaves no file. It MUST NOT forward the variable or the file into any process it starts.\n\n**Refusal before any plane.** The runtime passes the expected `space`, `owner`, `actor`, and\n`lifecycleUid` beside the file. The child MUST refuse, before any broker connection and before any\nexchange request, when the handoff's values differ from them or the document is malformed. A\nrefusal MUST NOT echo the document's contents.\n\n**Launch choices.** The manager MUST refuse, before enrollment, a spawn choice that only its own host\ncan honour, such as resuming a session held on that host, a working directory on its filesystem, or\na tool server it runs. Such a choice is never dropped silently.\n\n**Exchange.** The child obtains bearers only through the existing pinned HTTPS agent-bearer exchange\nat `exchangeUrl`, presenting the raw actor token. The service matches its SHA-256 digest against the\nledger as for any managed agent. Nothing about the exchange changes.\n\n**Readiness.** Readiness is observed from mesh presence of the exact principal and incarnation, as\nfor any managed launch. A runtime create whose acknowledgement is lost or ambiguous MUST leave the\nlaunch held and reported as uncertain. It MUST NOT be reported as exited without an observed exit or\nclose, and MUST NOT be retried into a second create, enrollment, or handoff for that lifecycle. A\nprovider answer that no resource exists is not an observed exit or close. A lifecycle is handed off\nat most once.\n\n**Fenced close.** The child's runtime resource is keyed by lifecycle: `cotal-` followed by the first\n32 lowercase hex characters of the SHA-256 of the UTF-8 bytes of the compact JSON array\n`[\"<space>\",\"<owner>\",\"<actor>\",\"<lifecycleUid>\"]`, with no whitespace. For space `s2420`, owner\n`u_aaaaaaaaaaaaaaaaaaaaaaaaaa`, actor `probe` and lifecycle UID `aaaaaaaaaaaaaaaaaaaaaaaaaa` the key is\n`cotal-ffa44aae523faeee4ab7689a699b392e`. A close by that key completes only when no create for that\nlifecycle can still materialize: the create was answered before the close, or the close fences the\nkey so a later create is refused. Until then the close stays pending and the launch is not exited.\nA runtime MAY issue the create as a durable provider operation keyed by that key and close the\nresource through the identifier the provider returned in its authenticated response to that create,\nkept in a durable record the host can read without the enrolling manager. Only that response binds\nan identifier to the key: an identifier derived from the key, or found by name or by listing\nresources, MUST NOT be closed or adopted as the lifecycle's resource. While the create's response is\nunknown, no identifier is bound, the launch stays held as under Readiness, and a close completes only\nas above.\n\n**Retirement.** A handed-off lifecycle retires only through the existing managed path, in this order:\nthe host-owned prepare-retirement for the UID-exact target with the operation id\n`managedRetirementOpId(lifecycleUid)`; the fenced close of the child's runtime resource through the\nhandle known for that lifecycle; then the auth-owned terminal barrier with the same operation id.\nAfter the enrolling manager is gone, the host runs the same three steps itself, ending at the managed\nretirement door. There is no participant stop kind and no second retirement protocol, and no runtime\nclose or adopt may be keyed on the agent name alone. A runtime MAY host a handed-off child only where\nthe host can perform the fenced close by lifecycle without the enrolling manager. A failed or\nuncertain step keeps the alias held. A manager preservation cut that holds a handed-off lifecycle is\nrefused before any child stops, because a later manager never resumes it, and a manager stop after\na refused cut retires that lifecycle through these steps.\n\n**Owner form.** A handoff serves whatever owner the enrollment returned. It neither requires nor\nexcludes any owner form.\n\n---\n\n## 14. Workflow runs (v0.5)\n\nA **workflow run** is one execution of a program in the Cotal workflow language, hosted by a\n**driver** (an endpoint, in the reference deployment the manager daemon) that performs the\nprogram's effects against the mesh and records every one of them in a per-run **step journal**.\nThis section defines the run's wire footprint: the record it is described by, the stream its\njournal travels on, the records its effects file, and the grants its driver holds. The\nlanguage, the journal entry, and the rules of resume, migration and fork are defined in\n[`spec/cotal-lang.md`](spec/cotal-lang.md), which this section incorporates by reference: an\nimplementation of this section MUST implement that document.\n\n### 14.1 Roles and identity\n\nThe **driver** is the one principal that executes a run: it validates and runs the program, calls\nthe effect handler, appends to the journal, and writes the run's records. It is hosted by an\nendpoint, and every \xA714 key leads with that `<endpoint>` token so a per-endpoint enumeration and a\nretirement drain (\xA713.1) both work by prefix. A **run id** (`<runId>`, an id token, \xA713.2) is minted\nby the driver when the run starts, is never caller-supplied, and is **never reused**: re-running a\nprogram from part of a run's history is a **fork**, and a fork is a new run under a new id whose\nrecord names its parent (\xA714.3). A run has exactly one **authoritative appender** at a time; \xA714.4\nis what makes that true.\n\nA user-auth run's durable actions MUST use the owner established by its authenticated admission.\nThe trusted host derives the run-stable actor and lifecycle uid from the run id and retains that\nowner on resume. Grant construction and effect dispatch MUST use the same triple. A supplied\nowner token is not admission evidence. The existing static/local path retains its `local` owner.\nThese identity rules do not authorize exporting host mediator or operator credentials to a driver.\n\n### 14.2 The language and its version\n\nPrograms, values, primitives, the step key grammar, the input hash, the request id and the entry\nschema are those of [`spec/cotal-lang.md`](spec/cotal-lang.md). The language carries a\n**`languageVersion`**, bumped when a revision changes what a program means (its PRNG, a builtin,\nnumeric behaviour, walker scheduling) and deliberately not the package or wire version; a run pins\nthe version it started under (\xA714.3) and a resume under another version is refused\n(`spec/cotal-lang.md` \xA78.4). A wire revision of this document therefore never invalidates an open\nrun, and a language revision never requires one here.\n\n### 14.3 The run record\n\nA run is described by the `run` record kind (\xA713.7): `run.<endpoint>.<runId>`, `.spec`/`.status`\nsplit, mediated, written by the driver's commit path only.\n\n- **Spec** (create-only, decided once): `{ v: 1, run, pins, createdAt, forkedFrom? }`. `pins` is\n  the **resolved pin set** the run started under, `{ seed, startedAt, yieldEvery, stepBudget,\n  effectCeiling, languageVersion }` (`spec/cotal-lang.md` \xA78.3): every one selects which effects run,\n  so a resume MUST read them back and bind to them, and MUST refuse a caller value that differs.\n  `startedAt` is the run's **logical epoch**, and a resuming host's own clock never moves a\n  replayed program. The RESOLVED value is pinned, never the default: a default is a property of the\n  interpreter, and the interpreter is the thing that may have changed between attempts. A spec that\n  already exists MUST refuse a second start under the same id. A fork (`spec/cotal-lang.md` \xA711.3)\n  is a new run with its own id and its own spec, and the child's spec names its lineage:\n  `forkedFrom` is `{ run, step }`, the parent run and the step key the cut excluded, written with\n  the spec and absent on a run started fresh. Absence reads as \"lineage unknown\" (a child recorded\n  before the field existed), never as \"not a fork\". A later revision that adds a field to the spec\n  half does so as its own binding revision, never by rewriting a spec that exists.\n- **Status** (last-value-wins, CAS-written): `{ v: 1, observedSpecRevision, state, holder, epoch,\n  fencingToken, journalHigh, at }`. `state` is one of `running`, `released`, `completed`, `failed`,\n  and `released` and `failed` are different facts: a failed program has a result and the journal has\n  it, a released run has none, because its driver stopped holding it (`spec/cotal-lang.md` \xA79.2,\n  L5012). `holder`, `epoch` and `fencingToken` name the driver that holds the run and the lease\n  (\xA713.6 work pool) it holds it under. `journalHigh` is the highest journal ordinal (\xA714.4) the run\n  is KNOWN to have reached, written at each activation and after each append the driver makes\n  while the run is `running`, before that append resolves to the interpreter: it is the one anchor\n  OUTSIDE the journal, so a replay whose last ordinal is below it has lost records from the\n  journal's tail, which nothing inside the journal can see, and the driver MUST refuse to resume it.\n  Interior loss is the journal's own ordinal chain's.\n\n### 14.4 The step journal on the wire\n\nThe journal of a run is carried by the per-space **`WFJ_<space>` stream** (\xA713.12) on **one subject\nper run**, `cotal.<space>.wfj.<runId>`. An implementation MUST create the stream with limits\nretention, file storage, no `max_age`, and `allow_direct=false`, and MUST NOT let any removal cause\nevict a live run's prefix (\xA713.12 retention floor). Retirement of a run's journal is by subject\npurge.\n\nEvery message on the subject is one **journal record**, JSON, one of two kinds. Both envelopes are\nCLOSED: a reader MUST refuse a record that carries a field outside the shape below, and MUST refuse\nan unknown `kind`, because a journal is replayed by whoever holds the run next and a field one\nwriter meant and another ignores is a divergence nothing would name:\n\n- **activation**: `{ v: 1, kind: \"activation\", run, n, holder, fencingToken, epoch, replayedTo, at }`,\n  the successor's first act, and the only record the runtime layer writes that is not a step.\n- **step**: `{ v: 1, kind: \"step\", run, n, at, entry }`, where `entry` is a language journal entry\n  (`spec/cotal-lang.md` \xA710.1) carried verbatim: the wire layer MUST NOT read inside it. A step is\n  appended TWICE, once `pending` before its effect is dispatched and once settled after; a reader\n  folds by the entry's key and the last record wins.\n\n`n` is the record's **ordinal** in the run's journal, from 0, and a replay MUST require\n`records[i].n === i`: the chain is the only check that sees a record removed from the middle of a\nsubject, since counting cannot and no anchor at the front can. A writer MUST stamp `run` with the run\nthe subject names; its grant covers exactly one subject (\xA714.6), which is what enforces it. A reader\nSHOULD refuse a record whose `run` names another run; the reference reader relies on the grant and\ndoes not re-check it.\n\n**The activation barrier.** A run has exactly one authoritative appender at a time, and the STREAM\nis the acceptor: every append MUST carry `Nats-Expected-Last-Subject-Sequence` for the run's own\nsubject, so a publish lands only if the subject is exactly where the publisher believed it was, and\nthere is no read-then-publish window because there is no read. Takeover is replay-then-activate:\n\n1. The successor replays the run subject from the beginning, through a **per-takeover replay\n   durable** it creates on the stream (`wfj_<runId>_<takeoverId>`, filtered to the run's subject,\n   explicit ack, deliver-all) and deletes when done. `<takeoverId>` is an id token (\xA713.2) minted by\n   whoever hands the driver its lease and its journal grant (\xA714.6), one per takeover of a run and\n   never reused for that run; the driver does not choose it, because a consumer name is one subject\n   token that no grant pattern covers in part, so it has to be known when the grant is minted. The\n   last replayed record's stream sequence is the only authoritative head there is (`STREAM.INFO`'s\n   `last_seq` is stream-wide, and its subject filter answers counts, not sequences).\n2. Its first act is an **activation record** appended at that expected sequence, and it drives\n   nothing before that record lands. Its authority is checked against the activation the journal\n   already holds: a lower `fencingToken` is refused (stale lease); an equal token is refused unless\n   `holder` AND `epoch` are the same (one process picking its own run back up); a higher token\n   activates.\n3. Once the activation lands the subject has advanced, so any append still in flight from the\n   superseded driver carries a stale expectation and the server rejects it.\n\nTwo CAS refusals are two different states and MUST NOT be conflated. A refused ACTIVATION means \"my\nreplay is stale\": the successor has driven nothing, the records that beat it are more prefix, and it\nMAY re-replay and activate again while it still holds the lease. A refused APPEND after an\nactivation that won means \"someone else activated\": that driver IS superseded, MUST stop, and MUST\nNOT refresh the sequence and retry, because a retry at the new head is the defect the barrier\nexists to prevent. A driver publishes one entry at a time from one serial queue per run and\nadvances its head only from each acknowledgement; once the bytes have gone out, any outcome without\none poisons the queue and nothing behind it reaches the wire (a record refused before it is sent,\nfor example one that cannot be serialized, fails only itself).\n\nThe journal is a language artifact, and its contents are decided by the language: a driver MUST\nawait the durable append of a `pending` entry before dispatching the effect it names, MUST settle\nthe entry from the handler's outcome, and MUST keep the settling append outside the handler's\nfailure domain, so a refused append is a durability failure (L5010) that stops the run and is never\nrecorded as the effect's failure (`spec/cotal-lang.md` \xA710.5). A cancelling scope's `cancel.issued`\nrecords whether the driver has discharged the intent against the world; the record states the\nintent and its discharge, and how a driver disposes of a losing arm's live work is a driver policy\nthis revision does not fix.\n\n### 14.5 Answers, notices, migrations\n\nThree record kinds carry the payloads a run's effects file (\xA713.7 for the grammar and the\nsentences that defend each shape). Their derived id tokens all take one form: **the unpadded\nbase64url of the SHA-256 over the strict RFC 8785 canonical JSON of the named object, 43\ncharacters**, which is an id token by construction. The reference implementation's canonicalizer is the one\n\xA713.7's `*Digest` fields use.\n\n- **`answer`**, `answer.<endpoint>.<token>.<answerId>`, atomic, create-only: `{ v: 1, token,\n  answerId, value?, artifact?, by, at }`, filed BEFORE the checkpoint token is presented; the\n  one-use settle fact (\xA713.6) then NAMES the id it accepted. For a checkpoint a run performed the\n  `answerId` on a `resumed` settle is REQUIRED (\xA713.6 leaves it optional for other checkpoints): a\n  run's handler reads the answer under the id the settle names, never by looking for \"the answer to\n  this token\", and refuses a resumed settle that names none. `answerId` = the digest id of\n  `{ token, by, value: value ?? null, artifact: artifact ?? null }`, so a retry of the same answer\n  lands on the same key with the same bytes and two different answers race on the settle, which is\n  what the settle is for. `by` is the answerer as the run's own authorization knows them, never the\n  presenting principal (the driver, for every answer) and never a field in the answer request. A\n  baseline managed seat reaches the answer door only through the self-targeted row above, after the\n  manager has matched its exact caller incarnation to the pending relay for this open pause.\n  An **amendment** is an answer filed after the pause settled: same key grammar under the token\n  the pause settled under, with `supersedes` naming the `answerId` the settle accepted. It is filed\n  through the same door and credential pinning as an answer, and nothing is presented, so the pause\n  stays settled, the one-use settle is untouched, and the run never reads the record. Its\n  `answerId` is minted fresh for each filing (32 random bytes, base64url, the first 43 characters)\n  and is never derived from its content: a participant who returns to an earlier position files\n  what an earlier filing said, and a content id would make the create-only write take it for a\n  retry of that filing and record nothing. A step that is still open, or that settled\n  without accepting an answer, has nothing to amend and is refused. The run surface lists a settled\n  step's amendments beside its accepted answer in the order the records bucket committed them (each\n  record's revision); `at` is the filer's clock and never decides the order. The last one listed is\n  the step's current recorded position, and the accepted answer remains what the program acted on.\n- A held `once` step (`spec/cotal-lang.md` \xA77.8) is answered like a checkpoint, addressed by its\n  step key; the driver presents the hold id (`spec/cotal-lang.md` \xA77.8) as the token, whatever kind\n  the step is, and reads the step's accepted answer and amendments under the same id once it\n  settles. The run's pause authority covers that id only while the step is pending with its hold\n  bound.\n- **`notice`**, `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>`, split: spec `{ v: 1, run,\n  step, addressee, fact, at }` (create-only; `fact` is the language's bounded decision record and\n  is checked against its bound BEFORE any record is written), status `{ v: 1, consumedAt, by,\n  observedSpecRevision }` (create-only: the consumption is established once, by the turn that\n  carried it). `addresseeId` = the digest id of `{ agent }` (the addressee's name); `noticeId` = the\n  digest id of `{ requestId, addressee }`, where `requestId` is the `notify` step's request id, so\n  one call to N agents files N notices and a re-run after a crash lands on the same ones. A driver\n  that performs the addressee's turns MUST render an unconsumed notice ahead of its next turn and\n  MUST NOT deliver it as a channel message. The reference driver performs that rendering: its turn\n  plane is durable (`spec/cotal-lang.md` \xA76.5), and a relayed turn carries the addressee's\n  unconsumed notices as its rendered context and marks them consumed with the turn's outcome.\n- **`migration`**, `migration.<endpoint>.<runId>.<migrationId>`, split: spec `{ v: 1, run,\n  fromHash?, toHash, at, consumedThrough, orphans[], overrides[], actor }` (create-only), status\n  `{ v: 1, appliedAt, by, observedSpecRevision }` (create-only). `migrationId` = the digest id of the\n  spec without `at`, so a dry walk re-run after a crash files no second migration for one decision.\n  `orphans[]` is `{ step, kind, verdict, code? }` per journal entry the new source no longer reaches,\n  with the verdicts and refusals of `spec/cotal-lang.md` \xA711.2; `fromHash` is the caller's claim\n  and is absent when not supplied, because the run record carries no program hash to verify it\n  against. A migration never rewrites a journal.\n\n### 14.6 Driver grants\n\nGrants are DERIVED (\xA713.7, \xA713.9), and a run driver's are minted **per run and per takeover\nattempt**, never per space:\n\n- publish on exactly `cotal.<space>.wfj.<runId>`;\n- create, bind (info, next, ack) and **delete** its own replay durable `wfj_<runId>_<takeoverId>`\n  on `WFJ_<space>`, named per takeover because a durable remembers how far it delivered and a\n  successor needs the prefix from the top, and because a consumer name is one subject token that no\n  pattern covers in part, so the takeover id belongs to the credential;\n- and, as the standing per-kind mediated writer path of \xA713.9 rather than anything minted per run,\n  the commit path for the `run`, `answer`, `notice` and `migration` keys of its own endpoint.\n\nThere is no wildcard form of any of these, on purpose: a space-wide `wfj.>` publish would let one\nrun's driver append to another run's journal, which is not a read leak but a corruption (the other\nrun would replay a step it never took), and the barrier's premise is exactly one authoritative\nappender per subject. The provisioner holds `STREAM.CREATE`/`STREAM.INFO` on `WFJ_<space>` and\ncreates it at space setup; agents never hold `STREAM.CREATE` (\xA713.12).\n\n### 14.7 Conformance (workflow runs)\n\nA conformant driver (v0.5) MUST:\n\n1. Validate a program against `spec/cotal-lang.md` before running it, and run it with the language\n   semantics that document defines, under a pin set resolved once and read back on every resume.\n2. Mint run ids itself and never reuse one; a fork is a new run under a new id.\n3. Append every journal record on the run's own subject under the subject-sequence fence, replay\n   before activating, activate under an authorized lease tuple, stop on a refused append after\n   activation, and never retry an append at a refreshed head.\n4. Write a `pending` entry durably before dispatching its effect, settle from the handler's outcome,\n   and treat a refused append as a durability failure that stops the run rather than as the effect's\n   outcome.\n5. Require the ordinal chain and the run id on replay, refuse a replay below the recorded\n   `journalHigh`, and refuse to resume without the recorded pins or under a different language\n   version.\n6. File answers, notices and migrations under their derived ids, create-only, and render notices\n   ahead of the addressee's next turn rather than as channel messages.\n7. Hold only the per-run, per-takeover grant family of \xA714.6.\n8. Admit every run under \xA714.8 before launching it, check every channel effect against the\n   admitted ceiling and the current revocation state, and never continue a run whose admission is\n   missing, unreadable, mismatched or revoked.\n\n### 14.8 Run admission\n\nA hosted run performs channel effects on a caller's behalf. What it may do in channels is the\n**admitted ceiling**: the caller's issued permission ceiling (\xA713.15) as resolved at admission,\nrecorded once per run, and never widened afterwards.\n\n**The record.** Before the driver is launched and before a successful start reply, the hosting\nendpoint writes `admission.v1.<endpoint>.<runId>` in `cotal_admission_<space>`, create-only,\nunder a one-shot `run-admitter` credential pinned to that one run:\n`{ version: 1, space, endpoint, runId, instanceId, caller, ceiling, provenance, admittedAt }`.\nThe store is write-once per key at the broker (\xA713.12: one message per subject under `discard:\nnew`, no rollup header, no message delete, no purge), so the admitter's own key row can neither\nreplace the admission nor remove it once written, and a marker, once written, stays.\n`caller` is the admitting request's broker-authenticated caller, generation included; `ceiling`\nis the resolved evidence's `permissions`, verbatim; `provenance` is\n`{ kind: \"issued\", ref, resolvedRevision }` for a hosted admission or\n`{ kind: \"operator\", by, reason }` for a local one (below). A run-start arriving on the legacy\nrail is refused as \xA713.15 says. On an open mesh, which issues no authority, the endpoint hosts no\nrun. The driver holds no row on this store; the mediator and operator profiles hold its leader-\nserved read only.\n\n**Enforcement.** The trusted host re-reads the admission, leader-served, before every channel\neffect: opening a wait, each fetch on it, each re-read of a recorded match, and a conclave's\nchannel writes. A concrete channel is checked against the ceiling with the \xA73 matcher: a\npublish requires `chat.<owner>.<actor>.<channel>` under the caller's own triple to be allowed by\n`ceiling.publish`; a read requires every subject `chat.*.*.<channel>` matches to be covered by\n`ceiling.subscribe`. Deny wins; an explicit `none` is deny-all; a generated channel name is\nchecked after it is derived and no wildcard is invented to admit it. `notify` writes agent-\naddressed notices and is not channel publication; spawn and turn keep their separately checked\ndelegated authority.\n\n**Revocation.** `revoked.v1.<endpoint>.<runId>` is the run's revocation marker: create-only,\nidempotent, written under the same `run-admitter` profile, never removed. A revoked run performs\nno further channel effect, its open waits refuse at their next fetch (the linearization point is\nthe leader-served read the host makes before returning any channel bytes), and no resume,\ntakeover or boot reconcile continues it. Revocation authorizes no new resource and no cleanup\nbeyond what the run's own journal already justifies. Caller disconnect or credential expiry after\nadmission does not revoke a run.\n\n**Resume, fork, local, restore.** A resume, takeover or reconcile continues under the ORIGINAL\nadmission and the current marker; the resuming caller's own authority is not consulted and cannot\nwiden it; a run with no admission stays parked, named in the host's log. A fork is a new run and\nneeds its own admission under the forking caller. A local drive (`cotal run start --local`) is\nadmitted from operator evidence named on the command line (the read and publish channel sets, or\n`none`), never from the host's own scope. The admission and revocation stores are retained with\nthe run, program and journal state they authorize; a restore that lacks them recreates them empty,\nand no run is taken back under authority the host cannot read.\n\n**User-auth runs.** A user-auth run is hosted by a signerless participant manager, and its issuing\nhost writes the admission. The issuing host admits a run-start whose caller has a derived user owner\nonly when that owner is the manager's registered owner, the owner whose `supervise` grant registered\nthe instance, so every user-admitted run on a participant manager belongs to that one owner. A\ncaller-requested resume and every principal answer or amendment ride the versioned rail. The manager\nforwards the request subject it served with the attempt or operator issuance it asks for, and the\nissuing host re-parses that subject, requires a user caller's owner to be the run's admitted owner\nfor a resume and the registered owner for an answer, resolves the caller's own issuance as live, and\nrequires its publish ceiling to permit that subject. The issuing host subscribes to those resume and\nanswer request subjects itself and never replies on them, and it issues for a forwarded subject only\nwhen it observed a caller publish that request and has not issued for it before, so a manager cannot\nforward a request its caller never sent. It reads what that request's envelope asked for and issues\nonly that: a resume attempt for the run its `runId` names, and an answering issuance for the\nendpoint the answer names, the manager's own when it names none, that amends when the request set\n`amend: true` and answers when it did not. When the request carries a `bind` (\xA713.2) naming\nanother instance or epoch than the manager's current registration, it issues nothing, since that\nmanager refuses the request unrun. It issues nothing either for a request whose `class` or pinned\n`inputDigest` and `outputDigest` differ from the command's declaration in the manager's registered\ncluster (\xA713.7), which that manager also refuses unrun. An answering operator issuance always carries\nthe served subject. An amendment's issuance marks its pause with `amend: true`, and the issuing host\nthen requires that pause settled `resumed` with an accepted answer instead of waiting. A legacy-rail\nanswer is accepted only from a\nmanaged seat of that owner whose actor-ledger row is live, on the relay path of \xA714.5. A boot\nreconcile forwards no subject and continues under the original admission. This revision hosts no\nuser-auth run on the signer-holding host's own manager.\n\n---\n\n## Appendix A: Reference implementation map\n\n| Spec section | Source |\n| --- | --- |\n| \xA72 Identity | `packages/core/src/identity.ts` |\n| \xA73 Subjects | `packages/core/src/subjects.ts` |\n| \xA75 Envelopes, \xA76 Presence, \xA77 Channels | `packages/core/src/types.ts` |\n| \xA78 Streams | `packages/core/src/streams.ts`, `packages/core/src/endpoint.ts` |\n| \xA79 Security | `packages/core/src/provision.ts` |\n| \xA710 Join link | `packages/core/src/link.ts` |\n| \xA713 Endpoint control surface | `packages/core/src/` (endpoint rails, envelope, contracts; lands with the control-surface campaign) |\n| \xA713.15 Issued authority | `packages/core/src/issued-authority.ts` (reference, evidence store, accepted row), `issuer-session.ts`, `endpoint-subjects.ts` / `endpoint-grants.ts` (the versioned rail) |\n| \xA714 Workflow runs, [`spec/cotal-lang.md`](spec/cotal-lang.md) | `packages/lang/src/` (the language, journal, keys, pins), `packages/core/src/run-record.ts`, `run-journal.ts`, `checkpoint-answer.ts`, `run-notice.ts`, `run-migration.ts`, `endpoint-binding.ts` (WFJ, grants), `run-admission.ts` (\xA714.8), `implementations/runtime/src/` (driver, migrate, fork), `implementations/manager/src/run-hosting.ts` (admission) |\n\n## Appendix B: Profile ACLs\n\nThis appendix is normative for the NATS binding. *(The operator-facing summary of these\ngrants is [docs/identity-and-auth.md](docs/identity-and-auth.md).)* Names below use these\nplaceholders:\n\n- `P = cotal.<space>`\n- `CHAT = CHAT_<space>`, `DM = DM_<space>`, `TASK = TASK_<space>`\n- `DLV = <Plane-3 per-member delivery stream>`; `INBOX = <mixed pre-auth fan-out stream>` (the durable-backstop handoff, \xA78): fan-out writes `INBOX` (`dinbox.<owner>.<actor>.<uid>`; lifecycle-bound from v0.4, so an inactive-gap or predecessor entry can never migrate to a same-name successor), the trusted reader re-authorizes and transfers to `DLV` (`dlv.<owner>.<actor>.<uid>`, same binding), and the agent binds its own `DLV` DELIVER consumer (filter pinned to its own triple). An agent gets **no** grant on `INBOX` (the mixed pre-auth store).\n- `KV = KV_cotal_presence_<space>`\n- `CHKV = KV_cotal_channels_<space>`; `DLVKV = <delivery lease/readiness KV>`\n- `MEMKV = KV_cotal_membership_<space>` (the derived channel-membership feed, \xA78)\n- `<owner>.<actor> = the authenticated principal` (\xA72): `<owner>` and `<actor>` are its two tokens; the dot-form is the wire/KV form, the dash-form `<owner>-<actor>` is the durable-name form\n- `connId = the authenticated connection id` (the connection nkey in static mode; the client-chosen nonce in user mode); distinct from the principal, and keys ONLY the reply inbox\n- `role = authenticated agent role`\n- `chatHistD = chathist_<owner>-<actor>-<uid>`, `dmD = dm_<owner>-<actor>-<uid>`, `dlvD = dlv_<owner>-<actor>-<uid>`, `svcD = svc_<role>` (per-instance durables are lifecycle-scoped from v0.4: keyed on the dash-form + lifecycle UID, \xA78/\xA713.1; `svcD` stays role-scoped)\n- `inbox = _INBOX_<connId>.>`\n\nGrouped placeholders such as `<CHAT|DM|TASK>` mean one concrete subject per listed token.\n\n### Agent\n\n`sub.allow`:\n\n- `inbox`\n- `P.live.<manager|delivery>.<owner>.<actor>.>` (replies to its own plane liveness probes, \xA76.1)\n- `P.ep.reply.*.*.*.<owner>.<actor>.<uid>.*` (exact arity; the agent's own endpoint reply rail: every endpoint's replies to THIS caller triple + nonce, \xA713.2; replies never ride the per-connection `inbox`)\n- `P.epe.\u2026`; the exact fully-qualified event subtrees of every minted read capability\n  (\xA713.9 event-read row), incl. the caller's own per-goal subtree\n  `P.epe.*.*.*.goal.<owner>.<actor>.<uid>.>`; the live tail of watch, granted per\n  capability, none by default\n- `P.chat.*.*.<ch>` for every `allowSubscribe` channel, the **live read boundary**: native core-sub join/leave is a `sub.allow`-bounded subscribe to this subject (wildcard sender owner+actor), so an agent whose ACL permits a channel joins it alone with no manager. Wildcards preserved (e.g. `P.chat.*.*.team.>` for `allowSubscribe: team.>`); a `team.>` grant matches strictly deeper channels, not the bare `team`; a `>` grant is read-all chat in the space on credential compromise\n\n`pub.allow`:\n\n- `P.chat.<owner>.<actor>.<ch>` for every `allowPublish` channel (post ACL; none by default)\n- `P.inst.*.*.<owner>.<actor>` (DM any recipient, forge-locked to me as sender)\n- `P.svc.*.<owner>.<actor>` (anycast any role, as me)\n- `P.live.<manager|delivery>.<owner>.<actor>` (plane liveness probe, as me, \xA76.1; the agent holds no `live` serve filter)\n- endpoint request forms per minted capability (\xA713.9): every agent gets the baseline set\n  (`describe` on all endpoints; the delivery endpoint's durable join/leave/list commands;\n  self-targeted manager commands with authz-mode `self`, including `run-answer`, which the manager\n  narrows to an ask or escalation pending on that exact seat incarnation); the `spawn` capability adds the\n  manager endpoint's lifecycle commands with authz-mode `owner`; `child`/`ledger` forms and\n  wider target patterns only per explicitly minted capability. The caller triple\n  `<owner>.<actor>.<uid>` is pinned in every granted form\n- control-surface durable reads (contract artifacts, decisions, goal results, receipts,\n  event catch-up, record reads): **NO raw JetStream read grant of any kind**, no\n  `DIRECT.GET`, no consumer `CREATE`, no bind-only `MSG.NEXT`/`ACK`, on `EPC`/`EPF`/`EPE`/the\n  records KV. Per \xA713.9 \"Mediated reads\", every JetStream read delivers stored bytes to a\n  caller-chosen destination the broker does not confine (push `deliver_subject`, pull\n  `MSG.NEXT` reply, `DIRECT.GET` reply are the same vector), so an untrusted caller holds none\n  of them. The caller reads through the trusted read mediator via a read command (an endpoint\n  request form, above) and receives its own caller-scoped facts over its reply rail\n  `P.ep.reply.*.*.*.<owner>.<actor>.<uid>.*` (already in `sub.allow`); the mediator owns the\n  reader consumers and re-authorizes each read. Live event progress is the caller's own core\n  subscription to granted `P.epe.\u2026` subtrees within `allowSubscribe` (bytes land only on its\n  own subscription, never a caller-chosen subject)\n- `$JS.API.INFO`\n- `$JS.API.STREAM.INFO.<CHAT|KV|CHKV|DLVKV>`: CHAT plus the world-readable presence/registry/lease KVs only; **not** DM/DLV/EPC (an agent reaches those by name \u2014 its own pre-created `dmD`/`dlvD`, or a subject-scoped `DIRECT.GET` on EPC \u2014 and `subjects_filter` is a request-body field, so INFO there would only leak inbox/delivery subject metadata). `TASK` rides the `role` gate below, not this row.\n- `$JS.API.CONSUMER.CREATE.<CHAT>.<chatHistD>.<P.chat.*.*.<ch>>` for every `allowSubscribe` channel (history reads; the single filter the server pins to the body, the agent's only CHAT consumer create. The live tail is the core `sub.allow` subscription above, not a JetStream consumer)\n- `$JS.API.CONSUMER.INFO.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.DELETE.<CHAT>.<chatHistD>`\n- `$JS.API.CONSUMER.INFO.<DM>.<dmD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DM>.<dmD>`\n- `$JS.ACK.<DM>.<dmD>.>` (DM inbox: BIND-ONLY its own pre-created `dmD`, never create)\n- `$JS.API.CONSUMER.INFO.<DLV>.<dlvD>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DLV>.<dlvD>`\n- `$JS.ACK.<DLV>.<dlvD>.>`, the **durable backstop**: BIND-ONLY its own pre-created per-member DELIVER consumer `dlvD` (the trusted reader's re-authorized handoff, \xA78). The agent holds NO grant on the mixed pre-auth `INBOX` fan-out stream.\n- `$JS.API.CONSUMER.CREATE.<KV>.>`\n- `$JS.API.CONSUMER.INFO.<KV>.>`\n- `$JS.FC.>`\n- `$KV.cotal_presence_<space>.<owner>.<actor>`\n- `$JS.API.STREAM.MSG.GET.<CHKV>`\n- `$JS.API.CONSUMER.CREATE.<CHKV>.>`\n- `$JS.API.CONSUMER.INFO.<CHKV>.>`\n- `$JS.API.STREAM.MSG.GET.<DLVKV>` (delivery lease/readiness; read-only, non-gating)\n- if `role` is set: `$JS.API.STREAM.INFO.<TASK>`, `$JS.API.CONSUMER.INFO.<TASK>.<svcD>`,\n  `$JS.API.CONSUMER.MSG.NEXT.<TASK>.<svcD>`, `$JS.ACK.<TASK>.<svcD>.>` (stream-level state is\n  gated with the bind grants, so a role-less agent holds nothing at all on `TASK`)\n\n`pub.deny` (the agent binds these consumers, never creates them; its only consumer-create grant is the pinned per-channel `chatHistD` history create):\n\n- `$JS.API.CONSUMER.CREATE.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.CREATE.<TASK>`\n- `$JS.API.CONSUMER.CREATE.<TASK>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<TASK>.>`\n- `$JS.API.CONSUMER.CREATE.<DLV>`\n- `$JS.API.CONSUMER.CREATE.<DLV>.>`\n- `$JS.API.CONSUMER.DURABLE.CREATE.<DLV>.>`\n\nA bare/multi-filter consumer create on `CHAT` is **not** explicitly denied (that would also deny the\npinned `chatHistD` create the agent needs), so it is default-denied (the agent holds no such allow),\nleaving the single-filter history consumer above as the agent's only CHAT consumer.\n\n### Observer\n\n`sub.allow`:\n\n- `P.chat.>`\n- `inbox`\n\nApplication publish is denied. `pub.allow` contains only read/control verbs needed to read\nCHAT history, presence, and channel registry:\n\n- `$JS.API.INFO`\n- `$JS.API.STREAM.INFO.<CHAT>`\n- `$JS.API.STREAM.INFO.<KV>`\n- `$JS.API.CONSUMER.CREATE.<CHAT>`\n- `$JS.API.CONSUMER.CREATE.<CHAT>.>`\n- `$JS.API.CONSUMER.INFO.<CHAT>.>`\n- `$JS.API.CONSUMER.MSG.NEXT.<CHAT>.>`\n- `$JS.ACK.<CHAT>.>`\n- `$JS.API.CONSUMER.CREATE.<KV>.>`\n- `$JS.API.CONSUMER.INFO.<KV>.>`\n- `$JS.API.STREAM.INFO.<CHKV>`\n- `$JS.API.STREAM.MSG.GET.<CHKV>`\n- `$JS.API.CONSUMER.CREATE.<CHKV>.>`\n- `$JS.API.CONSUMER.INFO.<CHKV>.>`\n- `$JS.API.STREAM.INFO.<MEMKV>`\n- `$JS.API.STREAM.MSG.GET.<MEMKV>`\n- `$JS.API.CONSUMER.CREATE.<MEMKV>.>`\n- `$JS.API.CONSUMER.INFO.<MEMKV>.>`\n- `$JS.API.STREAM.INFO.<DLVKV>`\n- `$JS.API.STREAM.MSG.GET.<DLVKV>`\n- `$JS.FC.>`\n\nThe membership feed (`MEMKV`) is read-only for this profile and, per \xA78's membership-feed\nparagraph, display-only and not part of the contract a client must implement.\n\nThe profile holds **no** `CONSUMER.DELETE` on any of these streams. Its consumers are client-named\nordered consumers (`oc_<nuid>_<serial>`, renamed on every rebuild), so the only expressible delete\ngrant is stream-wide, and a stream-wide grant lets one holder delete another principal's watch\ncursors and the delivery daemon's `fanout` durable. The broker removes these consumers at their\ninactive threshold (five minutes after the last interest), and a client MUST treat a refused delete\nof its own ephemeral consumer as that outcome rather than as a failure.\n\n### Admin\n\nAdmin has observer grants, with `sub.allow = [P.chat.>, P.inst.>, P.svc.>, inbox]`, the\ngod-view is the **messaging plane only**, enumerated: it deliberately excludes `P.ep.>`,\n`P.epe.>`, `P.epf.>`, `P.epj.>`, `P.ept.>`, `P.epr.>`, `P.epw.>`, `P.eps.>`, and `P.epc.>`\n(a space-wide `P.>` would plain-subscribe every `ep.one` request rail, collecting reply\nnonces the queue-qualified-only rule exists to protect, and every core-only session\nframe; \xA713.2, \xA713.11). Plus DM history read grants:\n\n- `$JS.API.STREAM.INFO.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>`\n- `$JS.API.CONSUMER.CREATE.<DM>.>`\n- `$JS.API.CONSUMER.INFO.<DM>.>`\n- `$JS.API.CONSUMER.MSG.NEXT.<DM>.>`\n- `$JS.ACK.<DM>.>`\n\nAdmin still has no application publish grants.\n\n### Scoped host profiles (formerly `manager`)\n\nThere is **no allow-all credential**. The privileged host duties are split into scoped,\nsingle-function profiles, each granting only the verbs its function needs and none other:\n\n- `provisioner`: pre-creates the per-instance lifecycle-scoped durables (`dm_\u2026-<uid>`,\n  `svc_\u2026`, the per-member `dlv_\u2026-<uid>` handoff) AND the trusted control-surface consumers of\n  the \xA713.9 matrix; `poolD`, `effD`, and the read mediator's reader durables\n  (`decD`/`goalD`/`eveD-n`/`recD-n`, owned by the mediator, never by callers, \xA713.9\n  \"Mediated reads\"), all PULL with exact full-tail filters; and mints scoped credentials;\n  ephemeral onboarding authority.\n- `deprovisioner`: target-pinned teardown of ONE retired lifecycle's footprint, minted per\n  teardown with the target's `(principal, lifecycleUid)` in every exact-name grant; it can\n  delete only lifecycle-keyed names, so it structurally cannot reach a same-name successor\n  (\xA713.1). The footprint is the `dm_`/`dlv_` durables, the read-ACL row, and the durable\n  membership row for each concrete channel the teardown names (one exact `memberKey` grant per\n  channel). A wildcard channel is refused at mint. The manager names the launch's concrete read\n  channels plus the channels the delivery daemon's read-only `lifecycleMemberships` admin verb\n  lists for that exact `(principal, lifecycleUid)`. When that inventory cannot be read, rows on\n  other channels stay retained, the teardown logs the inventory as incomplete, and retirement\n  remains held pending retry rather than releasing the alias.\n- `supervisor`: the always-on agent-lifecycle daemon (the manager process's own connection). It\n  is the manager endpoint's serve credential (\xA713.9) and the ONLY holder of the capabilities for\n  the delivery endpoint's admin commands (below).\n- `delivery`: the server-side Plane-3 infra: fan-out, trusted-reader re-authorization, and the\n  membership/ACL records the durable backstop authorizes against (\xA77). It is the `delivery`\n  endpoint's serve credential (\xA713.9); its admin commands, `reloadCreds`, the explicit adoption\n  step of standing credential renewal (the daemon re-reads its re-signed creds file, pins the\n  identity, swaps its connection, and reconnects the membership feed's rw connection, replying\n  with the adopted JWT windows); `reloadStoreIdentity`, the store-identity challenge that\n  names the SecretStore the daemon reloads from (the workstation root only when `--creds` is\n  `<root>/.cotal/<spaceSegment(space)>/delivery.creds`; the file's own directory otherwise, an injected coordinate,\n  the declared identity of an injected adapter, or the workstation root of the canonical arm; never a\n  `findCotalRoot` ancestor walk). The first-party workspace filesystem adapter declares its workstation\n  root, so passing that store explicitly names the real operator layout without an ambient coordinate. Uninjected `--creds`\n  that names one real workstation while process cwd resolves another is refused at start, because\n  membership-rw still uses `findCotalRoot`; a `--creds` path that is not under any `.cotal` tree is not that\n  case. A manager whose remint store diverges is not that daemon's renewal owner: it starts and\n  serves the space and skips the remint rather than being refused, including a daemon that bound\n  after manager start. Matching that store identity is necessary but NOT sufficient to own the\n  renewal, since the comparison carries no holder and no tiebreak and every manager sharing one\n  store satisfies it; the owner is the manager that also holds the space's renewal lease, so a\n  daemon's credentials have exactly one renewal owner at a time. And `evictPrincipal`, force-drop of a denied principal's live\n  connections (system-account CONNZ scan \u2192 per-server KICK \u2192 re-scan verify, fail-closed on\n  partial scans and on owners outside the principal namespace); carry a capability requirement\n  minted to the `supervisor` profile **and to the trusted auth path** (\xA79/\xA710), which is the\n  executor of the \xA713.1 takeover / terminal-retirement / handle-revocation barriers and calls\n  `evictPrincipal` on each revoked credential's `holderPrincipal` (\xA713.1) as their eviction\n  step; agents are broker-denied. `evictPrincipal` is\n  wired into those barriers, not\n  a standalone admin convenience. `evictPrincipals` is the same eviction for a set of at most 256\n  distinct principals in ONE shared sweep: one CONNZ scan for the set, a KICK for every matching\n  connection with at most 16 KICK requests in flight, and one re-scan per verify round covering\n  every principal still pending. Every KICK settles before the re-scan that verifies it. Its reply\n  is one `EvictionResult` per principal in request order, each read as `evictPrincipal`'s\n  (an under-reported scan leaves every principal it would have decided `verifiedGone:false,\n  scanComplete:false`). Frozen-gate reconciliation and an endpoint re-registration (\xA713.1) each\n  verify-evict their whole holder set through it, so neither costs one sweep per family holder,\n  and KICKing a live family costs one broker round trip per 16 live connections. A\n  daemon that does not serve it refuses the verb, and the repair or re-registration then leaves\n  the gate frozen. Its READ-ONLY twin `principalLiveness` answers whether one\n  principal still holds a live connection (the same CONNZ sweep, observer credential only \u2014 the\n  KICK credential is never opened on that path), reporting `live` / `gone` / `unknown` with scan\n  completeness as a separate field and a reply bound to the exact principal queried. It exists\n  because eviction cannot serve as its own precondition: a repair that must REFUSE while a holder\n  is alive would, using `evictPrincipal` to find out, kill the holder before it could refuse.\n  `gone` requires a complete, single-server-proven sweep (\xA713.13); an under-reporting sweep is\n  `unknown`, which never authorizes. The former\n  `delivery-admin` control tier is deleted with the v0 rail (\xA713.11).\n- `membership-rw`: the derived channel-membership graph feed reader/writer.\n- `operator`, `purger`, `teardown`, `channel-writer`, `control-caller-*`, `deployer`, `probe`: the\n  human-CLI and maintenance surfaces, each scoped to its verbs.\n- `issuer`: one issuance window (\xA713.15), minted per mint or per lifecycle terminal by the party\n  holding the space signer; the issued and accepted stores plus one auth-store liveness read.\n- `run-admitter`: one run's admission record or revocation marker (\xA714.8), minted per run for\n  60 seconds; two exact keys and nothing else.\n- `manager-service` is NOT a generic host profile: on a per-user-auth space only the\n  loopback/operator exchange may issue this closed, one-owner/one-fixed-manager-actor/one-instance\n  view to a signed-in user with ledger scope `supervise` (\xA713.1/\xA713.6). It reaches exactly the\n  staged manager registration, contract, status, gate, credential, and same-owner descendant\n  provisioning family; public exchange, managed-agent secret exchange, plain user bearers, and all\n  other instances are refused.\n- `platform-control` is NOT a generic host profile either. It is the \xA713.1 service view a host\n  issues, through its authority context's in-process door only, to one platform-run control\n  manager per assigned account, under a `p_` platform owner and the host's current assignment. It\n  reaches the same one-instance family as `manager-service` and same-owner descendants only. It\n  never carries a human identity, never reads or implies `supervise`, and every exchange refuses it.\n\nStanding host credentials are **bounded and renewed**: one-shot profiles carry minutes-scale\nexpiry; `supervisor`/`delivery`/`membership-rw` carry a 24h expiry with the manager as the named\nrenewal owner (self-remint for its own credential; same-nkey re-sign + explicit `reloadCreds`\nadoption for the seed-less daemons); the two system-account credentials (`membership-observer`,\n`connection-evictor`) carry a 30d expiry and are renewable ONLY by a system-account rotation +\nbroker restart; no persisted system-account minting secret exists, by design. On per-user-auth\nspaces, static `agent`/`observer`/`admin` minting is retired entirely (the flip): agent identities\nexist only as owner+actor principals under a logged-in user, and the elevated profiles of this\nappendix are reached per-connection via the exchange-authored view claim instead (\xA710). The flip is\ndeny-new: a static\ncredential signed before it (or minted out-of-band with the account signing key) remains\nbroker-valid until signing-key rotation, which is the revocation lever for static material; the\nguarantee therefore applies to spaces that never issued static user-facing credentials.\n\nThe live channel subscribe depends on none of these; it is broker-enforced via `sub.allow`, so\nself-serve live join works with no host present; only the durable backstop and its membership writes\nrequire a privileged host. None of these profiles is ever issued to ordinary agents. On the v0.4\nendpoint surface, every host profile's grant rows are **generated from the \xA713.9 ownership matrix**\n(matrix \u2192 grants, never the reverse): a profile with no matrix row holds no `ep*`, `$O.`, or\ncontrol-surface `$JS.API` authority, and `provision.ts` (`permissionsFor`) is the generated artifact\nthis appendix summarizes, not an independent authority. This appendix spells out the `agent`,\n`observer`, and `admin` profiles that make up the wire-facing security claim.\n\n## Appendix C: Normative references\n\n| Reference | Used for |\n| --- | --- |\n| RFC 2119, RFC 8174 | requirement keywords |\n| RFC 8259 | UTF-8 JSON envelopes (\xA75) |\n| RFC 4648 | base32 instance-id encoding (\xA72) |\n| RFC 8032 | Ed25519 keypairs behind nkeys (\xA72) |\n| RFC 8785 | JSON Canonicalization Scheme: every `*Digest` (\xA713.7), the program hash, input hashes and derived ids (\xA714, [`spec/cotal-lang.md`](spec/cotal-lang.md)) |\n| [ECMA-262, 14th edition (ECMAScript 2023)](https://262.ecma-international.org/14.0/) | the syntax and pure semantics the workflow language is a subset of ([`spec/cotal-lang.md`](spec/cotal-lang.md) \xA72) |\n| [NATS client protocol](https://docs.nats.io/reference/reference-protocols/nats-protocol) + [JetStream](https://docs.nats.io/nats-concepts/jetstream) | the v0 transport binding (\xA78) |\n| [NATS decentralized JWT auth](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt) + nkeys | identity and authorization (\xA72, \xA79) |\n\n## Appendix D: Change log\n\nNormative revisions of this document, newest first. Dated snapshots per \xA711; the wire\n`protocolVersion` is the compatibility signal, not these dates.\n\n| Date | Revision |\n| --- | --- |\n| 2026-10-04 | **Managed lifecycle handoff (\xA713.17), additive.** A managed agent already enrolled through \xA713.1 may run where the enrolling manager's filesystem is not visible. The manager releases one closed `cotal-managed-handoff/v1` document by value into that one child, carrying the issued owner, actor, lifecycle UID, sentinel, pinned exchange base, and the raw actor token, which the host never receives. The child's entry point removes the handoff file and its variable before it parses its arguments or does anything else, refuses a mismatched owner, actor, or lifecycle UID before any plane opens, never enrolls or mints, and uses the existing agent-bearer exchange unchanged. The manager refuses a spawn choice only its own host can honour before enrolling. Readiness stays presence-observed, a lost create acknowledgement stays held as uncertain and is never retried, a provider's answer that no resource exists is not an exit, and a close by the lifecycle-derived key is fenced against a create that could still land. A provider resource is bound to that key only by the provider's authenticated answer to its create, never by a derived identifier, a name or a listing. Retirement reuses prepare-retirement, then the known runtime handle's fenced close, then the terminal barrier, including after the manager is gone. A preservation cut that holds a handed-off lifecycle is refused, and a manager stop after a refused cut retires it. |\n| 2026-10-04 | **Platform control authority (\xA713.1, \xA713.6, \xA713.9), additive.** A closed server-authored `platform-control` view, beside the unchanged human `manager-service` view, lets a host run one pooled control manager per assigned account. Its holder's owner is a host-derived `p_` platform owner token, disjoint from every `u_` owner. The host's fresh platform-control assignment authorizes it in place of a ledger `supervise` scope. One closed envelope carries the existing typed manager requests through an in-process door of the host's authority context, served on no listener. The unchanged registration proof, process epoch, and all-duty renewal renew and fence it. Its host-owned maintenance reaches only the assigned instance under its own gate. An account has one assignment and so one control instance, which keeps its instance id and lifecycle UID across restarts and enters a deployment only after the assignment's named predecessor manager has left through its own path, read and never written by the host. It refuses human tokens, takeover of another owner's instance, local or custodial runtime, generic signing, exchange issuance, and cross-owner descendants. The reference host is `startAuthService` in `@cotal-ai/auth`. |\n| 2026-10-02 | **Plane liveness (\xA76.1), additive.** A credentialed peer can ask whether the manager or delivery plane has a bound responder, on `live.<plane>.<owner>.<actor>` with the reply under `<request>.reply.<nonce>`. The reply is `LivenessAnswer`: `plane`, a `ResponderState` verdict, and an optional opaque per-bind `instance` token that distinguishes responders without identifying them. Only the broker's no-responders answer grades `unbound`; every other failure to get a readable reply grades `unknown`. Agents gain the per-plane request and reply rows; the `delivery`, `supervisor` and remote-manager supervisor credentials gain their plane's serve filter and bounded reply grant. A responder binds again on every connection that replaces the one it bound on, and the manager is not `bound` while its service connection is closed or disconnected. |\n| 2026-09-28 | **The `auth` endpoint becomes a conforming registered endpoint (Cotal #399), closing the two gaps the prior two rounds named.** The plane's boot registers `svc.auth.<instanceId>` through the standard `registerServiceInstance` path and publishes its `retire-lifecycle` contract artifacts to the content-addressed contract store, so the endpoint now serves the reserved `describe` and answers the v1 envelope (`ep.v1`) instead of the legacy `{op,args}`/`{ok,data,error}` body this document states are deleted; a legacy body is refused `unsupported-version` as envelope validation, never an ACL denial. The requester side moves from a hand-built subject to the generic client (`resolveService` + `invokeCommand`), still minted in `exact` mode target-pinned to one incarnation at mint time, and gains the baseline `describe` row plus a bounded contract-store direct-get row so it can resolve the endpoint's registered digests before it calls; a body target that disagrees with the exact subject triple is refused `target-mismatch`. Two new \xA713.9 rows record the registered instance and the requester's describe/store-read grants. |\n| 2026-09-27 | **Id-less messages are not publish-deduplicated on the durable plane (\xA78).** The reference Plane-3 fan-out writer and membership-transfer frame publish carry no `Nats-Msg-Id` for a message whose `id` is `\"\"`, so two distinct id-less posts on a durable channel both reach a member and a redelivery of one id-less post may surface twice; a message with a real id keeps its idempotent publish key unchanged. Classification: reference-binding behaviour, no wire-envelope or schema change, protocolVersion unchanged. |\n| 2026-09-09 | **Issued authority and run admission (\xA713.15, \xA714.8).** A caller's request may ride a versioned rail (`ep.v1`) that pins the credential's issuer-accepted **generation** beside its triple; the issuer persists the generation's immutable permission ceiling as evidence before returning material, and a client learns its generation from an issuer-written accepted row. A hosted workflow run is admitted under the caller's resolved ceiling, recorded once per run in a dedicated store the driver cannot write, checked before every channel effect, and revoked by an independent marker; resume, takeover and reconcile continue under the original admission, a fork is a new admission, and a local run is admitted from operator evidence named on the command line. `run-start` on the legacy rail is refused by name. Three new per-space stores, two new one-shot profiles (`issuer`, `run-admitter`), and an admission read on the run mediator and operator profiles. **Breaking pre-1.0 authority change: minor.** |\n| 2026-08-24 | **Remote user manager authority.** A closed server-authored `manager-service` view permits one registered user-auth participant to operate one opaque manager instance only when their live actor-ledger row carries the dedicated `supervise` scope. `supervise` is distinct from `spawn` and `admin`; public and managed-agent exchanges refuse the view, and plain user bearers remain unprivileged. The host, never the participant, issues public-nkey JWT material through a lifecycle- and instance-bound, typed, replay-safe `prepare \u2192 activate \u2192 renew` protocol. The family is confined to one derived owner, fixed server-selected manager actor, lifecycle UID, instance registration/contracts/status, gate, and credential rows; descendant provisioning is host-validated for the same owner only. Revocation and renewal deny new material and unsafe restarts fail-closed while retaining live agents only within their independently valid authority. **Breaking pre-1.0 authority change: minor.** |\n| 2026-08-19 | **Receiver deduplication MUST NOT use the empty string as a key (\xA74), and id-less deliveries are individually addressable (\xA78).** Two distinct received messages MUST NOT be treated as one logical delivery solely because both carry `id: \"\"`; each remains independently deliverable, and copies that cannot be correlated by wire identity may surface more than once on an at-least-once path. The publisher's \xA75 obligation to supply a unique string id is unchanged; an absent or non-string id remains a malformed envelope, now enforced at each delivery pump (durable terminate, live drop, history and recall skip). \xA78 adds that the absence of a usable receiver dedup key does not relax acknowledgement ownership: a JetStream-consumed copy with `id: \"\"` that is surfaced or handled MUST be acknowledged independently, and the reference implementation realizes that through a per-delivery receive key (never wire identity, never dedup authority) at its drain and in-flight seams. Plane-3 durable fan-out still derives its publish msgID from `CotalMessage.id`, so distinct `id: \"\"` messages can be collapsed inside the broker's duplicate window on a durable channel before the receiver sees them; that path is its own tracked change and this revision's guarantee is scoped to the receiver. Classification: normative receive-side semantics, no wire-envelope or schema change, `protocolVersion` unchanged. |\n| 2026-08-18 | **v0.5 binding revision: workflow runs (\xA714), additive.** A deployment MAY host durable workflow runs: programs in the Cotal workflow language, defined by the new normative reference [`spec/cotal-lang.md`](spec/cotal-lang.md) (language version `1`: the syntax table, values and the boundary rule, the library, the effect primitives with their hashed projections, the four concurrency scopes and the clock-decided `race`, the step key grammar, journal entry schema, input hash and request id, resume, migrate and fork), whose every effect is recorded in a per-run step journal on the new per-space `WFJ_<space>` stream (one subject per run, no age eviction, no Direct Get, every append fenced by the run subject's own sequence, replay-then-activate takeover with a fencing-token authorization tuple, an ordinal chain and a `journalHigh` anchor). Four core record kinds join \xA713.7: `run` (split; the resolved pin set on the spec half, holder/lease/`journalHigh` on the status half; driver-minted, never-reused ids), `answer` (atomic, content-derived id, keyed per answer because every presenter is the driver), `notice` (split; addressee keyed by a digest of the name; consumption as status), `migration` (split; content-derived id; application as a create-only status). Driver grants are per run and per takeover, with no wildcard form. `languageVersion` is pinned per run and moves independently of the wire version. No existing kind, subject, grant row or shipped datum changes. |\n| 2026-08-16 | **A caller declares the incarnation it resolved against, and a responder that is not it refuses before any effect.** A class-addressed request is delivered to one member of a queue group, and the member that answers need not be the one the caller's `describe` resolved against. The caller could only detect that AFTERWARDS, from the reply subject, by which point the command had run: the split was observable but never preventable, and the reference client's recovery repeated the command. `bind` (\xA713.3) is the caller's declaration of `{ instanceId, epoch }`, checked by the responder against its own identity at the pre-effect seam, ahead of the governed gate and every handler. A mismatch is `failed-precondition` for a different instance and `expired` for another epoch of the same one, both carrying `details[].kind = ai.cotal.ep.bind-refused` and, per \xA713.3, `outcome: not-executed`. **ADDITIVE**: `bind` is MAY, a responder that does not implement the fence ignores it under \xA75 and executes, so the caller-side check remains the only protection in a skewed pair and `protocolVersion` stays 0.4. It confers nothing and narrows only, so it satisfies monotonic attenuation: a request carrying it reaches exactly the instances the subject already routes it to, and can only make one of them refuse. Absent on `describe` (the bootstrap that produces the bind) and on the scatter rail (which addresses every incarnation by construction); on the `inst` rail it MUST name the subject's instance and adds the epoch the subject grammar has no token for. Attribution still comes from the reply subject, never from this block: it is what the caller bound, not a claim about who answered. |\n| 2026-08-16 | **A command declares whether repeating it is safe, a responder reports whether a refusal already executed, and the two are separated from idempotency by `id`.** Three gaps that only bite together. **(1) `effect` (\xA713.7).** Nothing in a resolved command distinguished a read from a mutation \u2014 every manager command declares `class: \"ephemeral\"`, and `traits` carries no repeat-safety \u2014 so a client deciding whether to retry had nothing to consult, and the reference client repeats a mutation on a split. Precisely: the automatic repeat belongs to the high-level helper, not to the primitive \u2014 `invokeCommand` raises the post-reply currency refusal and stops, and the `invokeService` wrapper around it catches exactly that code, re-resolves, and invokes a second time. Measured on a live broker under a forced instance split, counting at the handler rather than on the wire, the repeated command executes TWICE. `effect` is `read` or `write`, with `read` defined OPERATIONALLY \u2014 repeating it changes nothing the command is TRYING to change, and the only excluded difference is the incidental trace of having been called (request ids, spans, logs, metrics, timing) \u2014 because the intuitive definition, indistinguishable to every observer, is satisfiable by no real command and would make the field decorative. The state in question is not only the endpoint's own: a command whose intended effect lands elsewhere is still a `write`, and `evictPrincipal` fixes that boundary, since dropping live broker connections while leaving the endpoint's own records untouched is the point of calling it. **(2) `error.outcome` (\xA713.3).** A refusal code cannot say whether the effect happened: the same code is correct for a request that ran and one that never left. `outcome` is emitted by the RESPONDER, which is the only party that knows \u2014 `not-executed` when it refuses before the handler, `executed` when it refuses after, `unknown` when it cannot tell. It describes a reply and only a reply \u2014 a caller-side refusal is not an `EndpointReply` and carries no `outcome` field \u2014 but it does NOT follow that the caller knows nothing, and the first cut of this amendment wrongly collapsed four distinguishable local cases into `unknown`. A refusal raised BEFORE publication is `not-executed`: the request never left, and calling that `unknown` suppresses a retry that is provably safe even for a `write`. A refusal raised while HOLDING a reply \u2014 the \xA713.2 post-reply currency check is the case in this document \u2014 takes what it knows from that reply: `ok:true` means the handler ran, and an `ok:false` reply carries the responder's own `outcome`, which the caller adopts rather than overwrites. A **broker-attested no-responders answer** on the reserved sentinel is also `not-executed`: it is positive evidence that the subject had zero subscribers, trusted only on that sentinel because the same status on an ordinary reply subject is a responder's own claim. Only \"no reply observed at all\" (deadline, transport failure after publication) is `unknown`. And **a reply proves the request was HANDLED, never that it was EXECUTED** \u2014 the version, class, target, sender, authz, contract, and guard checks all publish `ok:false` having executed nothing. It is also not a goal's terminal state (\xA713.6 owns that) and must not be used as one. **(3) Repeat versus resubmission (\xA713.8).** `effect` and \"idempotent by `id`\" are different axes and were unreconciled. They are now separated by CONVERGENCE rather than by token: a **resubmission** is a re-send the responder converges onto the decision it already recorded, a **repeat** is one it accepts as new work, and `effect` governs repeats whatever `id` they carry. Defining the split by the token instead left a hole \u2014 a post-horizon re-send under a reused `id` is accepted as new work, so it executes, while formally escaping a prohibition written as \"under a fresh `id`\". Reusing the token is how a caller ASKS for convergence; it is not the answer. Within the horizon `id` is what convergence is keyed on \u2014 and `id` is the whole key on the ephemeral rail but only ONE of the effect-defining dimensions the journal fingerprint binds \u2014 endpoint, command, `id`, `goalId`, `class`, args, both contract digests, the authorization mode, the target, `auth`, and the caller \u2014 where same id + different args is neither dedup nor a fresh call but a loud `conflict`. **Both rails are bounded by a horizon**, realized by decision-fact and result retention rather than by a clock, and outside it neither rule applies: the `id` carries no history, a re-send under it is a fresh call that WILL execute, and the same `id` with different args is no longer a `conflict`. A finite horizon is what keeps the decision store finite, so this is a fact callers must hold rather than a hole to close \u2014 and because a repeat is defined by acceptance rather than by token, a post-horizon same-`id` re-send of a `write` is exactly what \xA713.7 forbids a client to make automatically. A command idempotent by `id` is therefore NOT thereby `read`: safe to resubmit is not safe to repeat \u2014 and the dangerous reading is a reasonable one, since an operator who retries after a timeout mints a fresh `id` because the old request is gone. **NON-ADDITIVE, and versioned as such:** a client that ignored `effect` would keep performing exactly the retry the field exists to stop, so it rides `protocol.v` \u2014 the marker that ALREADY EXISTS on the service record spec and the describe descriptor, never a new field on the cluster document, which has no `protocol` and where \xA77 would drop it unread by exactly the clients this must stop. An instance whose clusters declare `effect` registers and describes at `v:2`; `v:1` descriptors stay valid, carry no `effect`, and every command served under one reads as `write`. The caller-side refusal of a `protocol.v` it does not implement is a requirement this cut CREATES, not one already met: today `describe`'s pinned output schema fixes `descriptor.protocol.v` to the constant `1`, so an unamended responder cannot publish a `v:2` descriptor at all, and the registry reader refuses a service record that is not `v:1` \u2014 but the resolving caller validates neither, and the shape it reads does not carry `protocol`. The responder-side fence is what protects old clients today, and only until this cut widens that constant. **Release order was the wrong instrument and is withdrawn**: a same-release ordering rule has no observable runtime meaning, since a release is not a deployment and an already-running v1 caller is unchanged by whatever a new artifact contains. **The cutover rule is \xA711's, and \xA713.7 does not state one.** Moving to `protocol.v: 2` IS a non-additive discovery change, so the \xA711 rule for one (previous row, landed first) is the sole authority on how it rolls out. \xA713.7 carries only what is specific to `2`: a caller that resolves a descriptor whose `protocol.v` it does not implement MUST fail the resolve (`unsupported-version`) and MUST NOT invoke against it \u2014 a descriptor it cannot read is no descriptor, and reading it as `v:1` reinstates the repeat \u2014 and implementing that refusal is what makes a caller count as having ADOPTED the section for \xA711's condition. Two intermediate drafts had to be withdrawn to reach that: one sited the cutover in \xA713.7 as a same-release ordering clause, which has no observable runtime meaning because a release is not a deployment; the next stated the cutover in BOTH sections, which is a single-source-of-truth defect, since two normative statements of one rule agree until either is edited and then silently become two conformance rules. The reason it cannot be sited here is the durable part: the condition is a property of the whole deployment, and a responder cannot evaluate it \u2014 no in-band negotiation, no caller version on the wire \u2014 so a rule stated here would bind the one party unable to check it. |\n| 2026-08-16 | **A non-additive discovery change is an out-of-band deployment cutover and rolls out CALLER-FIRST (\xA711).** The preceding \xA711 rule says v0 has no in-band capability negotiation and that deployments agree out of band; this says what that obliges when a discovery change CANNOT be ignored safely \u2014 where an unamended client that drops the new field per \xA77 would then behave in the very way the change exists to prevent, so no default value repairs the direction that matters. The obligation rests on the DEPLOYMENT, because neither participant can discharge it: a responder cannot tell an amended caller from an unamended one, since no request carries a caller version and `describe`'s answer is read by the caller without a version check. So every caller adopts the new rules BEFORE any responder registers or describes at the new version, and the two halves SHOULD ship in SEPARATE releases \u2014 **a release is not a deployment**, and an already-running caller is unchanged by whatever a new artifact contains, so the order of two source edits proves nothing about the processes on the wire. `protocol.v` on the registered service record is the observable marker: \"has any responder cut over\" is a checkable registry property, while \"has every caller adopted\" is the out-of-band agreement \xA711 already requires. **The residual is stated rather than engineered around**: an early cutover exposes unamended callers to exactly what the new version prevents, and within v0 nothing in band detects it \u2014 closing that needs negotiation v0 does not have, and the v1 marker owns it. Prose only: no schema, no wire field, no code. |\n| 2026-08-14 | **The auth-admin rail moves off the retired `ctl` surface onto the endpoint SUBJECTS (a subject-plane migration, NOT yet a conforming endpoint - see the residual below), and its authz description is corrected to what ships.** TWO defects on the same \xA713.9 rows, fixed together. **(1) The rail.** The rows served the auth plane's generic \"retire a lifecycle\" operation on `ctl.auth-admin.<owner>.<actor>` \u2014 a rail \xA713.11 retires in full and states MUST NOT be handled. New normative rows written onto a deleted rail are defects, not exceptions to it, so they are rewritten onto the v0.4 endpoint surface rather than given scoping language: `ep.one.auth.retire-lifecycle.handle.<tO>.<tA>.<tUid>.<cO>.<cA>.<cUid>.<nonce>`, served queue-qualified on the class rail, with the reply DERIVED from the parsed request (the bound-reply rule becomes structural \u2014 no caller- or payload-supplied reply target can arrive) and the request/reply planes disjoint, so the listener credential cannot express a request subject and the self-forge closes by grammar. The requester credential now pins its caller TRIPLE and exactly ONE target incarnation, so a leaked requester cannot be re-aimed. \xA713.11 is unchanged and gains no carve-out. **(2) The authz sentence.** These rows described serve-time authz as a space-manager-LEASE holder check; the implementation replaced that with the serve-issuance-gate check on 2026-07-22 without a spec change, so the normative text had been false since. It now describes what ships \u2014 a fresh leader-served read of `epgate.<serveEndpoint>.<serveInstanceId>` requiring presence, the declared epoch, and THE PRINCIPAL CROSS-CHECK (`row.principal` must equal the subject-derived caller principal), the last being new here: the two-token `ctl` subject could not express the caller beyond an alias, so the rail had accepted ANY registered instance's gate. The binding is stated as ALIAS-LEVEL, not incarnation-level: the gate is keyed by the persisted `instanceId` and its row carries no lifecycle uid, so a same-principal predecessor presenting the current epoch still passes; binding the publishing incarnation needs a gate-row schema change and is not attempted here. **NAMED RESIDUAL (Cotal #399) - THE RAIL IS NOT A CONFORMING ENDPOINT: it carries the endpoint SUBJECTS only. It still exchanges the pre-v0.4 `{op,args}` / `{ok,data,error}` bodies this document states are DELETED, registers no `svc.<endpoint>.<instanceId>` service record, does not serve the reserved `describe`, and has no contract/cluster artifact - so a GENERIC endpoint client can neither discover nor invoke this command. The exploitable half is closed in this change - the request carries a caller-chosen `id`, the responder echoes it on every reply, and the caller refuses any reply that does not echo, so a wrong-id `ok:true` cannot clear a retirement hold - but the versioned typed envelope, contract digests, `class`, deadline/`replyExpected` semantics, structured errors, service registration and `describe` are a separate cut tracked at #399, whose acceptance test is that a GENERIC client can discover and invoke the command. Recorded here rather than left implicit: serving a deleted envelope on the new rail is the same class of defect as serving on a deleted subject.** |\n| 2026-07-19 | **v0.4 amendment continuation: retirement cleaner inventory is discovery-only.** The terminal retirement barrier no longer accepts a caller-supplied `(endpoint, pools)` hint: the per-op cleaner and settlement-executor pool set is now DISCOVERY-ONLY, exactly the retiring lifecycle's accepted `oblig.<uid>.>` pool routes discovered from the just-drained obligation set. This SUPERSEDES the round-11 optional-hint clause (the 2026-07-15 row): the hint was a TRUSTED ADDITIVE AUTHORITY input that would mint a bounded per-op credential for a pool with no backing obligation, and the despawn rail never exercised it (always an empty hint), so it was grant-widening surface with no production caller. Every grant now scopes to exactly the pools the target holds accepted work on, and the \xA713.9 residuals cover only those discovered pools. The intent's `endpoints` field is removed from the closed operation-intent schema; a pre-change durable intent that still carries it fails the closed-schema check on resume (the v0.4 hard-cut window, where a clean broker holds none). |\n| 2026-07-16 | **v0.4 amendment continuation: connect-arm deny-new (production activation R1).** Every bearer carries its incarnation's root credential id (`act.credentialId`); the exchange mints the root credential RELEASE-LAST (active `cred.` row durable, gate finalize, lifecycle-head current-root CAS, bearer bytes last) and the connect authority requires the LIVE row (leader-served from the shape-proved primary auth store, re-proved on every rebind) plus root head equality, so revoking the row denies the next connect and a superseded or crash-orphaned root issuance never authenticates. The root credential is **incarnation-wide** (ratified): one row per incarnation, re-stamped (the same id) every exchange for its 90d life, never a fresh id per exchange, so one revoke denies every bearer of the incarnation, and a crash after the head CAS re-exports the same id by design (nothing unobserved to revoke; the only pre-release crash window is a durable unstamped row, denied by head equality). The authority store shape proof binds the stream to the actual KV bucket (exactly the one `$KV.<bucket>.>` subject + durable file storage, in addition to the primary/un-mirrored/non-evicting/`allow_direct` flags) at every bind and at boot ensure. Claimless bearers, revoked/expired/absent rows, and an unreadable authority store deny outright (no file-only fallback; a failed reader-credential renewal downs the reader immediately and denies). The head's current-root stamp moves only ABSENT to value: root rotation without the full family-revoke barrier is refused structurally. Named R1 residuals: a same-alias re-grant while the predecessor incarnation is live refuses the exchange (production issuance runs no takeover barrier yet), and the auth service's reader/mint-writer are seed-signed infra credentials (revoked by service stop or signing-seed rotation) pending the ledgered infra-mint family. |\n| 2026-07-16 | **v0.4 amendment continuation: retirement settlement authority split.** A seventh round (an independent cold read on the landed barrier plus the panel's authority ruling) split terminal pool cleanup across two profiles: the bounded cleaner keeps ONLY bind-scoped fetch, leader-served EPF terminal-observe reads, and ACK (its former own-pool `wrk` terminal-forge residual is REMOVED with the grant; its remaining residuals are terminal-free ACK suppression and the space-wide read exposure), while the op-bounded retirement settlement executor (a new \xA713.9 row) owns the intent-closed lease-record CAS and the lease-derived `wrk` terminal publish, carrying the relocated, intent-confined forge residual. Settlement is lease-fenced: an already-settled lease (a crashed owner's `committed`) dominates and is never overwritten. Effects-route completion is a new CLOSED `eff` fact (subject-bound caller and id; `fingerprint` and `sourceSeq` bound to the accepted decision), an action's completion requires the parsed `goal\u2026.result` fingerprint match, and subject presence never proves quiescence. The mediator's obligation-row residual is stated honestly (an operation/header-blind KV publish: valid-terminal overwrite or DEL/PURGE markers, refused loud by readers; the records stream denies stream-API message-delete/purge), and the caller-selected-reply confused-deputy injection residual is named for every raw `MSG.GET`/`MSG.NEXT` profile. |\n| 2026-07-15 | **v0.4 amendment (folds into the in-flight \xA713 revision below): lifecycle and admission fences.** Three-state lifecycle head (`active | retiring | retired`; currency only at `active`; `mappingRevision` = the head key's store revision), space-global never-deleted UID reservation (`uid.<lifecycleUid>`), per-kind issuance-gate operation intents and their allowed-transition sets, the locked terminal barrier order (obligation drain to quiescence before the exact-pool cleaner, both before frontiers), the \xA713.8 authority-head reservation/drain protocol (create-fence + proof-gated admission + per-class decision coordinates + writer\u2260target reclamation), the endpoint-wide admission-policy coordinate (the governance head + `policyRevision`) with drain-gated policy enforcement, the `ep` sentinel for untargeted admissions, and bind-time store shape proofs (\xA713.12). Refined per the re-verify round: the govern head's NORMATIVE policy selector `{ enforcedPolicyKey, enforcedPolicyRevision, pendingPolicy\u2026 }` with a stage/drain/promote mutation order (so the enforced policy is machine-selectable during the drain window), the `self`-class obligation's complete commit intent `{ commitKey, commitBaseRevision, commitValue, commitDigest }` (the pinned BYTES, not just a digest) with deterministic `accepted \u2192 terminal` recovery and full-intent create-join (an accepted-but-uncommitted row never blocks quiescence), the retirement barrier's cleaner-credential revoke + verified-eviction BEFORE any frontier records, the LIMITS-retention bind-time proof (a non-Limits authority store deletes rows on consumer ack), and the runtime gate parse rejecting impossible `retired`-under-takeover/registration state. A second re-verify round added: the head's `lastTakeoverOpId` (the epoch advance stamps the completing op, so a losing concurrent takeover never claims the winner's completion), the immutable revision-addressed admission-policy key (a mutable per-instance slot loses the old revision under history 1 during the drain), the `epgate.principal` and the rule that a ledger row's `holderPrincipal` is ALWAYS a CONNZ-attributable principal (the endpoint NAME forms the `epcred.` key in a separate field, never the eviction target), and the lifecycle barrier's session-pair teardown (a takeover revoking a `session.`-derived credential terminalizes the session and revokes the paired serving row). A third round (a convergent panel + independent cold read) added: the normative immutable `policy` record kind `policy.<endpoint>.<digest-hex>` (self-certifying content-addressed key; the govern selector names exactly this kind, replacing the per-deployment \"versioned key\" allowance), the CLOSED `commitValue` union (`{ enc: \"b64u\", bytes }` exact base64url value bytes, or `{ enc: \"ref\", key }` naming an immutable records key; `commitDigest` = `sha256:<hex>` over the raw value bytes), proof-issuance PAUSE for policy-admitted decisions while a `pendingPolicy\u2026` is staged (which makes the policy drain converge and the after-final-enumeration no-admit rule hold for policy movement), the serving-principal JOIN into the lifecycle barrier's verified-eviction set (a session-pair teardown returns the paired serving row's holder principal and the barrier evicts it before the epoch CAS), and the torn-coordinate takeover guard (the intent capture re-proves head coherence, and the freeze CAS is preceded by a head-currency read, so a stale intent never freezes the winner's reopened gate). A fourth round (a convergent re-verify + independent cold read) added: the drain-window admission pause is now a NORMATIVE step of the \xA713.8 admission algorithm (the mediator's create-fence AND post-create recheck leader-read the govern head and refuse a policy-admitted decision while a `pendingPolicyKey` is staged, which also bounds the never-deleted `oblig` set during a long drain), the \xA713.9 matrix records the mediator's govern-head and policy-version read authority, the `policy` kind's immutability is stated honestly as a trusted-writer create-only-CAS invariant backed by read-time self-certification rather than a broker-level update/delete subtraction (KV operations share one subject), and the takeover barrier's crash-boundary recovery COMPLETES containment (revoke + reconcile + verified-evict every family holder) BEFORE it aborts a stale/torn freeze, so a crash after a partial revoke never leaves a revoked credential's connection live. A fifth round (panel + independent cold read on the B2 mediator) refined: `commitDigest` is the RFC-8785 canonical content digest of the committed value, `sha256:<hex>` (not a raw-bytes digest, so it is insensitive to a non-canonical storage stringify), and `commitValue`'s `b64u`/`ref` forms both resolve that same value; the policy publication is content-addressed by the same canonical digest (property-order-insensitive). The session expiry sweep now enumerates a marker-preserving stream read rather than the bucket's `keys()` (which filters DEL/PURGE), so a tombstoned session key is reported as corruption, not silently skipped. The terminal barrier's frontier record is pinned as the `frontier.<lifecycleUid>` kind (\xA713.7: create-only, never deleted, one key per retired lifecycle, recorded once under its own operation's `opId` before the gate/head terminals), and the exact-pool cleaner's `retired` disposition is a first-class `wrk` terminal fact carrying its operation and retiring-target binding. A sixth round (the D14 confinement review) pinned the two mediated-profile grant shapes: the admission mediator's enumeration consumer carries a deterministic (endpoint, connection)-bound name with name-literal CREATE/INFO/MSG.NEXT/DELETE rows (closing the name-wildcard cross-consumer reach; the own-name delete is what keeps the fixed name reusable across filters), both profiles' reply inboxes are connection-scoped (`_INBOX_<connId>.>`, never the account-wide default), and both payload-blind write residuals are named with equal explicitness: the mediator's own-endpoint acceptance-forge and the cleaner's own-pool `wrk` terminal-forge (work suppression or mis-settlement), each confined to its subject-expressible scope. A seventh round (the control-surface sealed-scanner seal) moved the dynamic-enumeration `CONSUMER.CREATE` off every standing/runtime credential (the takeover/retirement/handle-revocation barrier and the session sweep on `cotal_auth_<space>`, and the admission mediator plus the retirement obligation-drain on `cotal_records_<space>`) into dedicated SEALED scanners the trusted process opens for itself and NEVER hands out, because a consumer-create request BODY is not subject-ACL confinable (an extended name+filter grant still admits a `durable_name` + push `deliver_subject` exporter of every current/future row that survives connection close and revocation, nats-server#8274, reproduced live); each scanner is pinned to one literal consumer name under a forced pull/`LastPerSubject`/ephemeral/memory config, bind-verified before use and unconditionally deleted after, its CREATE filter confined to its subtree, space-bonded so a hand-assembled or foreign-space scanner never enumerates, and fence-free by construction (a `LastPerSubject` read carries no upper cutoff, so a same-subject overwrite during the scan is SEEN, not dropped). Its re-verify round hardened the seal from asserted to enforced: the scanner capability handle is immutable once branded (a swapped scan op throws rather than surviving the injection assert; that mutation vector was reachable only from inside the trusted process, the signing-seed residual class, never externally), every scan over a space's literal consumer name serializes process-wide (a second scanner instance can never interleave with a live scan and return a partial enumeration; cross-process duplication remains excluded by the one-authority-plane-per-space composition), every delivered subject is revalidated against the exact requested filter (an out-of-filter delivery from a foreign re-resolution of the literal name is refused loud; a foreign SAME-OR-NARROWER filter remains covered by the one-plane composition, not by this check), the two scanner profiles are explicit \xA713.9 matrix rows whose grant builders the mechanical matrix audit pins as the SOLE dynamic-enumeration `CONSUMER.CREATE` holders on the two authority streams (the provisioner's pre-created full-tail reader durables remain the one other records-stream consumer authority, and the audit pins that complete surface too), and the admission-mediator coordinate stays package-internal until a composition owns the one-records-scanner-per-space injection. An eighth round (the control-surface piece-2/4 wiring) landed: the record-reader provisioning seam is an ALLOWLIST over one canonical authority-def collection (a reader durable's kind must be a registered caller-readable record kind, so every authority-control kind and every unregistered kind refuse, and a dual-token kind whose atomic head is authority admits only a filter strictly deeper than the head, never one that can match or is shallower than the head key); that classification is runtime-frozen and the seam consults a private module-load snapshot, so a post-import mutation cannot remove the guard (the same integrity discipline is applied to every exported security-relevant collection: the baseline grant vocabularies, the credential-lifetime matrix, the session terminal states, the schema profile, and the broker floor are all frozen, and the minting-path consumers read private snapshots). The retirement barrier's cleaner authority is SPLIT into two per-operation credentials: a zero-write cleaner (its residual is terminal-free ACK suppression) and a settlement executor that alone holds the lease-record CAS and the lease-derived `wrk` terminal publish on the intent's exact pools plus the leader-served EPF and records fencing reads its own code path performs (NO EPW read: the settlement path settles or expires through the lease key before any EPW live-entry probe, so that read is unreachable and ungranted); the two are distinct CONNZ principals fenced independently before any frontier records, and the barrier runs settlement on the executor's own connection rather than its standing one. The retirement barrier is the `frontier.<lifecycleUid>` writer (the exact-arity `frontier.*` grant row), and the auth service's boot crash-resume finishes an owed retirement through the assembled deps (a per-endpoint short-lived drain client over the reviewed admission-mediator profile sharing the plane's sealed records scanner, and the per-op cleaner/executor split), fail-closed and loud like the takeover resume. Its re-verify round closed three composition gaps: the barrier now grants `STREAM.INFO` for exactly the CLOSED retirement-frontier stream set (the per-space lifecycle-data streams EPF/EPW/EPE/records, one source feeding both the intent validation and the grant, so a frontier read is never denied on a real broker nor a caller-selected arbitrary stream), the settlement executor drops the unreachable EPW live-entry read (the settlement path settles or expires through the lease key before any EPW probe, so that grant was dead), and the assembled drain completes every settleable obligation but fails CLOSED with an operator-legible frozen-not-lost message on accepted work that needs a confined commit-applier/route-reconciler authority (a scoped boundary whose full mechanics are a separate reviewed slice, never a broad records-write grant bolted onto the drain). A ninth round (the cross-process plane-ownership seal, \xA713.13) closed the last composition assumption the sealed scanners leaned on: at most one authority plane per space now holds them by a broker-visible claim, one exact never-deleted auth-KV `plane` row binding the two non-reconnecting scanner connections' broker identities, taken by create/revision-CAS with the candidates INERT until the win (no scan capability exists before it); a stale `held` row is reclaimed on LIVENESS ALONE (both claimed tuples conclusively absent under a COMPLETE connection sweep, adjudicated by the delivery daemon's closed read-only oracle over the delivery-admin rail; the auth process holds no `$SYS`), with no TTL, no heartbeat, and no sealed-scan-progress bit (a mid-scan crash reclaims; a paused-but-live plane keeps its connections and its ownership); the winner re-validates the claim before AND after every sealed scan (refuse or discard), an owned scanner disconnect fences the plane (invalidate exposure, close the sibling, never a transparent reconnect into a successor's consumer), clean close releases only after the scan clients are down, the three operator refusal faces carry distinct copy (live peer / inconclusive-fail-safe / mid-life fenced stop), and the launcher adds an exclusive-create pidfile belt. Its re-verify round hardened the reclaim and the fence: a `gone` verdict is valid only under the single-nats-server-process boundary, proven per observation from the responding server's own topology declaration in the `$SYS` reply envelope (any cluster self-report, multi-server observation, or missing declaration reads `unknown`; leafnode/gateway-extended accounts and backup-restore-onto-a-fresh-broker are named residuals; multi-server needs an incarnation/roster authority) \u2014 never inferred from which servers replied, which could neither be enforced by reply-counting (a partition shows one responder) nor flipped to require-the-claimed-server's-reply (a restarted server can never reply, the permanent-wedge horn); claim re-validation covers the two pinned scanner tuples (a tuple-only row rewrite is a lost claim); a scanner-death fence is FATAL to the whole authority plane (every authority operation refuses and the service exits loud, never a healthy-looking half-dead plane); the plane credentials' non-expiring boundary is normative (exactly the two non-reconnecting plane connections; every other authority credential keeps short-expiry + renewal); the claim row, connection tuple, oracle-query, and oracle-result schemas are closed exactly (unknown fields refuse, at every level); only successful well-formed CONNZ pages count toward a reclaim sweep (an API error, malformed envelope, non-string cluster declaration, id mismatch, or incomplete page poisons the observation); every sweep's reply inbox carries a per-call nonce (concurrent sweeps cannot cross-complete); the fenced plane's refusals are audience-split (a retryable unavailability to connecting agents, the state-3 restart copy to the operator's log and exit line); and the pidfile belt publishes atomically pre-populated (temp inode + no-overwrite `link(2)`; an empty slot is unpublishable and a pre-protocol one reclaims exactly once). A tenth round (the confined drain repairers) closed the retirement drain's accepted-work boundary functionally: the fail-closed applyCommit/reconcile interim is replaced by two per-op, per-repair principals \u2014 the COMMIT APPLIER (`local.epapl_<opId-hash>`, one exact records-KV publish row, minted only for a key inside the CLOSED self-commit class derived from the canonical frozen kind registry + the commit-path writer metadata, so a forged accepted-self row can never name an authority coordinate into a grant) and the POOL-ROUTE RECONCILER (`local.eprec_<opId-hash>`, one exact EPW item create-publish row, executing only a MEDIATOR-DERIVED closed repair command: the mediator reads and row-binds the durable acceptance decision itself and derives the exact subject + the \xA713.6 canonical acceptance item bytes, now a normative derivation so first enqueues and crash repairs are byte-identical) \u2014 each minted per repair, executed, closed, with the CAS-header and payload-blind residuals named per profile; an accepted self-commit now re-applies (or classifies landed/superseded) and an accepted pool route re-materializes, so a retirement with covered accepted work COMPLETES on resume, and an accepted EFFECTS route with no completion marker terminalizes through the RETIREMENT-CANCEL terminal (\xA713.8 option (i)): the effects completion fact becomes a closed two-member union (ran, or `cancelled: { opId, target }` \u2014 the same identity spine, never a forged success, written only for the retiring target's own acceptances), an action's goal union already carries the first-class `cancelled` state (the retirement attribution rides its digest-bound payload), the cancel publishes CREATE-ONLY on the SAME completion subject so first-terminal-wins is structural in both directions, and a third per-op principal (`local.epcan_<opId-hash>`, one exact completion-subject create row) executes the mediator-derived repair \u2014 so a retirement with in-flight accepted effects work now COMPLETES on resume with a reader-legible cancelled terminal instead of freezing. An eleventh round (the despawn\u2192retirement trigger, the P1 closure) reserved the `auth-admin` control service (SPEC 13.2): the AUTH plane serves the GENERIC \"retire a lifecycle\" operation on the `ctl` grammar's subject-attributed rail (the delivery-admin discipline: broker-ACL caller attribution, bound replies, an unbound reply target dropped before processing), authorized at SERVE TIME by the fresh space-manager-lease holder check (one leader-served read of the manager bucket's single lease key; holder == the subject-attributed requester principal; DEL/PURGE markers and TTL-expunged rows read absent and refuse fail-closed \u2014 never mint-time trust, closing the post-lease-loss window), answering the four-outcome idempotence table in operator vocabulary with every refusal a stated COMPLETE no-op; the space manager triggers it per despawn through an ephemeral request-and-reply-only `retirement-requester` credential with a STABLE per-lifecycle opId (retries, same-name-spawn nudges, and boot resumes converge on one operation), holds the despawned name RESERVED-pending-retirement until the terminal (a same-name spawn refuses legibly and re-drives the request; the in-memory reservation's restart residual is named \u2014 the durable truth is the lifecycle head itself), and the retirement executes through the plane's own reviewed deps over its ONE sealed records scanner. The barrier's terminal cleaner/executor pool set is the operation's EFFECTIVE INVENTORY: the target's accepted `oblig.<uid>.>` pool routes discovered from the just-drained obligation set UNIONED with the intent's OPTIONAL trusted hint (the despawn rail passes none), superseding the round-8 \"intent's exact pools\" enumeration so an empty-hint despawn still settles every accepted pool item before the frontier; the durable-intent hint is a TRUSTED ADDITIVE AUTHORITY input (a hinted pool with no accepted obligation still receives a bounded per-op credential), and the compromised cleaner/executor residuals scope to that whole effective inventory, including any hint-only pool. |\n| 2026-07-10 | **v0.4 binding revision: endpoint control surface (\xA713).** One standardized typed surface for every endpoint (manager, delivery, wrapped third-party servers): class/instance/scatter rails with per-command broker enforcement and an authorization-mode gradient, lifecycle identity (recyclable alias + never-reused lifecycle UID + fenced process epoch, \xA713.1, \xA72/\xA76/\xA78 extensions), versioned envelope with structured errors and signed slots, three delivery contracts (ephemeral, split-key records, untrusted submissions \u2192 mediated canonical facts), verbs call/cast/watch/claim/scatter (claim owner-mediated: workers hold no pool grant), composites (action, checkpoint, guard, capability handle with redemption-pinned `handle`-mode targets, session, virtual endpoints), content-addressed cluster contracts + governed traits + describe, the ownership matrix (incl. exact reader/consumer/ack rows and pinned consumer-name grammars), takeover/retirement revoke-and-evict barriers over the full ledgered credential family (credential ledger, \xA713.1), mediated timer arming (request/armed/fire split with a scheduler-origin fire check), poison quarantine facts, an epoch-pinned record-write ingress plane (`epr`), a single-message digest-subject contract store (`epc`), pre-created pull-only reader consumers (no dynamic reader creates: a create's delivery target is body-set and unconfined), an alias CAS head for lifecycle activation, and receipts and trust anchors. **Hard cut:** deletes the v0 `ctl` rail, `ControlRequest`/`ControlReply`, the `self`/`manager`/`admin`/`delivery-admin` tiers, and the reserved `control.<instance>` subject. `protocolVersion` targets `0.4` at migration completion; `1.0` stays reserved as a later stability declaration. |\n| 2026-07-07 | Documentation revision, no wire change: layered authority statement (schema authoritative for shapes, prose for semantics), document-snapshot policy and this change log (\xA711), reciprocal links to the informative docs. |\n| 2026-07-03 | **v0.3 binding revision: owner+actor identity.** The wire identity becomes the two-token principal `(owner, actor)`: subjects carry the sender as `<owner>.<actor>`, and grants, durables, presence, and `from.id` re-key onto the pair (\xA72, \xA73, \xA76, \xA78, \xA79). The connection nkey remains only the transport credential (the per-connection reply inbox). Adds the per-user-auth authorization grammar and the owner-token format (\xA72, \xA79). Supersedes the single-id grammar. |\n| 2026-06-21 | **v0.3 binding revision: channel live delivery.** Channel live delivery moves from the mediated per-instance live-tail durable to native `sub.allow`-bounded core subscriptions, with an explicit per-channel `live`/`durable` delivery class and the per-member durable backstop (\xA74, \xA77, \xA78); membership moves to a privileged-written registry (\xA77). Supersedes the v0.2 single-durable live-tail. |\n| earlier | v0.2 and before predate change control: the v0.2 contract (single mediated live-tail durable binding) is superseded by v0.3 and kept only in history. |\n"
   },
   "lang": {
     "title": "Cotal Lang: the workflow language",