@cotal-ai/connector-core 0.128.4 → 0.128.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { DocsBundle } from "./docs.js";
|
|
2
2
|
/** The installed Cotal version, for stamping the orientation card and other surfaces. */
|
|
3
|
-
export declare const DOCS_VERSION = "0.128.
|
|
3
|
+
export declare const DOCS_VERSION = "0.128.6";
|
|
4
4
|
export declare function loadDocsBundle(): DocsBundle;
|
|
5
5
|
//# sourceMappingURL=docs-bundle.generated.d.ts.map
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/** The installed Cotal version, for stamping the orientation card and other surfaces. */
|
|
2
|
-
export const DOCS_VERSION = "0.128.
|
|
2
|
+
export const DOCS_VERSION = "0.128.6";
|
|
3
3
|
export function loadDocsBundle() {
|
|
4
4
|
return {
|
|
5
|
-
"version": "0.128.
|
|
5
|
+
"version": "0.128.6",
|
|
6
6
|
"generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
|
|
7
7
|
"pages": [
|
|
8
8
|
{
|
|
@@ -123,7 +123,7 @@ export function loadDocsBundle() {
|
|
|
123
123
|
"kind": "Guide (informative)",
|
|
124
124
|
"category": "Guide",
|
|
125
125
|
"summary": "OpenAI Codex joins a Cotal mesh as a lateral peer: the same cotal tool surface, the same message delivery and attention model as the other connectors, plus mid-turn steering: a directed peer messag…",
|
|
126
|
-
"body": "# Connect Codex (beta)\n\n> **Guide** (informative) · **For:** operators · **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering: a directed peer message arriving during a\nconnector-started turn is **steered into that turn** instead of waiting for it to end.\nMessage batches arriving during a turn started in the attached TUI or by Codex itself,\nincluding a native goal continuation, wait for that turn to end before the connector starts\na delivery turn.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed` (or `cotal ext add @cotal-ai/connector-codex`) brings it in. Use\n`cotal ext seed --repair` when an earlier seed failed or was interrupted.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex # foreground in this terminal\ncotal spawn reviewer --agent codex -d # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --harness codex # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nThe catalog comes from a short-lived `codex app-server`, the binary a launch runs:\n`COTAL_CODEX_BIN` when you set it, otherwise the absolute path the manager resolved at boot.\nIf it exits, closes its input, or does\nnot answer `model/list` within 10 seconds, `cotal models` reports that as the Codex error and the\nmanager keeps serving the other connectors.\n\nModel and variant are published on presence, which is where the web dashboard's `model · variant`\nbadge reads them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n (DM, anycast, @mention) arriving during a connector-started turn is injected into that turn\n (`turn/steer`). During an externally started turn, the connector buffers the message and starts\n a delivery turn after the external turn ends. The external turn's completion cannot acknowledge\n a connector batch it did not carry. In focus mode, an @mention's pull hint can still steer an\n external turn; the message body stays on the inbox recall path. Ambient channel chatter waits\n for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n app-server is the MCP client, so the tools work the same on a turn a peer message started and\n on one **you** typed into the TUI.\n- **One managed conversation.** Only the thread the host drives can use its Cotal tools. Codex's\n native MCP request metadata identifies that thread, including turns typed in the attached TUI.\n Cotal tool calls from a second root thread are refused, rather than speaking with the managed\n conversation's identity. Native filesystem tools are not serialized across threads by Cotal.\n An app-server restart binds the replacement thread without creating a second mesh lifecycle.\n- **Ready means on the mesh.** The host announces `ready` and hands the terminal to Codex only\n after the app-server, MCP surface, and mesh endpoint are all live (including the initial\n presence publish). If the broker cannot be reached, startup fails within 15 seconds with the\n broker address and latest connection error; it never opens an offline-looking TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) when the turn\n completes, and also when the operator interrupts it (Escape in the attached TUI): that dismisses\n the batch rather than redelivering it. A failed turn retries with backoff, and an unknown terminal\n outcome (a missing or unrecognized status) leaves the batch un-acked with no retry of its own. If\n the Codex app-server itself dies, the host restarts it in place (same mesh identity, credential,\n and durable) and re-drives the un-acked batch into the new thread; a crash *loop* (more than 3 in\n 2 minutes) is fatal rather than an endless respawn. A retirement (the host shutting itself down)\n interrupts any live turn too, but that batch stays un-acked and redelivery to it is not promised:\n a later same-name spawn is a successor with its own delivery frontier. (The shared bounded-inbox\n overflow rule applies: under extreme bursts an evicted in-flight id cannot redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n wired through the isolated home; use the file store or the env key for managed agents. That\n symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n See [Sandbox autonomy](#sandbox-autonomy) for what each one means and how to\n change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n still available. In the foreground that is your terminal; detached it is the manager's pty,\n which is what `cotal attach` streams and drives. With no terminal at all (piped output,\n CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n way, only the UI differs.\n **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n wants deterministic text). The host refuses any value outside the on/off spellings in\n [Configuration](config.md#environment-variables) when it starts. It is read from the environment\n of **whichever process builds the launch**, so set it in the right place:\n - foreground `cotal spawn`: your own shell, per spawn;\n - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n which is what `cotal attach` streams.\n Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n `host.log` inside the agent's private home\n (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n approval requests relay an `approval` condition. A failed turn maps its native\n `codexErrorInfo` into the closed condition vocabulary and preserves that value in\n `condition.source`. Presence writes leave the host in the order the events arrived, so a\n turn that fails or asks for approval in the tick it started keeps its condition until the\n next turn starts. The model id is reported from the started thread.\n\n `contextWindowExceeded` maps to `context`; `sessionBudgetExceeded` to `budget`;\n `usageLimitExceeded` to `billing`; `rateLimitExceeded` to `rate_limit`;\n `serverOverloaded` to `overloaded`; `internalServerError` and `httpConnectionFailed` to\n `server`; `unauthorized` to `auth`; `badRequest`, `cyberPolicy`, and\n `misalignmentPolicyViolation` to `request`; and rollback, sandbox, `other`, or an unrecognized\n value to `failed`. An error marked `willRetry` maps to `retrying` while keeping its native source.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Event plane\n\nA spawned seat publishes a structured account of what it did: run\nboundaries per turn, assistant text, reasoning, and the tool calls the model makes through Codex's\nfunction-call and custom-tool interfaces, each with its start and its end. Tool arguments and\ntool results are not republished onto this channel. That covers the tools you watch a seat use,\n`shell` and `apply_patch` among them. The channel is\n`events.<owner>.<actor>`, named after the seat's principal, and the rules for it are the same on\nevery connector: see [connect-claude.md](connect-claude.md#event-plane) for the channel, the grant,\nand how to read it. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an\nunrestricted space. A registration that requires events refuses `--no-events`, and its launch\nalways carries the flag and the workspace root the event log lives under. A hand-driven user-mode\nlaunch with `COTAL_EVENTS_REQUIRED=1` arms the plane without that flag.\nYour own `codex` publishes nothing unless its environment arms the plane.\n\n```bash\ncotal spawn watcher --agent codex -d # event plane armed; read it with `cotal console`\n```\n\nEight things are specific to Codex and worth knowing before you read a stream:\n\n- **The thread's rollout file is the durable record.** The seat's\n rollout lives inside its own isolated `CODEX_HOME`, under\n `<workspace>/.cotal/codex/<space>-<name>-<hash>/sessions/<yyyy>/<mm>/<dd>/rollout-<stamp>-<thread>.jsonl`.\n Reading the file rather than the stream is what lets the seat resume a thread's stream where it\n stopped after its own process restarts, rather than reopening it from the top.\n- **A restarted app-server is a NEW thread, and its stream is a new one.** When the child dies and\n the seat brings up a replacement, Codex starts a fresh thread with a fresh rollout. The seat\n finishes the old one first, publishing what it had and closing any run left open, then begins\n publishing the new thread under its own write-ahead log. A reader sees one stream end and another\n begin, never one stream silently continuing under a different thread. If the new thread's file is\n slow to appear the order is the other way round: the seat spends its whole bounded look for the new\n file first, and the old stream ends when that look gives up, not at the moment of the restart. From\n the give-up on it publishes nothing until the new thread binds at a later turn boundary; it does not\n keep reporting the dead thread's activity in the meantime.\n- **The stream starts where the seat binds to the file.** `thread/start` writes nothing to disk; the\n file appears when the thread is primed. The seat binds to it then, and publishes from that point\n forward. If the file is slow to appear the seat says so in its log and looks again at each turn\n boundary, and whatever the thread wrote before the bind is not republished. A seat stopped before\n it binds leaves without binding.\n- **Codex's built-in tools remain private to the host.** Web search, tool search and image generation\n record an end with no start, and nothing joins the two halves: the start-shaped record carries no\n call id and the end carries one. Rather than guess a pairing, the seat drops them, so those tool\n uses are absent from the stream while everything on the function-call path is present.\n- **Failed turns publish run errors.** Codex records a failure on\n the turn's own completion record, so a turn that hit a usage limit or an upstream error ends its\n run with `RUN_ERROR` carrying the fixed message `run failed` and no code. Neither Codex's error\n text nor its `codex_error_info` is published there: both are upstream values that can echo your\n prompt or tool output, and the events channel has a different read ACL.\n- **No user-authored text is published, ever.** Your prompts, the peer messages injected into the\n thread, and the developer instructions the persona supplies are all withheld. The events channel\n carries a different read ACL from the channel you typed into, so republishing your own words there\n would widen who can read them. Assistant text, reasoning and tool activity are unaffected.\n- **A broker outage can stop the plane.** Initial mesh absence still\n fails the host's readiness gate within 15 seconds, so it never opens an offline-looking TUI. Once\n ready, the plane publishes through the seat's reconnecting mesh endpoint, and an outage can stop\n its emitter. The seat keeps running on every space, its log records `AG-UI emitter stopped` with\n the delay before the plane is re-established, and the thread publishes again from its stored\n cursor once that succeeds.\n Tool arguments and tool results are not published. The stream also does not carry the\n session's own record of the user's words and the developer instructions. A bind announces\n where the stream starts and the emitter's setup then runs before its first read; what the\n thread appends inside that window is published rather than left behind the cursor, and a whole\n turn can sit in there. Nothing is sent twice. The boundary itself is written to the log as soon\n as the bind succeeds, so a host that dies before its first read still resumes from that boundary\n rather than from wherever the file ends by the time it comes back.\n\n The grant still does not decide who may READ a plane. A spawn through the manager gives a seat\n publish rights on its own event channel and nothing else, and a spawn whose grant names a\n different agent's event channel is refused at the door. That fence is the manager's, it reads\n the concrete form and leaves a pattern such as `events.<owner>.>` to ordinary ACL authority,\n and a foreground `cotal spawn` on your own machine grants whatever you name because it mints\n from your own signing material. [connect-claude.md](connect-claude.md#event-plane) spells all\n three out. Who may READ a plane is minted separately and out of band either way, with\n `cotal actor grant` on a user-auth mesh and `cotal auth mint --profile agent --allow-subscribe` on a\n static one. Who may read the plane is still that mint, not the spawn grant.\n- **Reasoning is published as its summary only.** Codex also stores an encrypted reasoning blob on\n every reasoning record; it is opaque, no reader can display it, and it is never put on the wire.\n\n## Sandbox autonomy\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}' # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n run it as a separate OS user. See [Sandbox autonomy](#sandbox-autonomy).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n anything off-box. It is not isolation between *managed agents*, which run as the same user and\n can therefore reach each other's tokens; a hostile agent on your workstation could drive\n another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n way to reach a detached agent.\n- **`/new` does not replace the managed conversation.** The attached TUI can open a different\n thread, but the host keeps driving its original thread. Cotal tool calls from the other thread\n fail with an explanation naming the managed thread. Return to that thread in Codex, or spawn\n a separate Cotal seat for another conversation. There is no thread migration or hook recovery.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) · [Define a team](define-a-team.md) · [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) · [Connect Claude Code](connect-claude.md) · [Connect OpenCode](connect-opencode.md)\n"
|
|
126
|
+
"body": "# Connect Codex (beta)\n\n> **Guide** (informative) · **For:** operators · **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering: a directed peer message arriving during a\nconnector-started turn is **steered into that turn** instead of waiting for it to end.\nMessage batches arriving during a turn started in the attached TUI or by Codex itself,\nincluding a native goal continuation, wait for that turn to end before the connector starts\na delivery turn.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed` (or `cotal ext add @cotal-ai/connector-codex`) brings it in. Use\n`cotal ext seed --repair` when an earlier seed failed or was interrupted.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex # foreground in this terminal\ncotal spawn reviewer --agent codex -d # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --harness codex # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nThe catalog comes from a short-lived `codex app-server`, the binary a launch runs:\n`COTAL_CODEX_BIN` when you set it, otherwise the absolute path the manager resolved at boot.\nIf it exits, closes its input, or does\nnot answer `model/list` within 10 seconds, `cotal models` reports that as the Codex error and the\nmanager keeps serving the other connectors.\n\nModel and variant are published on presence, which is where the web dashboard's `model · variant`\nbadge reads them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n (DM, anycast, @mention) arriving during a connector-started turn is injected into that turn\n (`turn/steer`). During an externally started turn, the connector buffers the message and starts\n a delivery turn after the external turn ends. The external turn's completion cannot acknowledge\n a connector batch it did not carry. In focus mode, an @mention's pull hint can still steer an\n external turn; the message body stays on the inbox recall path. Ambient channel chatter waits\n for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n app-server is the MCP client, so the tools work the same on a turn a peer message started and\n on one **you** typed into the TUI.\n- **One managed conversation.** Only the thread the host drives can use its Cotal tools. Codex's\n native MCP request metadata identifies that thread, including turns typed in the attached TUI.\n Cotal tool calls from a second root thread are refused, rather than speaking with the managed\n conversation's identity. Native filesystem tools are not serialized across threads by Cotal.\n An app-server restart binds the replacement thread without creating a second mesh lifecycle.\n- **Ready means on the mesh.** The host announces `ready` and hands the terminal to Codex only\n after the app-server, MCP surface, and mesh endpoint are all live (including the initial\n presence publish). If the broker cannot be reached, startup fails within 15 seconds with the\n broker address and latest connection error; it never opens an offline-looking TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) when the turn\n completes, and also when the operator interrupts it (Escape in the attached TUI): that dismisses\n the batch rather than redelivering it. A failed turn retries with backoff, and an unknown terminal\n outcome (a missing or unrecognized status) leaves the batch un-acked with no retry of its own. If\n the Codex app-server itself dies, the host restarts it in place (same mesh identity, credential,\n and durable) and re-drives the un-acked batch into the new thread; a crash *loop* (more than 3 in\n 2 minutes) is fatal rather than an endless respawn. A retirement (the host shutting itself down)\n interrupts any live turn too, but that batch stays un-acked and redelivery to it is not promised:\n a later same-name spawn is a successor with its own delivery frontier. (The shared bounded-inbox\n overflow rule applies: under extreme bursts an evicted in-flight id cannot redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n wired through the isolated home; use the file store or the env key for managed agents. That\n symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n See [Sandbox autonomy](#sandbox-autonomy) for what each one means and how to\n change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n still available. In the foreground that is your terminal; detached it is the manager's pty,\n which is what `cotal attach` streams and drives. With no terminal at all (piped output,\n CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n way, only the UI differs.\n **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n wants deterministic text). The host refuses any value outside the on/off spellings in\n [Configuration](config.md#environment-variables) when it starts. It is read from the environment\n of **whichever process builds the launch**, so set it in the right place:\n - foreground `cotal spawn`: your own shell, per spawn;\n - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n which is what `cotal attach` streams.\n Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n `host.log` inside the agent's private home\n (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n a user-input request's temporary waiting presence does not end the host turn. A completed\n native turn still yields `done` for its surfaced workflow turn after the host answers a\n user-input request, even if no later command or MCP item runs. Explicit `blocked` and\n `handoff` yields remain unchanged.\n Approval requests relay an `approval` condition. A failed turn maps its native\n `codexErrorInfo` into the closed condition vocabulary and preserves that value in\n `condition.source`. Presence writes leave the host in the order the events arrived, so a\n turn that fails or asks for approval in the tick it started keeps its condition until the\n next turn starts. The model id is reported from the started thread.\n\n `contextWindowExceeded` maps to `context`; `sessionBudgetExceeded` to `budget`;\n `usageLimitExceeded` to `billing`; `rateLimitExceeded` to `rate_limit`;\n `serverOverloaded` to `overloaded`; `internalServerError` and `httpConnectionFailed` to\n `server`; `unauthorized` to `auth`; `badRequest`, `cyberPolicy`, and\n `misalignmentPolicyViolation` to `request`; and rollback, sandbox, `other`, or an unrecognized\n value to `failed`. An error marked `willRetry` maps to `retrying` while keeping its native source.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Event plane\n\nA spawned seat publishes a structured account of what it did: run\nboundaries per turn, assistant text, reasoning, and the tool calls the model makes through Codex's\nfunction-call and custom-tool interfaces, each with its start and its end. Tool arguments and\ntool results are not republished onto this channel. That covers the tools you watch a seat use,\n`shell` and `apply_patch` among them. The channel is\n`events.<owner>.<actor>`, named after the seat's principal, and the rules for it are the same on\nevery connector: see [connect-claude.md](connect-claude.md#event-plane) for the channel, the grant,\nand how to read it. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an\nunrestricted space. A registration that requires events refuses `--no-events`, and its launch\nalways carries the flag and the workspace root the event log lives under. A hand-driven user-mode\nlaunch with `COTAL_EVENTS_REQUIRED=1` arms the plane without that flag.\nYour own `codex` publishes nothing unless its environment arms the plane.\n\n```bash\ncotal spawn watcher --agent codex -d # event plane armed; read it with `cotal console`\n```\n\nEight things are specific to Codex and worth knowing before you read a stream:\n\n- **The thread's rollout file is the durable record.** The seat's\n rollout lives inside its own isolated `CODEX_HOME`, under\n `<workspace>/.cotal/codex/<space>-<name>-<hash>/sessions/<yyyy>/<mm>/<dd>/rollout-<stamp>-<thread>.jsonl`.\n Reading the file rather than the stream is what lets the seat resume a thread's stream where it\n stopped after its own process restarts, rather than reopening it from the top.\n- **A restarted app-server is a NEW thread, and its stream is a new one.** When the child dies and\n the seat brings up a replacement, Codex starts a fresh thread with a fresh rollout. The seat\n finishes the old one first, publishing what it had and closing any run left open, then begins\n publishing the new thread under its own write-ahead log. A reader sees one stream end and another\n begin, never one stream silently continuing under a different thread. If the new thread's file is\n slow to appear the order is the other way round: the seat spends its whole bounded look for the new\n file first, and the old stream ends when that look gives up, not at the moment of the restart. From\n the give-up on it publishes nothing until the new thread binds at a later turn boundary; it does not\n keep reporting the dead thread's activity in the meantime.\n- **The stream starts where the seat binds to the file.** `thread/start` writes nothing to disk; the\n file appears when the thread is primed. The seat binds to it then, and publishes from that point\n forward. If the file is slow to appear the seat says so in its log and looks again at each turn\n boundary, and whatever the thread wrote before the bind is not republished. A seat stopped before\n it binds leaves without binding.\n- **Codex's built-in tools remain private to the host.** Web search, tool search and image generation\n record an end with no start, and nothing joins the two halves: the start-shaped record carries no\n call id and the end carries one. Rather than guess a pairing, the seat drops them, so those tool\n uses are absent from the stream while everything on the function-call path is present.\n- **Failed turns publish run errors.** Codex records a failure on\n the turn's own completion record, so a turn that hit a usage limit or an upstream error ends its\n run with `RUN_ERROR` carrying the fixed message `run failed` and no code. Neither Codex's error\n text nor its `codex_error_info` is published there: both are upstream values that can echo your\n prompt or tool output, and the events channel has a different read ACL.\n- **No user-authored text is published, ever.** Your prompts, the peer messages injected into the\n thread, and the developer instructions the persona supplies are all withheld. The events channel\n carries a different read ACL from the channel you typed into, so republishing your own words there\n would widen who can read them. Assistant text, reasoning and tool activity are unaffected.\n- **A broker outage can stop the plane.** Initial mesh absence still\n fails the host's readiness gate within 15 seconds, so it never opens an offline-looking TUI. Once\n ready, the plane publishes through the seat's reconnecting mesh endpoint, and an outage can stop\n its emitter. The seat keeps running on every space, its log records `AG-UI emitter stopped` with\n the delay before the plane is re-established, and the thread publishes again from its stored\n cursor once that succeeds.\n Tool arguments and tool results are not published. The stream also does not carry the\n session's own record of the user's words and the developer instructions. A bind announces\n where the stream starts and the emitter's setup then runs before its first read; what the\n thread appends inside that window is published rather than left behind the cursor, and a whole\n turn can sit in there. Nothing is sent twice. The boundary itself is written to the log as soon\n as the bind succeeds, so a host that dies before its first read still resumes from that boundary\n rather than from wherever the file ends by the time it comes back.\n\n The grant still does not decide who may READ a plane. A spawn through the manager gives a seat\n publish rights on its own event channel and nothing else, and a spawn whose grant names a\n different agent's event channel is refused at the door. That fence is the manager's, it reads\n the concrete form and leaves a pattern such as `events.<owner>.>` to ordinary ACL authority,\n and a foreground `cotal spawn` on your own machine grants whatever you name because it mints\n from your own signing material. [connect-claude.md](connect-claude.md#event-plane) spells all\n three out. Who may READ a plane is minted separately and out of band either way, with\n `cotal actor grant` on a user-auth mesh and `cotal auth mint --profile agent --allow-subscribe` on a\n static one. Who may read the plane is still that mint, not the spawn grant.\n- **Reasoning is published as its summary only.** Codex also stores an encrypted reasoning blob on\n every reasoning record; it is opaque, no reader can display it, and it is never put on the wire.\n\n## Sandbox autonomy\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}' # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n run it as a separate OS user. See [Sandbox autonomy](#sandbox-autonomy).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n anything off-box. It is not isolation between *managed agents*, which run as the same user and\n can therefore reach each other's tokens; a hostile agent on your workstation could drive\n another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n way to reach a detached agent.\n- **`/new` does not replace the managed conversation.** The attached TUI can open a different\n thread, but the host keeps driving its original thread. Cotal tool calls from the other thread\n fail with an explanation naming the managed thread. Return to that thread in Codex, or spawn\n a separate Cotal seat for another conversation. There is no thread migration or hook recovery.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) · [Define a team](define-a-team.md) · [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) · [Connect Claude Code](connect-claude.md) · [Connect OpenCode](connect-opencode.md)\n"
|
|
127
127
|
},
|
|
128
128
|
{
|
|
129
129
|
"slug": "connect-hermes",
|
|
@@ -171,7 +171,7 @@ export function loadDocsBundle() {
|
|
|
171
171
|
"kind": "Concept (informative)",
|
|
172
172
|
"category": "Concept",
|
|
173
173
|
"summary": "Cotal once had a privileged control rail: a fixed set of named service tiers (self / manager / admin / delivery) on their own ctl.",
|
|
174
|
-
"body": "# The control surface\n\n> **Concept** (informative) · **For:** operators and client authors who want to know how the manager and other daemons are driven · **Normative:** [SPEC §13](../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\nOne part of the old rail is still served in the reference implementation. The delivery daemon\nanswers agents' durable join, leave and membership-list requests on `ctl.delivery.<owner>.<actor>`\nand the manager's admin requests on `ctl.delivery-admin.<owner>.<actor>`\n([delivery daemon](delivery-daemon.md)). [SPEC §13.11](../SPEC.md#1311-the-hard-cut) retires every\n`ctl` subject and §7 places the durable join on the `delivery` endpoint, so these two rails are\nimplementation residue the spec does not define.\n\nFor a starting point across the integration interfaces, see the [API reference](api-reference.md).\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 §13.2](../SPEC.md#132-grammar) for the grammar and [§13.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 §13.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`. An\nendpoint that refuses a request before running the command states `not-executed` in the reply's\n`error.outcome` too, for example on a wrong envelope version, sender, contract digest or target\nmode, or a body that does not parse. A refusal the command itself raises carries only the\noutcome it states. A refusal that does not serialize comes back as `internal`, and one too large\nto publish as `resource-exhausted`, and both keep that outcome. 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 §13.7](../SPEC.md#137-contracts-and-discovery) and [cli.md](cli.md).\n\nThe manager's `vitals` command reports one invocation-time sample of host CPU count and load,\navailable and total memory, and bounded local filesystem capacity. It is untargeted but resolves to\none exact Manager instance. The separate `manager.vitals` capability is issued only when the actor\nscope contains `machine-vitals`; `spawn`, `run` and `admin` do not imply it. The response contains\nmount points and aggregate byte counts, never device paths, remote endpoints, process data, command\nlines, environment values or persisted history. Unsupported measurement refuses without a partial\nor zero-valued fallback.\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. It is\nminted beside `spawn` in the operator instruments, which are the caller on a static mesh, and in a\n`spawn` holder's `manager-caller` view. The standing agent `spawn` capability does not carry it.\nA runtime that delegates seats outside the manager's host cannot use a host cwd. Its manager\nrefuses `resolve-cwd` with `failed-precondition` before any filesystem lookup, with the same\nexecution-mode refusal for every path. It returns no host name or canonical path.\n\nThe manager's `resolve-agent` command is minted beside `spawn` in the spawn capability and the\noperator instruments. It accepts the persona fields `spawn` takes (`name`, `config`, `agent`,\n`defaultAgent`) and returns `{agent}`, the harness `spawn` on that manager would launch: the flag,\nthen the persona's `agent:` pin, then the caller's default, then the manager's own default. It loads\nthe persona with the same visibility check as `spawn` and launches nothing. A detached `--resume`\nwithout `--agent` asks it before carrying a session, and a manager that does not serve it refuses\nthe call.\n\nOn a delegated runtime, both `resolve-agent` and `spawn` refuse an explicit persona `config`\nbefore any lookup of that path. Absolute, relative and bare-name config overrides receive the\nsame `failed-precondition` refusal. Select a named catalog persona through `name` instead.\nLocally executing managers retain their config-path behavior. A resolved manifest uses its own\nvalidated, host-materialized persona resource and is not a caller-selected config override.\n\n`spawn` refuses an empty or whitespace-only value in any of its optional string fields, such as\n`role`, `agent` or `identity`, with `bad-request` naming the field. To take the persona file's value,\nomit the field.\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`. A named `cotal_despawn` resolves its target through this read\nand cannot address an instance, so it asks again until the owning instance answers, up to 16\ntimes.\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.\nWith no arguments, retired rows remain excluded. From manager cluster revision 32,\n`{names: [\"worker\"], includeRetired: true}` point-reads up to 100 distinct aliases and\nincludes their retired rows. An absent or sibling-owned slot is omitted, not reported\nas retired. Each returned row retains its principal, lifecycle UID, slot/head revisions,\nphase and any native cleanup-complete fact. Consumers must match every requested\nincarnation; a missing live row or an accepted stop is not a retirement result.\n`live` reflects the manager's live roster at render time, not the durable row. A slot row\nis never deleted, so a row whose latest operation is a DEL or PURGE marker is corruption:\nthe list answers `unavailable` naming that row, as `inspect` does for its name.\n\n### Static chat sessions\n\nFrom manager cluster revision 34, a static manager admits chat sessions with\n`chat-session-open` and ends them with `chat-session-retire`. Both are untargeted and in the\n`manager.chat` class. Only operator instruments carry their rows; the `spawn` and `run`\ncapabilities do not. A user-mode or open manager refuses both with `unimplemented`.\n\n`chat-session-open` takes `{subscribe, allowSubscribe, allowPublish, label, ttl, sealTo}`. The\nthree lists are a spawn's, under a spawn's rules: `subscribe` is the session's initial channels,\n`allowSubscribe` its read ceiling (empty means `subscribe`, and `subscribe` must lie within it),\nand `allowPublish` its post list (empty means none). Each may be omitted. A session can join any\nchannel under its ceiling, patterns included. A concrete event channel of another principal is\nrefused, as it is for a spawn. The manager draws a `chat_<26 base32>` alias and a fresh nkey\nidentity, runs the static slot activation, provisions the session's DM and DELIVER durables and\nACL row, and mints an agent-profile leaf with no role, capabilities, endpoint rows or issuance.\nThe leaf expires after `ttl` seconds, at most 900, and is never renewed. Because the leaf is not\nan issuance, the manager writes its credential ledger row itself before the credential leaves the\nprocess, and that row is what retirement marks revoked and verify-evicts.\n\n`sealTo` is a one-time curve public key (`X…`) the caller mints and keeps the private half of. The\nreply is `{alias, actor, lifecycleUid, expiresAt, sealer, sealed}`: `actor` is the nkey the\nbroker authenticates, `alias` names the slot, and `expiresAt` is in epoch milliseconds. The\ncredential is not in the reply in the clear. `sealed` is base64url, sealed to `sealTo` from the\none-time `sealer` key with the NATS xkey format, and opens to the credential bound to the space,\nthe admitting manager instance and every field of the reply. A generic invoke, an agent or a\nbrowser sees only that ciphertext. The chat adapter opens it once, refuses it unless every bound\nfield matches, and keeps the credential in memory.\n\n`chat-session-retire` takes `{alias, actor, lifecycleUid}` and runs the static terminal. It refuses\nbefore any effect unless the alias is a chat alias whose slot this manager instance owns at that\nuid and actor. It answers `retired`, `alreadyRetired`, or `failed` with a `retirement pending:`\nreason while the slot stays held. Retirement marks the credential's ledger row revoked, verifies\nthat the session's principal has no broker connection left, tears down its broker footprint and\nretires the slot. A static mesh has no broker-side credential revocation, so a copy of the leaf\ncan still connect with the permissions it carries until its expiry. An ordinary spawn refuses any\nname that starts with `chat_`.\n\nThe manager that admitted a session retires it at its expiry when nothing retired it sooner, so a\nlost reply or an abandoned client does not hold the slot. Its stop retires every session it still\nholds, with or without its agents, and names each one it could not retire; a stop that preserves\nthe manager's state leaves them. Its own startup sweep never retires a session it is admitting or\nholds. A session that none of these retired stays held until the next start of that manager\ninstance.\n\n## Persona write observation\n\nThe Manager serves `define-persona` and `remove-persona` under `manager.persona`. Removal takes\n`{name}` and returns `{name}`. It deletes only the machine-local definition, not agents already\nrunning from it. A missing definition is `not-found`. The name may exceed the current 64-character\nspawn limit, provided it is still a safe catalog filename stem, so an invalid legacy definition can\nbe removed.\n\nAn unanswered `define-persona` or `remove-persona` command does not prove the write did not land.\nThe caller must read the catalog again on the same manager before acting. The write may still land\nafter the wait ends, so a missing readback alone does not make another write safe. A failed describe,\nbroker no-responders answer or explicit pre-effect refusal remains a failure, not an unknown write.\n\n## Spawn is a goal\n\nLong-running commands are **actions** ([SPEC §13.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_2\", \"uid\": \"...\",\n \"goalId\": \"...\", \"fingerprint\": \"...\",\n \"readinessDeadlineMs\": 30000,\n \"executor\": { \"lifecycleUid\": \"...\", \"epoch\": 3 }\n}\n```\n\nThe `uid` is the lifecycle the agent runs at. On a participant manager whose host enrolls its\nagents, the host picks that uid, so the manager accepts the goal only after the host has answered.\nA host refusal there refuses the spawn, and no goal is bound.\n\nResubmitting the same `goalId` returns the same acceptance. A `goalId` belongs to the caller that\nsubmitted it, so another caller's spawn under the same id is its own goal with its own\nacceptance. A sibling instance or a restarted one\nanswers it from the identity the accepting instance recorded before it replied, owner included.\nWhen that record names no owner because an older manager wrote it, the resubmission is refused\n`unavailable`. Once the goal has ended, the accepting manager keeps its acceptance for five more\nminutes. After that, and at any other instance, the resubmission is answered from the goal's\nterminal and never accepted again: a `succeeded` terminal names the agent, so it returns the same\nacceptance, and any other outcome refuses it `failed-precondition` with that terminal attached.\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 follower keeps the acceptance as the data of any\nterminal other than `succeeded`, so `cotal_spawn` returns an uncertain launch as a pending result\ninstead of an error: it names the allocated agent, its id, and its manager, and tells the calling\nagent to watch the roster. 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\nThe manager keeps a spawn or launch exception's error code and details when turning it\ninto a refusal. Failed `ControlReply` values keep their code and details at the serving\nboundary. A host enrollment refusal that proves nothing was executed also keeps its\ncode in the public `Manager.startAgent` reply after staged-secret cleanup. A reply\nwithout a code remains `failed-precondition`.\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. The CLI and the connector tools hand a\nrefusal on in one shape, so `cotal spawn --detach` keeps the same code, details, rendered facts\nand acceptance data as `cotal_spawn`. 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 mesh or from an unbound open caller, an untargeted spawn rides class anycast\n(any manager may accept, and the acceptance records which one did). An open managed seat's\npersona definition, list, show and spawn tools default to its launching manager. Its generic\nmanager describe and self-targeted invoke use that launch address too. An explicit existing\npersona or spawn selector still selects that instance. Static credential grants and user-auth\nissuer selection are unchanged. For self-stop, persona definition and direct spawn, a static managed\nseat keeps its class-only credential and accepts only its launching manager's attributed describe\nreply. These commands retain that bind on the class rail, so a sibling refuses before effects and\nthe existing bounded split repair asks again. An absent launching manager never selects a replacement.\nThe library's `describeService` accepts an optional `instanceId`;\na pinned describe does not read or populate the endpoint-only class cache.\n`cotal spawn <persona> --detach --on <instance>` and `cotal_spawn(instance: \"<instance>\")`\npin one instance by its exact id, as `--on` does for `cotal ps`, `cotal models` and every hosted\n`cotal run` verb, and `instance` for `cotal_run`, `cotal_persona` and `cotal_personas`. 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 or class queue. It adds no command capability except the\nthree reads a launch needs: a view whose actor holds `spawn` may call `status`, `models` and\n`resolve-cwd` on that instance, subject to the execution-mode limit above. A `run`-only or no-scope view may not, and `ps` and `slots` stay with\n`admin`. A user mesh's co-located manager answers every owner's view, so its `status` counts only the\ncaller's own seats, as `ps` would list them, unless the caller holds `admin`. An absent,\nambiguous or unauthorized selection refuses before the command is sent. An ambiguous one lists the\nowner's live manager instance ids and names the caller's way to pick one: `--on <instanceId>` for\nthe CLI, `--manager-instance <instanceId>` for `cotal agent-bearer --manager-call`, and the\n`instance` argument for an agent's tools.\nA pin changes routing, not the caller's grant.\n\nEach `status.connectors` row includes `eventPlane: boolean`. The value is true only when the\nconnector declares the event channel it publishes. Installed-extension rows carry the cached fact\nbefore the package is imported, and an old inventory without it is refused rather than treated as\ntrue. A client that reads a required event policy can use this field to disable an incompatible\nconnector before spawn. The Manager still owns the launch refusal text and applies it at admission.\n\nManaged launches carry `COTAL_MANAGER_INSTANCE` so their tools address the manager that launched\nthem; a tool's `instance` argument must name that same manager. The `cotal` commands run from their\nshell select it too, unless `--on` names another instance. 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 reference `cotal_spawn` tool retains the published request id when its submission wait\nends before acceptance is observed. That id is the manager's goal id if the submission is\naccepted later. The tool reports an unknown outcome with the id and a same-caller\n`goal-result` read, without claiming that acceptance occurred. Do not repeat the spawn.\nAn unanswered describe or a broker-attested no-responder refusal does not create a goal\nhandle. A missing readback is inconclusive while the original submission may still arrive.\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\nThe manager's reserved `cancel` command accepts `{goalId, mode?}` and returns `{goalId, state}`.\nIt is served for a turn the manager relays. The goal is the authenticated caller's own, so a caller\nwithdraws only a turn it submitted. The turn ends `cancelled`, its seat is not shown it again, and a\nlater yield of it is answered with that terminal. A goal that already ended is refused\n`failed-precondition` with its cached outcome attached, and a goal this manager does not relay is\nrefused without being changed. So is a second cancel that arrives while a first is still ending the\nturn; a first that fails leaves the turn pending unless something ended it meanwhile. A workflow\nrun sends it for the turn, ask attempt or escalation of a branch it cancelled.\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\nA followed call resolves the endpoint within its deadline before the submission starts, so a\nrefused or unanswered describe surfaces as its own error. On a user-auth mesh that preparation also\nobtains the caller's `manager-caller` view and opens its connection, and a failure there surfaces\nunchanged. The control connection uses the remaining preparation deadline, including time spent\nobtaining the bearer, rather than a separate two-second limit. A deadline that passes during those\nsteps reports that the request was not run. The\ndescribe then spends what is left of the deadline, so a describe that draws no reply still reports\nitself as unanswered.\nA describe or command publish that the broker refuses reports `not-executed`.\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 --no-manager` on that host starts no\nmanager, and `cotal supervise --server` runs the manager elsewhere ([Run a mesh](run-a-mesh.md)).\nA broker host that already runs a manager stops it only after `✓ manager up` in\n`.cotal/manager.<spaceKey>.log` (detach stdout listing `manager` is pidfile liveness, not a\nteardown boundary). A controller stack stops it with\n`cotal service stop stack-manager --space <s> --yes`; a legacy stack has no command that stops only\nits manager. Extra live managers are 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 describe and the contract store reads after it share the resolver's one deadline, so a slow\nstore read fails the resolve with `deadline-exceeded` when that deadline expires. `cotal invoke` passes its\n`--timeout` as that deadline (default 10000 ms) and gives the reply what the resolve leaves of it.\n`cotal describe` has no `--timeout` and passes 10000 ms. Cancelling a\nresolve settles a store read in flight instead of waiting for it to return. When one store read\nfails, the resolve fails with it and fetches no further command contracts; fetches already under\nway finish on their own. A call for one command fetches only that command's cluster and schema\nclosures. `describe` still fetches the complete visible surface because its result lists every\ncommand.\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`, the `cotal run` verbs and the manager row of\n`cotal status` re-describe and re-issue an unpinned call after each such refusal, up to 16 times,\nso a split reaches the operator only when every attempt split. A hosted run's own manager calls\nuse the same bound. A pinned call is never re-issued. An agent's own manager\ntools, such as `cotal_spawn` and `cotal_despawn`, re-describe and re-issue with the same bound,\nincluding the goal-result read that follows a spawn to its outcome.\n\nAn unpinned targeted call, such as `cotal_despawn` or a hosted run's turn relay, can also reach a\nmanager that does not host its target, because each manager resolves targets against the agents\nit runs. That manager refuses with `expired` and `not-executed` and says it holds no mapping for\nthe target, and the same re-issue repairs it within the same bound. An agent that no manager hosts\nstill ends in that refusal once the re-issues run out. A pinned call gets the refusal of the\ninstance it named.\n\nA verified Manager `status` reply includes `host`, the answering process's host name, and\n`version`, the running `@cotal-ai/manager` package version captured when its module loaded.\nThese fields are advisory display metadata. They do not select a Manager, authorize a caller\nor determine placement. Use the verified responder's `instanceId` for attribution. Clients\nmust accept status payloads that omit either field and leave the missing value unknown.\nThe optional fields advance the Manager cluster revision to 28.\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.\nWhen no manager takes the class queue, the broker answers an unpinned `spawn` with no\nresponders, and the caller classifies that `not-executed` (SPEC 13.3).\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 §13.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 §13.5](../SPEC.md#135-verbs): a deleted `svc` spec *is* the deregistration).\n\nA manager that stops cleanly removes its own registration, so an ordinary shutdown leaves no stale\nrow. The delete is pinned to the registration revision that process wrote. When a successor has\nregistered the same instance since then, the stop logs that and leaves the successor's registration\nalone. It refuses that delete while this instance holds the endpoint governance slot at the live\nissuance-gate generation (a registration still completing its reopen). A leftover slot whose\ngeneration is behind that live generation is not in-flight and does not block the stop. A manager\nthat cannot renew or read its lease keeps serving, stays registered, and retries. If another process\nholds the same instance key, that process has taken the instance over, so this one logs the conflict\nand exits without deregistering, leaving the successor'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.\nOnce that reopen commits, the registration has completed: a governance slot it then fails to release\nis left behind the live generation, as on a normal registration, and does not fail the restart.\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 endpoint deregister <endpoint> <full-instance-id>`\n([cli.md](cli.md#endpoint-deregister)). 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. `cotal attach`\nreconnects when its link dies by asking the manager for a new session\n([CLI](cli.md#managed-seats)).\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\". Both refusals carry `not-executed`, because nothing was typed. A write the\nruntime rejects once delivery has started states no outcome, so a caller reads it as `unknown`.\nThe manager's other control refusals follow the same rule: one raised before the command's first\neffect, such as a denied caller, a stale target or a missing persona file, carries `not-executed`.\nSee [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 §13.9](../SPEC.md#139-authority-boundary) and\n[identity & auth](identity-and-auth.md).\n\nA carried resume transcript never rides the rails. The operator-only `transcript-receive` command\nanswers whether to upload and hands back a one-time claim for `spawn`, and the bytes travel through\nthe target instance's own transfer bucket under two one-shot credentials: a writer the operator\nmints for that one transcript, and a reader the target instance mints for its own bucket, or that\nthe host issues a remote manager through its `transferReader` authority operation.\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 §13](../SPEC.md#13-endpoint-control-surface-v04), the normative contract.\n"
|
|
174
|
+
"body": "# The control surface\n\n> **Concept** (informative) · **For:** operators and client authors who want to know how the manager and other daemons are driven · **Normative:** [SPEC §13](../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\nOne part of the old rail is still served in the reference implementation. The delivery daemon\nanswers agents' durable join, leave and membership-list requests on `ctl.delivery.<owner>.<actor>`\nand the manager's admin requests on `ctl.delivery-admin.<owner>.<actor>`\n([delivery daemon](delivery-daemon.md)). [SPEC §13.11](../SPEC.md#1311-the-hard-cut) retires every\n`ctl` subject and §7 places the durable join on the `delivery` endpoint, so these two rails are\nimplementation residue the spec does not define.\n\nFor a starting point across the integration interfaces, see the [API reference](api-reference.md).\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 §13.2](../SPEC.md#132-grammar) for the grammar and [§13.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 §13.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`. An\nendpoint that refuses a request before running the command states `not-executed` in the reply's\n`error.outcome` too, for example on a wrong envelope version, sender, contract digest or target\nmode, or a body that does not parse. A refusal the command itself raises carries only the\noutcome it states. A refusal that does not serialize comes back as `internal`, and one too large\nto publish as `resource-exhausted`, and both keep that outcome. 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 §13.7](../SPEC.md#137-contracts-and-discovery) and [cli.md](cli.md).\n\nThe manager's `vitals` command reports one invocation-time sample of host CPU count and load,\navailable and total memory, and bounded local filesystem capacity. It is untargeted but resolves to\none exact Manager instance. The separate `manager.vitals` capability is issued only when the actor\nscope contains `machine-vitals`; `spawn`, `run` and `admin` do not imply it. The response contains\nmount points and aggregate byte counts, never device paths, remote endpoints, process data, command\nlines, environment values or persisted history. Unsupported measurement refuses without a partial\nor zero-valued fallback.\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. It is\nminted beside `spawn` in the operator instruments, which are the caller on a static mesh, and in a\n`spawn` holder's `manager-caller` view. The standing agent `spawn` capability does not carry it.\nA runtime that delegates seats outside the manager's host cannot use a host cwd. Its manager\nrefuses `resolve-cwd` with `failed-precondition` before any filesystem lookup, with the same\nexecution-mode refusal for every path. It returns no host name or canonical path.\n\nThe manager's `resolve-agent` command is minted beside `spawn` in the spawn capability and the\noperator instruments. It accepts the persona fields `spawn` takes (`name`, `config`, `agent`,\n`defaultAgent`) and returns `{agent}`, the harness `spawn` on that manager would launch: the flag,\nthen the persona's `agent:` pin, then the caller's default, then the manager's own default. It loads\nthe persona with the same visibility check as `spawn` and launches nothing. A detached `--resume`\nwithout `--agent` asks it before carrying a session, and a manager that does not serve it refuses\nthe call.\n\nOn a delegated runtime, both `resolve-agent` and `spawn` refuse an explicit persona `config`\nbefore any lookup of that path. Absolute, relative and bare-name config overrides receive the\nsame `failed-precondition` refusal. Select a named catalog persona through `name` instead.\nLocally executing managers retain their config-path behavior. A resolved manifest uses its own\nvalidated, host-materialized persona resource and is not a caller-selected config override.\n\n`spawn` refuses an empty or whitespace-only value in any of its optional string fields, such as\n`role`, `agent` or `identity`, with `bad-request` naming the field. To take the persona file's value,\nomit the field.\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`. A named `cotal_despawn` resolves its target through this read\nand cannot address an instance, so it asks again until the owning instance answers, up to 16\ntimes.\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.\nWith no arguments, retired rows remain excluded. From manager cluster revision 32,\n`{names: [\"worker\"], includeRetired: true}` point-reads up to 100 distinct aliases and\nincludes their retired rows. An absent or sibling-owned slot is omitted, not reported\nas retired. Each returned row retains its principal, lifecycle UID, slot/head revisions,\nphase and any native cleanup-complete fact. Consumers must match every requested\nincarnation; a missing live row or an accepted stop is not a retirement result.\n`live` reflects the manager's live roster at render time, not the durable row. A slot row\nis never deleted, so a row whose latest operation is a DEL or PURGE marker is corruption:\nthe list answers `unavailable` naming that row, as `inspect` does for its name.\n\n### Static chat sessions\n\nFrom manager cluster revision 34, a static manager admits chat sessions with\n`chat-session-open` and ends them with `chat-session-retire`. Both are untargeted and in the\n`manager.chat` class. Only operator instruments carry their rows; the `spawn` and `run`\ncapabilities do not. A user-mode or open manager refuses both with `unimplemented`.\n\n`chat-session-open` takes `{subscribe, allowSubscribe, allowPublish, label, ttl, sealTo}`. The\nthree lists are a spawn's, under a spawn's rules: `subscribe` is the session's initial channels,\n`allowSubscribe` its read ceiling (empty means `subscribe`, and `subscribe` must lie within it),\nand `allowPublish` its post list (empty means none). Each may be omitted. A session can join any\nchannel under its ceiling, patterns included. A concrete event channel of another principal is\nrefused, as it is for a spawn. The manager draws a `chat_<26 base32>` alias and a fresh nkey\nidentity, runs the static slot activation, provisions the session's DM and DELIVER durables and\nACL row, and mints an agent-profile leaf with no role, capabilities, endpoint rows or issuance.\nThe leaf expires after `ttl` seconds, at most 900, and is never renewed. Because the leaf is not\nan issuance, the manager writes its credential ledger row itself before the credential leaves the\nprocess, and that row is what retirement marks revoked and verify-evicts.\n\n`sealTo` is a one-time curve public key (`X…`) the caller mints and keeps the private half of. The\nreply is `{alias, actor, lifecycleUid, expiresAt, sealer, sealed}`: `actor` is the nkey the\nbroker authenticates, `alias` names the slot, and `expiresAt` is in epoch milliseconds. The\ncredential is not in the reply in the clear. `sealed` is base64url, sealed to `sealTo` from the\none-time `sealer` key with the NATS xkey format, and opens to the credential bound to the space,\nthe admitting manager instance and every field of the reply. A generic invoke, an agent or a\nbrowser sees only that ciphertext. The chat adapter opens it once, refuses it unless every bound\nfield matches, and keeps the credential in memory.\n\n`chat-session-retire` takes `{alias, actor, lifecycleUid}` and runs the static terminal. It refuses\nbefore any effect unless the alias is a chat alias whose slot this manager instance owns at that\nuid and actor. It answers `retired`, `alreadyRetired`, or `failed` with a `retirement pending:`\nreason while the slot stays held. Retirement marks the credential's ledger row revoked, verifies\nthat the session's principal has no broker connection left, tears down its broker footprint and\nretires the slot. A static mesh has no broker-side credential revocation, so a copy of the leaf\ncan still connect with the permissions it carries until its expiry. An ordinary spawn refuses any\nname that starts with `chat_`.\n\nThe manager that admitted a session retires it at its expiry when nothing retired it sooner, so a\nlost reply or an abandoned client does not hold the slot. Its stop retires every session it still\nholds, with or without its agents, and names each one it could not retire; a stop that preserves\nthe manager's state leaves them. Its own startup sweep never retires a session it is admitting or\nholds. A session that none of these retired stays held until the next start of that manager\ninstance.\n\n## Persona write observation\n\nThe Manager serves `define-persona` and `remove-persona` under `manager.persona`. Removal takes\n`{name}` and returns `{name}`. It deletes only the machine-local definition, not agents already\nrunning from it. A missing definition is `not-found`. The name may exceed the current 64-character\nspawn limit, provided it is still a safe catalog filename stem, so an invalid legacy definition can\nbe removed.\n\nAn unanswered `define-persona` or `remove-persona` command does not prove the write did not land.\nThe caller must read the catalog again on the same manager before acting. The write may still land\nafter the wait ends, so a missing readback alone does not make another write safe. A failed describe,\nbroker no-responders answer or explicit pre-effect refusal remains a failure, not an unknown write.\n\n## Spawn is a goal\n\nLong-running commands are **actions** ([SPEC §13.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_2\", \"uid\": \"...\",\n \"goalId\": \"...\", \"fingerprint\": \"...\",\n \"readinessDeadlineMs\": 30000,\n \"executor\": { \"lifecycleUid\": \"...\", \"epoch\": 3 }\n}\n```\n\nThe `uid` is the lifecycle the agent runs at. On a participant manager whose host enrolls its\nagents, the host picks that uid, so the manager accepts the goal only after the host has answered.\nA host refusal there refuses the spawn, and no goal is bound.\n\nResubmitting the same `goalId` returns the same acceptance. A `goalId` belongs to the caller that\nsubmitted it, so another caller's spawn under the same id is its own goal with its own\nacceptance. A sibling instance or a restarted one\nanswers it from the identity the accepting instance recorded before it replied, owner included.\nWhen that record names no owner because an older manager wrote it, the resubmission is refused\n`unavailable`. Once the goal has ended, the accepting manager keeps its acceptance for five more\nminutes. After that, and at any other instance, the resubmission is answered from the goal's\nterminal and never accepted again: a `succeeded` terminal names the agent, so it returns the same\nacceptance, and any other outcome refuses it `failed-precondition` with that terminal attached.\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 follower keeps the acceptance as the data of any\nterminal other than `succeeded`, so `cotal_spawn` returns an uncertain launch as a pending result\ninstead of an error: it names the allocated agent, its id, and its manager, and tells the calling\nagent to watch the roster. 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\nThe manager keeps a spawn or launch exception's error code and details when turning it\ninto a refusal. Failed `ControlReply` values keep their code and details at the serving\nboundary. A host enrollment refusal that proves nothing was executed also keeps its\ncode in the public `Manager.startAgent` reply after staged-secret cleanup. A reply\nwithout a code remains `failed-precondition`.\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. The CLI and the connector tools hand a\nrefusal on in one shape, so `cotal spawn --detach` keeps the same code, details, rendered facts\nand acceptance data as `cotal_spawn`. 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 mesh or from an unbound open caller, an untargeted spawn rides class anycast\n(any manager may accept, and the acceptance records which one did). An open managed seat's\npersona definition, list, show and spawn tools default to its launching manager. Its generic\nmanager describe and self-targeted invoke use that launch address too. An explicit existing\npersona or spawn selector still selects that instance. Static credential grants and user-auth\nissuer selection are unchanged. For self-stop, persona definition and direct spawn, a static managed\nseat keeps its class-only credential and accepts only its launching manager's attributed describe\nreply. These commands retain that bind on the class rail, so a sibling refuses before effects and\nthe existing bounded split repair asks again. An absent launching manager never selects a replacement.\nThe library's `describeService` accepts an optional `instanceId`;\na pinned describe does not read or populate the endpoint-only class cache.\n`cotal spawn <persona> --detach --on <instance>` and `cotal_spawn(instance: \"<instance>\")`\npin one instance by its exact id, as `--on` does for `cotal ps`, `cotal models` and every hosted\n`cotal run` verb, and `instance` for `cotal_run`, `cotal_persona` and `cotal_personas`. 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 or class queue. It adds no command capability except the\nthree reads a launch needs: a view whose actor holds `spawn` may call `status`, `models` and\n`resolve-cwd` on that instance, subject to the execution-mode limit above. A `run`-only or no-scope view may not, and `ps` and `slots` stay with\n`admin`. A user mesh's co-located manager answers every owner's view, so its `status` counts only the\ncaller's own seats, as `ps` would list them, unless the caller holds `admin`. An absent,\nambiguous or unauthorized selection refuses before the command is sent. An ambiguous one lists the\nowner's live manager instance ids and names the caller's way to pick one: `--on <instanceId>` for\nthe CLI, `--manager-instance <instanceId>` for `cotal agent-bearer --manager-call`, and the\n`instance` argument for an agent's tools.\nA pin changes routing, not the caller's grant.\n\nEach `status.connectors` row includes `eventPlane: boolean`. The value is true only when the\nconnector declares the event channel it publishes. Installed-extension rows carry the cached fact\nbefore the package is imported, and an old inventory without it is refused rather than treated as\ntrue. A client that reads a required event policy can use this field to disable an incompatible\nconnector before spawn. The Manager still owns the launch refusal text and applies it at admission.\n\nManaged launches carry `COTAL_MANAGER_INSTANCE` so their tools address the manager that launched\nthem; a tool's `instance` argument must name that same manager. The `cotal` commands run from their\nshell select it too, unless `--on` names another instance. 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 reference `cotal_spawn` tool retains the published request id when its submission wait\nends before acceptance is observed. That id is the manager's goal id if the submission is\naccepted later. The tool reports an unknown outcome with the id and a same-caller\n`goal-result` read, without claiming that acceptance occurred. Do not repeat the spawn.\nAn unanswered describe or a broker-attested no-responder refusal does not create a goal\nhandle. A missing readback is inconclusive while the original submission may still arrive.\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\nThe manager's reserved `cancel` command accepts `{goalId, mode?}` and returns `{goalId, state}`.\nIt is served for a turn the manager relays. The goal is the authenticated caller's own, so a caller\nwithdraws only a turn it submitted. The turn ends `cancelled`, its seat is not shown it again, and a\nlater yield of it is answered with that terminal. A goal that already ended is refused\n`failed-precondition` with its cached outcome attached, and a goal this manager does not relay is\nrefused without being changed. So is a second cancel that arrives while a first is still ending the\nturn; a first that fails leaves the turn pending unless something ended it meanwhile. A workflow\nrun sends it for the turn, ask attempt or escalation of a branch it cancelled.\n\nA followed mutation requires a manager whose attributed describe includes `goal-result`. If it\nis absent, preflight refuses with `failed-precondition`, an upgrade notice and `not-executed`\nbefore submitting the mutation. Narrowed discovery preserves that refusal. 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\nA followed call resolves the endpoint within its deadline before the submission starts, so a\nrefused or unanswered describe surfaces as its own error. On a user-auth mesh that preparation also\nobtains the caller's `manager-caller` view and opens its connection, and a failure there surfaces\nunchanged. The control connection uses the remaining preparation deadline, including time spent\nobtaining the bearer, rather than a separate two-second limit. A deadline that passes during those\nsteps reports that the request was not run. The\ndescribe then spends what is left of the deadline, so a describe that draws no reply still reports\nitself as unanswered.\nA describe or command publish that the broker refuses reports `not-executed`.\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 --no-manager` on that host starts no\nmanager, and `cotal supervise --server` runs the manager elsewhere ([Run a mesh](run-a-mesh.md)).\nA broker host that already runs a manager stops it only after `✓ manager up` in\n`.cotal/manager.<spaceKey>.log` (detach stdout listing `manager` is pidfile liveness, not a\nteardown boundary). A controller stack stops it with\n`cotal service stop stack-manager --space <s> --yes`; a legacy stack has no command that stops only\nits manager. Extra live managers are 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 describe and the contract store reads after it share the resolver's one deadline, so a slow\nstore read fails the resolve with `deadline-exceeded` when that deadline expires. `cotal invoke` passes its\n`--timeout` as that deadline (default 10000 ms) and gives the reply what the resolve leaves of it.\n`cotal describe` has no `--timeout` and passes 10000 ms. Cancelling a\nresolve settles a store read in flight instead of waiting for it to return. When one store read\nfails, the resolve fails with it and fetches no further command contracts; fetches already under\nway finish on their own. A call for one command fetches only that command's cluster and schema\nclosures. `describe` still fetches the complete visible surface because its result lists every\ncommand.\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`, the `cotal run` verbs and the manager row of\n`cotal status` re-describe and re-issue an unpinned call after each such refusal, up to 16 times,\nso a split reaches the operator only when every attempt split. A hosted run's own manager calls\nuse the same bound. A pinned call is never re-issued. An agent's own manager\ntools, such as `cotal_spawn` and `cotal_despawn`, re-describe and re-issue with the same bound,\nincluding the goal-result read that follows a spawn to its outcome.\n\nAn unpinned targeted call, such as `cotal_despawn` or a hosted run's turn relay, can also reach a\nmanager that does not host its target, because each manager resolves targets against the agents\nit runs. That manager refuses with `expired` and `not-executed` and says it holds no mapping for\nthe target, and the same re-issue repairs it within the same bound. An agent that no manager hosts\nstill ends in that refusal once the re-issues run out. A pinned call gets the refusal of the\ninstance it named.\n\nA verified Manager `status` reply includes `host`, the answering process's host name, and\n`version`, the running `@cotal-ai/manager` package version captured when its module loaded.\nThese fields are advisory display metadata. They do not select a Manager, authorize a caller\nor determine placement. Use the verified responder's `instanceId` for attribution. Clients\nmust accept status payloads that omit either field and leave the missing value unknown.\nThe optional fields advance the Manager cluster revision to 28.\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.\nWhen no manager takes the class queue, the broker answers an unpinned `spawn` with no\nresponders, and the caller classifies that `not-executed` (SPEC 13.3).\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 §13.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 §13.5](../SPEC.md#135-verbs): a deleted `svc` spec *is* the deregistration).\n\nA manager that stops cleanly removes its own registration, so an ordinary shutdown leaves no stale\nrow. The delete is pinned to the registration revision that process wrote. When a successor has\nregistered the same instance since then, the stop logs that and leaves the successor's registration\nalone. It refuses that delete while this instance holds the endpoint governance slot at the live\nissuance-gate generation (a registration still completing its reopen). A leftover slot whose\ngeneration is behind that live generation is not in-flight and does not block the stop. A manager\nthat cannot renew or read its lease keeps serving, stays registered, and retries. If another process\nholds the same instance key, that process has taken the instance over, so this one logs the conflict\nand exits without deregistering, leaving the successor'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.\nOnce that reopen commits, the registration has completed: a governance slot it then fails to release\nis left behind the live generation, as on a normal registration, and does not fail the restart.\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 endpoint deregister <endpoint> <full-instance-id>`\n([cli.md](cli.md#endpoint-deregister)). 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. `cotal attach`\nreconnects when its link dies by asking the manager for a new session\n([CLI](cli.md#managed-seats)).\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\". Both refusals carry `not-executed`, because nothing was typed. A write the\nruntime rejects once delivery has started states no outcome, so a caller reads it as `unknown`.\nThe manager's other control refusals follow the same rule: one raised before the command's first\neffect, such as a denied caller, a stale target or a missing persona file, carries `not-executed`.\nSee [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 §13.9](../SPEC.md#139-authority-boundary) and\n[identity & auth](identity-and-auth.md).\n\nA carried resume transcript never rides the rails. The operator-only `transcript-receive` command\nanswers whether to upload and hands back a one-time claim for `spawn`, and the bytes travel through\nthe target instance's own transfer bucket under two one-shot credentials: a writer the operator\nmints for that one transcript, and a reader the target instance mints for its own bucket, or that\nthe host issues a remote manager through its `transferReader` authority operation.\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 §13](../SPEC.md#13-endpoint-control-surface-v04), the normative contract.\n"
|
|
175
175
|
},
|
|
176
176
|
{
|
|
177
177
|
"slug": "dashboard-api",
|
|
@@ -195,7 +195,7 @@ export function loadDocsBundle() {
|
|
|
195
195
|
"kind": "Concept (informative)",
|
|
196
196
|
"category": "Concept",
|
|
197
197
|
"summary": "Live channel delivery is at-most-once: a message reaches only the peers subscribed at the moment it is published (SPEC §4).",
|
|
198
|
-
"body": "# The delivery daemon (Plane-3)\n\n> **Concept** (informative) · **For:** operators and implementers · **Normative:** [SPEC §4](../SPEC.md#4-delivery-modes), [§7](../SPEC.md#7-channels), [§8](../SPEC.md#8-nats--jetstream-binding)\n\nLive channel delivery is **at-most-once**: a message reaches only the peers subscribed at the\nmoment it is published ([SPEC §4](../SPEC.md#4-delivery-modes)). Agents are busy, mid-turn, or\noffline, so a channel marked **`durable`** needs a per-member backstop that holds each post until\nthat member has actually seen it. The delivery daemon is the server-side component that provides\nit. In the reference implementation this backstop is nicknamed **Plane-3** (the durable plane,\nalongside the live subject fabric and the presence/registry state).\n\nThe backstop defines a **delivery contract** while leaving the storage layout open: [SPEC §8](../SPEC.md#8-nats--jetstream-binding)\nmakes the daemon's store, writer, reader, and registry reference-implementation detail. What is\nnormative is the [§4](../SPEC.md#4-delivery-modes) guarantee it upholds (`durable` is\nat-least-once for current members within retention) and the [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)\nread checks it must apply. A conformant deployment may realize the backstop differently.\n\n## The three pieces\n\n- **Fan-out writer.** On each post to a `durable` channel it copies the message into every\n eligible member's private durable store. For an `@mention` on a *`live`* channel it also writes\n a copy for each mentioned peer authorized to read that channel, which is how a mention reaches\n an authorized peer who isn't currently joined ([SPEC §4](../SPEC.md#4-delivery-modes)). Fan-out\n handles routing; authorization remains with the broker policy. A post with an empty id is copied\n without a duplicate-suppression key, so two distinct id-less posts are both delivered and a\n redelivery of one may surface twice.\n- **Trusted reader.** It pulls each pending entry, re-checks that the member is still allowed to\n read it, and hands the authorized copy to the member's own `dlv_<owner>-<actor>-<uid>` DELIVER\n consumer, which has the same ack semantics. The copy does not ride the member's reply inbox. The\n entry stays pending until the member confirms it was surfaced. A crash between handing off\n and surfacing does not lose the message; the entry redelivers ([SPEC §8](../SPEC.md#8-nats--jetstream-binding)).\n An entry addressed to a retired lifecycle is dropped and removed from the store the first time\n the reader meets it. Retirement leaves a tombstone on that lifecycle's read-ACL row, and a retired\n lifecycle never comes back, so a later reader with a fresh cursor does not pay for it again. The\n reader acks such an entry only after the delete succeeds. A failed delete leaves the entry pending,\n so it is retried and given up after ten redeliveries, and an entry the stream no longer holds counts\n as removed. A daemon that stops serving while the delete is in flight neither acks nor gives up the\n entry, so the daemon that serves next retries it. When the entry came from a durable channel, the\n reader also removes the retired lifecycle's member row for that channel, when one exists: a daemon\n that died between creating a row and its post-write ACL read leaves one, and until it goes every\n later message on the channel is copied into the retired inbox and dropped again. The removal is\n best effort; a failure is a warning, and the next entry retries it. An entry whose owner has no ACL row at all is\n retried, then given up after ten redeliveries, and kept, because a missing row does not prove the\n owner is gone.\n- **Membership registry.** A privileged-written record of who is a durable member of each\n channel, carrying per-member join and leave cursors so a post concurrent with a join or leave\n orders deterministically ([SPEC §7](../SPEC.md#7-channels)). It is broker-known truth, not\n self-reported: an agent cannot assert its own membership.\n\n## Why a *trusted* reader\n\nThe per-member store is **mixed**: it holds copies for whatever channels a member was in when\neach post landed. An agent can leave a channel or lose a grant afterward, so \"this inbox belongs\nto agent A\" is not authorization to hand A everything in it. Agents therefore hold **no\ncontent-bearing read** on the store; the daemon reads it on their behalf and re-authorizes every\n`(instance, channel, message)` entry against the member's **current read ACL** and, for\n`durable`-channel entries, its **membership interval** (the post's sequence sits between the\nmember's join and leave cursors) before releasing content ([SPEC §7](../SPEC.md#7-channels),\n[§8](../SPEC.md#8-nats--jetstream-binding), [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n\nA **leave is a hard read boundary** for the backstop: once a member leaves, its backstop no\nlonger surfaces that channel's content. (Leaving does not revoke the ACL; the peer can still\nre-subscribe live or read ACL-bounded history within `allowSubscribe`.) See\n[identity-and-auth.md](identity-and-auth.md) for how the ACLs are minted and\n[presence-and-delivery.md](presence-and-delivery.md) for the delivery-class model.\n\n## Where it runs\n\n`cotal up` on an **authenticated** mesh starts the delivery daemon alongside the broker and the\nmanager, as its own long-lived infra role. It runs on a **scoped, least-privilege `delivery`\ncredential** co-located with the broker: never an allow-all cred, and it never holds the account\nsigning key. One daemon serves a space (a single-flight lease guards against a second binding the\nsame durables).\n\nOne process can also serve every space on a host: `cotal deliver --spaces <manifest> --server <url>`\nholds one lane per space the manifest names ([server daemons](cli.md#server-daemons)). A lane is\nthat space's daemon. It reads the space's own credential from the root, dials on its own\nconnections, which authenticate into that space's account, and holds its own lease, broker\nwatchdog, timer writer and membership feed, so a second daemon for the space is refused by the lease\nas before. A lane that loses the broker, its credential or its lease closes alone and the host\nreopens it; the other lanes keep serving.\n\nThe manager needs this daemon while it starts. Its SecretStore challenge, its boot repair of a frozen\nregistration gate, and the verified eviction a restart performs all go over the daemon's\n`ctl.delivery-admin` rail. Agents' durable join, leave and membership-list requests go over its\n`ctl.delivery` rail. Both are `ctl` subjects that [SPEC §13.11](../SPEC.md#1311-the-hard-cut)\nretires; the reference implementation still serves them (see\n[the control surface](control-surface.md)). A manager that starts while the daemon is still binding, or while the\ndaemon re-checks who owns its lease, waits up to 60 seconds for the rail to answer. Only a request\nthat times out or finds no responder is retried. Retries come closer together as the wait runs out,\nso a daemon that binds in its last seconds is still asked. The wait ends on time even while a retry\nis still connecting, and nothing is sent after it. A daemon that answers fails the start at once if\nit refuses or its reply cannot be read. One that stays silent for the whole wait fails it, and the\nmanager log names the rail.\n\nThe daemon answers `ctl.delivery-admin` requests one at a time, in the order they arrive, with one\nexception: the `lifecycleMemberships` inventory a retirement reads before it deletes the retired\nagent's membership rows. That request is answered without waiting for the others, so a manager stop\nthat retires many seats does not queue each inventory behind the other seats' evictions. Inventories\nthat arrive together share one read of the members bucket, and each one's read begins after it\narrived. Before the manager asks for a lifecycle's inventory, it narrows that lifecycle's read-ACL\nrow to no reads. A durable join reads that row again just before it writes its membership row, and\nonce more after. When the channel is no longer allowed, the join writes nothing, or removes the row it\njust wrote, and is refused. A leave or an activation only updates a row that still exists. A row of the\nretiring lifecycle is then either in the inventory or gone, whichever daemon process wrote it. The\ndaemon also fences on its own, for a manager that does not narrow the row: when the inventory request\narrives with the lifecycle's ACL row still allowing reads, it refuses every durable join and leave of\nthat lifecycle from that moment, on that daemon process. A request whose row is already narrowed, or\nretired, leaves no such mark, since the row refuses those writes by itself. Either way the read starts\nonly after the writes already running have finished.\n\nA reply on the `ctl.delivery` or `ctl.delivery-admin` rail that is larger than the broker's\n`max_payload` cannot be published. The daemon answers that request with a refusal giving the reply's\nsize in bytes, so the caller fails at once and does not wait out its timeout.\n\nA restart verify-evicts every holder in the manager's credential family, and the family keeps a\nledger row for every credential an earlier incarnation was issued. The manager keeps its serve,\ngoal-writer and session-ledger identities across restarts, so restarts add no holders; each attach\nsession adds one serving holder. The manager sends those holders\nas one `evictPrincipals` request per 256, and the daemon answers each request with one shared sweep\nof the broker. The manager records the holders each request verified before it sends the next, so a\nrestart cut short by its executor window resumes after the last recorded request. A daemon that does\nnot serve that verb refuses it, and the restart leaves the gate frozen.\n\nAn agent binds its per-member delivery durable even when the plane reached by its connection has no\nready delivery lease, so a daemon that starts later can deliver through it. A missing or not-ready\nlease emits a warning that names the durable, space, and condition. It tells the agent to reconnect\nagainst another plane if that plane serves the space, which re-binds the durable there.\n\nBefore it constructs its endpoint or claims that lease, the daemon reads the account-scoped `$SYS`\nobserver from the same source it will use for scans, whether that source is the workstation store or\nan injected hosted store. It refuses if the observer belongs to another account, is missing, or is\npart of a present but torn observer/evictor rotation. An absent evictor keeps the documented\npre-eviction, deny-new-only posture; eviction itself remains unavailable until it is provisioned.\n\nIt inherits the mesh's transport on **every** launch, including the relaunch a bare `cotal up`\nperforms when the daemon is missing. A TLS-required mesh always starts it with TLS demanded, so it\nrefuses a plaintext listener rather than upgrading on the server's unauthenticated greeting. It\nholds a standing credential and reconnects unattended, so a downgrade here would repeat with nobody\nwatching. See [transport.md](transport.md).\n\nAfter a reachability check at start-up, the daemon watches the broker only through its resident\nconnection's events. It opens no other connection to check the broker. A disconnect starts a clock,\nand a reconnect stops it. When the time since the disconnect, less any time the daemon's own\nevent loop was stalled, reaches the window (`COTAL_DELIVERY_BROKER_GONE_MS`, 15 seconds by\ndefault), the daemon logs\n`✗ delivery: broker connection unavailable (broker unreachable), exiting (coupled to the broker)`\nand exits. Wall time since the disconnect also has a backstop\n(`COTAL_DELIVERY_BROKER_GONE_BACKSTOP_MS`, four times the window by default and never less than it).\nReaching it logs\n`✗ delivery: broker connection unavailable past backstop (broker unreachable), exiting (coupled to the broker)`\nand exits, however long the daemon was stalled. A broker that stops answering without closing the\nsocket counts as disconnected only once the client's pings go unanswered, so the clock starts a few\nseconds after the broker stops.\n\nAn authentication-expiry error is not a broker disconnect. The daemon logs\n`! delivery: credential expired, awaiting proved renewal` at once and waits for a renewal it has\nproved against the broker; a reconnect alone does not clear it. If no such renewal arrives by the\nbackstop, it logs `✗ delivery: credential expired without renewal` and exits.\n\nThe daemon refuses a `reloadCreds` adoption until it has finished starting, which is after its lease\nwatch is bound. Its lease turns ready earlier than that, so a renewal owner can ask before start-up\nis done. The refusal says the daemon has not finished starting and adopts nothing. The next renewal\npass or the daemon's own 75% re-read adopts the re-signed credentials.\n\nAfter an adoption the daemon reconnects with the new credentials 250ms after its reply. A\ndelivery-admin request it reads in the meantime is answered once that reconnect completes, or\nafter 5s. A reply sent while the connection is down would be lost, and its caller, such as a\nmanager evicting its predecessor right after its boot renewal, would wait out its whole 15s request\ntimeout.\n\n`cotal up` reports the daemon **only when it is actually serving**. A daemon it started can exit\nwithout taking the single-flight lease because another daemon holds it, or because a crashed\nholder's lease has not expired yet. `up` then says so and exits non-zero instead of printing a\nhealthy control plane over a daemon that is not there. A lease write the credential is not allowed to make is reported\nas a denial naming the refused subject and operation, never as another daemon holding the lease.\nA lease write the broker refuses for another reason, such as the insufficient-resources answer of a\nstore over its `--max-file-store` cap, is quoted as the broker gave it. A running daemon whose lease\nkey expired creates it again. Only a create refused because a live lease exists makes it say that\nanother daemon has taken the shard. Any other refusal is quoted, with the line saying it could not\nre-acquire the lease, and the daemon exits all the same, because it serves only under its lease.\nThe daemon writes its own reason to `.cotal/delivery.<key>.log`, the log\nfor the space it serves ([Config](config.md#project-files)). That path is project-local. Detached\n`up` redirects the daemon's stdout and stderr onto the file, so wrapping the launcher in a\nsystemd unit does not put those lines in that unit's journal. A daemon stopped by SIGTERM or\nSIGINT, which is what `cotal down`, a service stop and Ctrl-C send, writes `received <signal>,\nexiting` to that log before it releases its lease. A signal that arrives while the daemon is\nstill claiming the lease waits for the broker's answer, and a claim that won is then released the\nsame way. A signal that arrives while the daemon's connection redials, as it does when the daemon\nmoves onto a renewed credential, waits up to five seconds from the drop for the redial before the\nrelease, because a request sent while the connection is down is never answered. A SIGKILL,\nincluding one from the kernel OOM killer, ends the daemon with no line.\n\nA foreground `cotal up` restarts a daemon it started when that daemon dies while the broker that\n`up` started is still running. It logs\n`delivery daemon exited (<cause>) while nats-server is running - restarting it`, then\n`delivery daemon running again` once the replacement's responder is bound. A replacement whose\nresponder does not bind gets the same not-bound warning as at startup instead. The daemon ends\nitself when it cannot reach the broker, and a starved host can make a running broker look\nunreachable. Without the restart, every retirement that needs the daemon would fail until someone\nran `cotal up` again. A failed restart is logged and retried after the 30-second lease TTL. A daemon\nthat exits cleanly or on SIGTERM or SIGINT stays stopped. So does one that bare `cotal down`\nstops, also when the daemon is too starved to exit on SIGTERM and `down` kills it, when it is a\nreplacement that is still starting, and when the stop lands between two restart attempts. A legacy\nstack has no command that stops only the daemon. Detached\n`up` exits after launching and restarts nothing; a bare `cotal up` relaunches a missing daemon there.\n\nCtrl-C on a foreground `up`, and a broker that exits under it, stop the daemon with the same stop\nbare `cotal down` uses for it. It holds the reservation `down` takes, so the delivery stop of a\nconcurrent `cotal down` is refused while it runs. It sends SIGKILL to a daemon that has not exited 15\nseconds after SIGTERM, and removes the daemon's credential only once its death is confirmed. A\nrecord whose pid now belongs to another program is cleared without a signal. If the broker exits\nwhile that stop is running, `up` waits for the stop to finish before it exits.\n\nThe daemon **records itself** in `.cotal/delivery.<key>.pid`, whichever way it was started, and\nremoves that record when it exits cleanly. A lane of `cotal deliver --spaces` is the exception: it\nwrites no record, because the record is what `cotal down` signals for one space and the host serves\nseveral. The launcher is not the only route to a running daemon: a\ncontainer entrypoint, a systemd unit, or `cotal deliver --space <space>` typed by hand all reach one\ntoo, and a record written only by the launcher goes stale the moment any of those restarts it.\n`cotal deliver` is a deprecated entry kept for existing units and scripts; new setups use the\n`delivery` service preset ([deprecated daemon entries](UPGRADING.md#deprecated-daemon-entries)). Typed\nby hand on the workstation, the daemon dials the broker recorded for the space in the mesh registry\n(a mismatching `--server` is refused before any dial); with no record for the space it uses the\nlocal mesh default, and a daemon with an injected store never consults the registry at all. The\nwrite happens once the daemon holds the single-flight lease, because that is the point at which it is\nthe space's daemon: one that loses the lease refuses to bind and exits, and must not overwrite the\nlive holder's record on its way out.\n\nThe daemon serves one workspace root, chosen at start: the one `cotal deliver --root <dir>` names,\nor the nearest `.cotal/` above its working directory. A workstation daemon with neither refuses at\nstart and names the directory it searched from, before it reads a credential or dials a broker,\nbecause a directory nobody set up holds none of its credentials. A daemon with an injected store\ntakes its credentials from that store and needs no `.cotal/`.\n\nReaders verify the record before believing it. A recorded pid is trusted only when the process behind\nit is alive **and** its command line names a delivery daemon, so a record that outlived its process\nand had its number reused is reported as stale rather than as a healthy daemon. `cotal down` never\nsignals such a process. Where a command line cannot be read, the record is trusted as before: the\ncheck only ever downgrades on proof.\n\nThe daemon also hosts the space's **checkpoint timer writer** ([SPEC §13.9](../SPEC.md#139-authority-boundary)):\nthe standing pump that turns workflow `.schedule` requests into armed broker schedules, on its own\nconnection under the same delivery credential. That connection presents the credential the daemon\nholds now and reconnects onto each renewed one the daemon adopts, so the broker never closes it for\nan expired credential and it never dials with one. Without a running writer no workflow pause on the\nspace ever expires. The writer restarts itself with backoff and logs while it is down; a fault\nthere never takes delivery down. Stopping the daemon ends the writer's pending fetch at once and\nwakes a retry backoff it is sleeping through, so a close never waits for a retry it will not make.\n\n**Open dev mode has no delivery daemon.** Open mode is deliberately **live-only**: there is no\ntrusted reader, so there is no durable backstop. Run an auth mesh if you need durable channels.\n\n## Without it\n\nThe self-serve **live** path never depends on the daemon: join is a broker-enforced subscribe\nunder `sub.allow`, so a `durable` channel still delivers live with no daemon present ([SPEC §7](../SPEC.md#7-channels)).\nOnly the durable backstop and its membership writes need the privileged host. If a peer joins a\n`durable` channel while the backstop can't be established, it is **joined live with the durable\nbackstop unestablished**: the live subscription is active, and the shortfall is surfaced as an\nexceptional delivery state, never reported as `joined durable` and never silently dropped ([SPEC §7](../SPEC.md#7-channels)).\n"
|
|
198
|
+
"body": "# The delivery daemon (Plane-3)\n\n> **Concept** (informative) · **For:** operators and implementers · **Normative:** [SPEC §4](../SPEC.md#4-delivery-modes), [§7](../SPEC.md#7-channels), [§8](../SPEC.md#8-nats--jetstream-binding)\n\nLive channel delivery is **at-most-once**: a message reaches only the peers subscribed at the\nmoment it is published ([SPEC §4](../SPEC.md#4-delivery-modes)). Agents are busy, mid-turn, or\noffline, so a channel marked **`durable`** needs a per-member backstop that holds each post until\nthat member has actually seen it. The delivery daemon is the server-side component that provides\nit. In the reference implementation this backstop is nicknamed **Plane-3** (the durable plane,\nalongside the live subject fabric and the presence/registry state).\n\nThe backstop defines a **delivery contract** while leaving the storage layout open: [SPEC §8](../SPEC.md#8-nats--jetstream-binding)\nmakes the daemon's store, writer, reader, and registry reference-implementation detail. What is\nnormative is the [§4](../SPEC.md#4-delivery-modes) guarantee it upholds (`durable` is\nat-least-once for current members within retention) and the [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)\nread checks it must apply. A conformant deployment may realize the backstop differently.\n\n## The three pieces\n\n- **Fan-out writer.** On each post to a `durable` channel it copies the message into every\n eligible member's private durable store. For an `@mention` on a *`live`* channel it also writes\n a copy for each mentioned peer authorized to read that channel, which is how a mention reaches\n an authorized peer who isn't currently joined ([SPEC §4](../SPEC.md#4-delivery-modes)). Fan-out\n handles routing; authorization remains with the broker policy. A post with an empty id is copied\n without a duplicate-suppression key, so two distinct id-less posts are both delivered and a\n redelivery of one may surface twice.\n- **Trusted reader.** It pulls each pending entry, re-checks that the member is still allowed to\n read it, and hands the authorized copy to the member's own `dlv_<owner>-<actor>-<uid>` DELIVER\n consumer, which has the same ack semantics. The copy does not ride the member's reply inbox. The\n entry stays pending until the member confirms it was surfaced. A crash between handing off\n and surfacing does not lose the message; the entry redelivers ([SPEC §8](../SPEC.md#8-nats--jetstream-binding)).\n An entry addressed to a retired lifecycle is dropped and removed from the store the first time\n the reader meets it. Retirement leaves a tombstone on that lifecycle's read-ACL row, and a retired\n lifecycle never comes back, so a later reader with a fresh cursor does not pay for it again. The\n reader acks such an entry only after the delete succeeds. A failed delete leaves the entry pending,\n so it is retried and given up after ten redeliveries, and an entry the stream no longer holds counts\n as removed. A daemon that stops serving while the delete is in flight neither acks nor gives up the\n entry, so the daemon that serves next retries it. When the entry came from a durable channel, the\n reader also removes the retired lifecycle's member row for that channel, when one exists: a daemon\n that died between creating a row and its post-write ACL read leaves one, and until it goes every\n later message on the channel is copied into the retired inbox and dropped again. The removal is\n best effort; a failure is a warning, and the next entry retries it. An entry whose owner has no ACL row at all is\n retried, then given up after ten redeliveries, and kept, because a missing row does not prove the\n owner is gone.\n- **Membership registry.** A privileged-written record of who is a durable member of each\n channel, carrying per-member join and leave cursors so a post concurrent with a join or leave\n orders deterministically ([SPEC §7](../SPEC.md#7-channels)). It is broker-known truth, not\n self-reported: an agent cannot assert its own membership.\n\n## Why a *trusted* reader\n\nThe per-member store is **mixed**: it holds copies for whatever channels a member was in when\neach post landed. An agent can leave a channel or lose a grant afterward, so \"this inbox belongs\nto agent A\" is not authorization to hand A everything in it. Agents therefore hold **no\ncontent-bearing read** on the store; the daemon reads it on their behalf and re-authorizes every\n`(instance, channel, message)` entry against the member's **current read ACL** and, for\n`durable`-channel entries, its **membership interval** (the post's sequence sits between the\nmember's join and leave cursors) before releasing content ([SPEC §7](../SPEC.md#7-channels),\n[§8](../SPEC.md#8-nats--jetstream-binding), [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n\nA **leave is a hard read boundary** for the backstop: once a member leaves, its backstop no\nlonger surfaces that channel's content. (Leaving does not revoke the ACL; the peer can still\nre-subscribe live or read ACL-bounded history within `allowSubscribe`.) See\n[identity-and-auth.md](identity-and-auth.md) for how the ACLs are minted and\n[presence-and-delivery.md](presence-and-delivery.md) for the delivery-class model.\n\n## Where it runs\n\n`cotal up` on an **authenticated** mesh starts the delivery daemon alongside the broker and the\nmanager, as its own long-lived infra role. It runs on a **scoped, least-privilege `delivery`\ncredential** co-located with the broker: never an allow-all cred, and it never holds the account\nsigning key. One daemon serves a space (a single-flight lease guards against a second binding the\nsame durables).\n\nOne process can also serve every space on a host: `cotal deliver --spaces <manifest> --server <url>`\nholds one lane per space the manifest names ([server daemons](cli.md#server-daemons)). A lane is\nthat space's daemon. It reads the space's own credential from the root, dials on its own\nconnections, which authenticate into that space's account, and holds its own lease, broker\nwatchdog, timer writer and membership feed, so a second daemon for the space is refused by the lease\nas before. A lane that loses the broker, its credential or its lease closes alone and the host\nreopens it; the other lanes keep serving.\n\nThe manager needs this daemon while it starts. Its SecretStore challenge, its boot repair of a frozen\nregistration gate, and the verified eviction a restart performs all go over the daemon's\n`ctl.delivery-admin` rail. Agents' durable join, leave and membership-list requests go over its\n`ctl.delivery` rail. Both are `ctl` subjects that [SPEC §13.11](../SPEC.md#1311-the-hard-cut)\nretires; the reference implementation still serves them (see\n[the control surface](control-surface.md)). A manager that starts while the daemon is still binding, or while the\ndaemon re-checks who owns its lease, waits up to 60 seconds for the rail to answer. Only a request\nthat times out or finds no responder is retried. The first retry runs at once. Later retries are at\nmost one second apart, shortened as the wait runs out, so a daemon that binds in its last seconds is\nstill asked. The wait ends on time even while a retry is still connecting, and nothing is sent after\nit. A daemon that answers fails the start at once if it refuses or its reply cannot be read. One\nthat stays silent for the whole wait fails it, and the manager log names the rail.\n\nA manager retiring a static agent uses the same retry cadence for an unanswered verified-eviction\nrequest, within a 15-second total wait. A credential reload briefly removes the daemon's responder\nwhile it reconnects; that gap must not abandon an otherwise healthy retirement. A refusal or an\nunusable eviction reply still fails at once. The lifecycle stays held until eviction is verified\nand cleanup completes.\n\nThe daemon answers `ctl.delivery-admin` requests one at a time, in the order they arrive, with one\nexception: the `lifecycleMemberships` inventory a retirement reads before it deletes the retired\nagent's membership rows. That request is answered without waiting for the others, so a manager stop\nthat retires many seats does not queue each inventory behind the other seats' evictions. Inventories\nthat arrive together share one read of the members bucket, and each one's read begins after it\narrived. Before the manager asks for a lifecycle's inventory, it narrows that lifecycle's read-ACL\nrow to no reads. A durable join reads that row again just before it writes its membership row, and\nonce more after. When the channel is no longer allowed, the join writes nothing, or removes the row it\njust wrote, and is refused. A leave or an activation only updates a row that still exists. A row of the\nretiring lifecycle is then either in the inventory or gone, whichever daemon process wrote it. The\ndaemon also fences on its own, for a manager that does not narrow the row: when the inventory request\narrives with the lifecycle's ACL row still allowing reads, it refuses every durable join and leave of\nthat lifecycle from that moment, on that daemon process. A request whose row is already narrowed, or\nretired, leaves no such mark, since the row refuses those writes by itself. Either way the read starts\nonly after the writes already running have finished.\n\nA reply on the `ctl.delivery` or `ctl.delivery-admin` rail that is larger than the broker's\n`max_payload` cannot be published. The daemon answers that request with a refusal giving the reply's\nsize in bytes, so the caller fails at once and does not wait out its timeout.\n\nA restart verify-evicts every holder in the manager's credential family, and the family keeps a\nledger row for every credential an earlier incarnation was issued. The manager keeps its serve,\ngoal-writer and session-ledger identities across restarts, so restarts add no holders; each attach\nsession adds one serving holder. The manager sends those holders\nas one `evictPrincipals` request per 256, and the daemon answers each request with one shared sweep\nof the broker. The manager records the holders each request verified before it sends the next, so a\nrestart cut short by its executor window resumes after the last recorded request. A daemon that does\nnot serve that verb refuses it, and the restart leaves the gate frozen.\n\nAn agent binds its per-member delivery durable even when the plane reached by its connection has no\nready delivery lease, so a daemon that starts later can deliver through it. A missing or not-ready\nlease emits a warning that names the durable, space, and condition. It tells the agent to reconnect\nagainst another plane if that plane serves the space, which re-binds the durable there.\n\nBefore it constructs its endpoint or claims that lease, the daemon reads the account-scoped `$SYS`\nobserver from the same source it will use for scans, whether that source is the workstation store or\nan injected hosted store. It refuses if the observer belongs to another account, is missing, or is\npart of a present but torn observer/evictor rotation. An absent evictor keeps the documented\npre-eviction, deny-new-only posture; eviction itself remains unavailable until it is provisioned.\n\nIt inherits the mesh's transport on **every** launch, including the relaunch a bare `cotal up`\nperforms when the daemon is missing. A TLS-required mesh always starts it with TLS demanded, so it\nrefuses a plaintext listener rather than upgrading on the server's unauthenticated greeting. It\nholds a standing credential and reconnects unattended, so a downgrade here would repeat with nobody\nwatching. See [transport.md](transport.md).\n\nAfter a reachability check at start-up, the daemon watches the broker only through its resident\nconnection's events. It opens no other connection to check the broker. A disconnect starts a clock,\nand a reconnect stops it. When the time since the disconnect, less any time the daemon's own\nevent loop was stalled, reaches the window (`COTAL_DELIVERY_BROKER_GONE_MS`, 15 seconds by\ndefault), the daemon logs\n`✗ delivery: broker connection unavailable (broker unreachable), exiting (coupled to the broker)`\nand exits. Wall time since the disconnect also has a backstop\n(`COTAL_DELIVERY_BROKER_GONE_BACKSTOP_MS`, four times the window by default and never less than it).\nReaching it logs\n`✗ delivery: broker connection unavailable past backstop (broker unreachable), exiting (coupled to the broker)`\nand exits, however long the daemon was stalled. A broker that stops answering without closing the\nsocket counts as disconnected only once the client's pings go unanswered, so the clock starts a few\nseconds after the broker stops.\n\nAn authentication-expiry error is not a broker disconnect. The daemon logs\n`! delivery: credential expired, awaiting proved renewal` at once and waits for a renewal it has\nproved against the broker; a reconnect alone does not clear it. If no such renewal arrives by the\nbackstop, it logs `✗ delivery: credential expired without renewal` and exits.\n\nThe daemon refuses a `reloadCreds` adoption until it has finished starting, which is after its lease\nwatch is bound. Its lease turns ready earlier than that, so a renewal owner can ask before start-up\nis done. The refusal says the daemon has not finished starting and adopts nothing. The next renewal\npass or the daemon's own 75% re-read adopts the re-signed credentials.\n\nAfter an adoption the daemon reconnects with the new credentials 250ms after its reply. A\ndelivery-admin request it reads in the meantime is answered once that reconnect completes, or\nafter 5s. A reply sent while the connection is down would be lost, and its caller, such as a\nmanager evicting its predecessor right after its boot renewal, would wait out its whole 15s request\ntimeout.\n\n`cotal up` reports the daemon **only when it is actually serving**. A daemon it started can exit\nwithout taking the single-flight lease because another daemon holds it, or because a crashed\nholder's lease has not expired yet. `up` then says so and exits non-zero instead of printing a\nhealthy control plane over a daemon that is not there. A lease write the credential is not allowed to make is reported\nas a denial naming the refused subject and operation, never as another daemon holding the lease.\nA lease write the broker refuses for another reason, such as the insufficient-resources answer of a\nstore over its `--max-file-store` cap, is quoted as the broker gave it. A running daemon whose lease\nkey expired creates it again. Only a create refused because a live lease exists makes it say that\nanother daemon has taken the shard. Any other refusal is quoted, with the line saying it could not\nre-acquire the lease, and the daemon exits all the same, because it serves only under its lease.\nThe daemon writes its own reason to `.cotal/delivery.<key>.log`, the log\nfor the space it serves ([Config](config.md#project-files)). That path is project-local. Detached\n`up` redirects the daemon's stdout and stderr onto the file, so wrapping the launcher in a\nsystemd unit does not put those lines in that unit's journal. A daemon stopped by SIGTERM or\nSIGINT, which is what `cotal down`, a service stop and Ctrl-C send, writes `received <signal>,\nexiting` to that log before it releases its lease. A signal that arrives while the daemon is\nstill claiming the lease waits for the broker's answer, and a claim that won is then released the\nsame way. A signal that arrives while the daemon's connection redials, as it does when the daemon\nmoves onto a renewed credential, waits up to five seconds from the drop for the redial before the\nrelease, because a request sent while the connection is down is never answered. A SIGKILL,\nincluding one from the kernel OOM killer, ends the daemon with no line.\n\nA foreground `cotal up` restarts a daemon it started when that daemon dies while the broker that\n`up` started is still running. It logs\n`delivery daemon exited (<cause>) while nats-server is running - restarting it`, then\n`delivery daemon running again` once the replacement's responder is bound. A replacement whose\nresponder does not bind gets the same not-bound warning as at startup instead. The daemon ends\nitself when it cannot reach the broker, and a starved host can make a running broker look\nunreachable. Without the restart, every retirement that needs the daemon would fail until someone\nran `cotal up` again. A failed restart is logged and retried after the 30-second lease TTL. A daemon\nthat exits cleanly or on SIGTERM or SIGINT stays stopped. So does one that bare `cotal down`\nstops, also when the daemon is too starved to exit on SIGTERM and `down` kills it, when it is a\nreplacement that is still starting, and when the stop lands between two restart attempts. A legacy\nstack has no command that stops only the daemon. Detached\n`up` exits after launching and restarts nothing; a bare `cotal up` relaunches a missing daemon there.\n\nCtrl-C on a foreground `up`, and a broker that exits under it, stop the daemon with the same stop\nbare `cotal down` uses for it. It holds the reservation `down` takes, so the delivery stop of a\nconcurrent `cotal down` is refused while it runs. It sends SIGKILL to a daemon that has not exited 15\nseconds after SIGTERM, and removes the daemon's credential only once its death is confirmed. A\nrecord whose pid now belongs to another program is cleared without a signal. If the broker exits\nwhile that stop is running, `up` waits for the stop to finish before it exits.\n\nThe daemon **records itself** in `.cotal/delivery.<key>.pid`, whichever way it was started, and\nremoves that record when it exits cleanly. A lane of `cotal deliver --spaces` is the exception: it\nwrites no record, because the record is what `cotal down` signals for one space and the host serves\nseveral. The launcher is not the only route to a running daemon: a\ncontainer entrypoint, a systemd unit, or `cotal deliver --space <space>` typed by hand all reach one\ntoo, and a record written only by the launcher goes stale the moment any of those restarts it.\n`cotal deliver` is a deprecated entry kept for existing units and scripts; new setups use the\n`delivery` service preset ([deprecated daemon entries](UPGRADING.md#deprecated-daemon-entries)). Typed\nby hand on the workstation, the daemon dials the broker recorded for the space in the mesh registry\n(a mismatching `--server` is refused before any dial); with no record for the space it uses the\nlocal mesh default, and a daemon with an injected store never consults the registry at all. The\nwrite happens once the daemon holds the single-flight lease, because that is the point at which it is\nthe space's daemon: one that loses the lease refuses to bind and exits, and must not overwrite the\nlive holder's record on its way out.\n\nThe daemon serves one workspace root, chosen at start: the one `cotal deliver --root <dir>` names,\nor the nearest `.cotal/` above its working directory. A workstation daemon with neither refuses at\nstart and names the directory it searched from, before it reads a credential or dials a broker,\nbecause a directory nobody set up holds none of its credentials. A daemon with an injected store\ntakes its credentials from that store and needs no `.cotal/`.\n\nReaders verify the record before believing it. A recorded pid is trusted only when the process behind\nit is alive **and** its command line names a delivery daemon, so a record that outlived its process\nand had its number reused is reported as stale rather than as a healthy daemon. `cotal down` never\nsignals such a process. Where a command line cannot be read, the record is trusted as before: the\ncheck only ever downgrades on proof.\n\nThe daemon also hosts the space's **checkpoint timer writer** ([SPEC §13.9](../SPEC.md#139-authority-boundary)):\nthe standing pump that turns workflow `.schedule` requests into armed broker schedules, on its own\nconnection under the same delivery credential. That connection presents the credential the daemon\nholds now and reconnects onto each renewed one the daemon adopts, so the broker never closes it for\nan expired credential and it never dials with one. Without a running writer no workflow pause on the\nspace ever expires. The writer restarts itself with backoff and logs while it is down; a fault\nthere never takes delivery down. Stopping the daemon ends the writer's pending fetch at once and\nwakes a retry backoff it is sleeping through, so a close never waits for a retry it will not make.\n\n**Open dev mode has no delivery daemon.** Open mode is deliberately **live-only**: there is no\ntrusted reader, so there is no durable backstop. Run an auth mesh if you need durable channels.\n\n## Without it\n\nThe self-serve **live** path never depends on the daemon: join is a broker-enforced subscribe\nunder `sub.allow`, so a `durable` channel still delivers live with no daemon present ([SPEC §7](../SPEC.md#7-channels)).\nOnly the durable backstop and its membership writes need the privileged host. If a peer joins a\n`durable` channel while the backstop can't be established, it is **joined live with the durable\nbackstop unestablished**: the live subscription is active, and the shortfall is surfaced as an\nexceptional delivery state, never reported as `joined durable` and never silently dropped ([SPEC §7](../SPEC.md#7-channels)).\n"
|
|
199
199
|
},
|
|
200
200
|
{
|
|
201
201
|
"slug": "deploy",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docs-bundle.generated.js","sourceRoot":"","sources":["../src/docs-bundle.generated.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"docs-bundle.generated.js","sourceRoot":"","sources":["../src/docs-bundle.generated.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"manager-call.d.ts","sourceRoot":"","sources":["../src/manager-call.ts"],"names":[],"mappings":"AAAA,OAAO,EAYL,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAElB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,KAAK,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,cAAc,GAAG,UAAU,GAAG,mBAAmB,CAAC,CAAC;AAqBxH,iGAAiG;AACjG,wBAAgB,gBAAgB,IAAI,IAAI,CAAwB;AAEhE;;;oFAGoF;AACpF,KAAK,iBAAiB,GAAG,CACvB,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,iBAAiB,CAAC,EAC5D,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KAC9D,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,mGAAmG;AACnG,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,EACjD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC1G,OAAO,CAAC,iBAAiB,CAAC,
|
|
1
|
+
{"version":3,"file":"manager-call.d.ts","sourceRoot":"","sources":["../src/manager-call.ts"],"names":[],"mappings":"AAAA,OAAO,EAYL,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAElB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,KAAK,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,cAAc,GAAG,UAAU,GAAG,mBAAmB,CAAC,CAAC;AAqBxH,iGAAiG;AACjG,wBAAgB,gBAAgB,IAAI,IAAI,CAAwB;AAEhE;;;oFAGoF;AACpF,KAAK,iBAAiB,GAAG,CACvB,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,iBAAiB,CAAC,EAC5D,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KAC9D,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,mGAAmG;AACnG,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,EACjD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC1G,OAAO,CAAC,iBAAiB,CAAC,CA0H5B"}
|
package/dist/manager-call.js
CHANGED
|
@@ -35,6 +35,7 @@ export async function invokeUserManager(config, bearer, command, args, opts = {}
|
|
|
35
35
|
const onAbort = () => { void nc?.close(); };
|
|
36
36
|
const resolve = (signal = opts.signal, deadlineMs = opts.deadlineMs ?? 10_000) => resolveService(nc, config.space, endpoint, caller, {
|
|
37
37
|
instanceId, deadlineMs, signal, commands: opts.follow ? [command, "goal-result"] : [command],
|
|
38
|
+
...(opts.follow && command !== "goal-result" ? { optionalCommands: ["goal-result"] } : {}),
|
|
38
39
|
});
|
|
39
40
|
const resolvePrepared = async (signal = opts.signal, deadline = Date.now() + (opts.deadlineMs ?? 10_000)) => {
|
|
40
41
|
const remaining = () => {
|
package/dist/manager-call.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"manager-call.js","sourceRoot":"","sources":["../src/manager-call.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,GAKtB,MAAM,gBAAgB,CAAC;AAMxB;;;qGAGqG;AACrG,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;AAC7C,MAAM,sBAAsB,GAAG,EAAE,GAAG,MAAM,CAAC;AAC3C,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AACD,SAAS,kBAAkB,CAAC,GAAW;IACrC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,sBAAsB,CAAC,CAAC;IACzD,IAAI,UAAU,CAAC,IAAI,GAAG,eAAe;QAAE,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;AAC5F,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,KAAW,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAWhE,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAqB,EACrB,MAAiD,EACjD,OAAe,EACf,IAAyC,EACzC,OAAyG,EAAE;IAE3G,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAS,CAAC;IAC9B,MAAM,QAAQ,GAAG,2BAA2B,CAAC;IAC7C,IAAI,EAA8B,CAAC;IACnC,IAAI,MAAgB,CAAC;IACrB,IAAI,UAAkB,CAAC;IACvB,IAAI,OAAwB,CAAC;IAC7B,IAAI,mBAAgE,CAAC;IACrE,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,EAAG,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE;QACpI,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"manager-call.js","sourceRoot":"","sources":["../src/manager-call.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cotal-ai/connector-core",
|
|
3
3
|
"description": "Shared MCP-bridge runtime for Cotal connectors: the mesh agent, cotal_* tools, and hook relay.",
|
|
4
|
-
"version": "0.128.
|
|
4
|
+
"version": "0.128.6",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -41,11 +41,11 @@
|
|
|
41
41
|
"@cotal-ai/core": ">=0.1.0"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
-
"@cotal-ai/auth": "0.128.
|
|
44
|
+
"@cotal-ai/auth": "0.128.6",
|
|
45
45
|
"jose": "^6.2.3",
|
|
46
46
|
"@cotal-ai/smoke-kit": "0.0.0",
|
|
47
47
|
"@ag-ui/core": "0.0.57",
|
|
48
|
-
"@cotal-ai/core": "0.128.
|
|
48
|
+
"@cotal-ai/core": "0.128.6",
|
|
49
49
|
"@nats-io/jetstream": "^3.4.0",
|
|
50
50
|
"@nats-io/transport-node": "^3.4.0"
|
|
51
51
|
},
|