@cotal-ai/pi 0.41.1 → 0.41.3

package/dist/index.js

@@ -16322,7 +16322,7 @@ import { isConcreteChannel as isConcreteChannel3, channelInAllow as channelInAll
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.41.1",
+  "version": "0.41.3",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -16344,7 +16344,7 @@ var DOCS_BUNDLE = {
       "title": "Architecture",
       "kind": "Concept (informative)",
       "summary": "Cotal is built as a thin waist: the normative wire contract (subjects, message schemas, presence/discovery, delivery semantics, the auth grammar) is the standard (SPEC), and everything else is a pl\u2026",
-      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## A2A influence\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## NATS mapping\n\nThe messaging plane rides three subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)); the endpoint control surface adds its own rails\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| endpoint (control) | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026` ([\xA713.2](../SPEC.md#132-grammar)) |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the endpoint control surface on its own rails and streams\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)). Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches every contributed `kind:name`. Command metadata is cached for\n`--help`/completion; running a command or requesting a provider imports its owner lazily and\nuses the live object. Before that first import, the loader rebinds shared peers to the current\nhost under the extension-prefix lock; version skew or an unbindable peer fails loudly.\nThe repo's `@cotal-ai/web` dashboard and optional tmux/cmux/Orca/Herdr runtimes use this mechanism.\nRuntime resolution stays registry-driven and open-ended: a name with no registered/installed\nprovider fails loud (never a fallback), and a third-party runtime installs under its own package\nname. The CLI does carry a small, non-authoritative map of the first-party runtime names\n(`orca`/`tmux`/`cmux`/`herdr`) to their `@cotal-ai/*` packages, used only to print an exact `cotal ext add`\nhint for a known-but-uninstalled runtime and to list them in `cotal runtimes`; it never resolves or\nregisters a provider.\n\nMachine-local processes use the same registry. The base CLI contributes broker/control-plane\n`local-process` descriptors, while an installed package contributes its own (for example `web`).\nThat keeps `cotal down <component>` and `cotal status` extensible without teaching the base CLI\npackage-specific pidfiles. A provider process claims its declared pidfile with exclusive create;\nextension removal reserves that same path so startup cannot cross uninstall.\n\nBeyond the app-bound connectors, `@cotal-ai/pi` is a **host-native plugin**: a pi extension\nloaded into the user's own pi (CLI or SDK-embedded), placing a Cotal endpoint inside the\nsession's process and driving its run loop off the inbox. See\n[connect-pi](connect-pi.md).\n\n## Connector runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha), a host-native extension for\n[pi](connect-pi.md) (alpha). The [connectors matrix](connectors.md) compares them\nfeature-by-feature.\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A manual\n`/reconnect` is the human-invoked counterpart.\n\n## Manager supervision\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh. The manager is not a privileged control plane: it is an ordinary\nservice endpoint on the same `ep` rails as any other daemon\n([\xA713](../SPEC.md#13-endpoint-control-surface-v04)), holding only the capability rows its\ncallers grant it. It owns process lifecycle and config binding (start / stop / restart,\nbinding env and policy) and has no say in what work the agents do. Agents coordinate\nlaterally; the manager only births and configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`**, **`cmux`**, **`orca`**, and **`herdr`** are\n  extensions that put each teammate in its own native terminal surface (explicit opt-ins\n  that throw when the extension isn't loaded, never a silent fallback); **byo** is the\n  floor (a human's own terminal, tracked via presence); **host** (Agent SDK, true mid-turn\n  interrupt) is the documented upgrade path ([roadmap](roadmap.md)).\n- **Served commands.** `spawn` (an action, below), `stop`, `ps`, `status`, `attach`,\n  `models`, `definePersona`, and `bind` are endpoint commands\n  ([\xA713.5](../SPEC.md#135-verbs)) any authorized node can send, policy-gated\n  ([identity & auth](identity-and-auth.md)). A caller learns them off the wire with `cotal\n  describe manager`; nothing is compiled in.\n- **Spawn is an action.** Asking for an agent no longer blocks the caller while the process\n  comes up. The manager accepts a spawn **goal** ([\xA713.6](../SPEC.md#136-composites)) and\n  immediately returns the allocated identity (the agent's name, its `owner`/`actor`/`uid`\n  triple, a `goalId`, and the executor coordinate `{lifecycleUid, epoch}`); progress events\n  then report the launch until a terminal outcome. Presence within the readiness window is\n  `succeeded`, an early exit is `failed`, and the window passing with neither is\n  `uncertain`: a bounded, reconcilable outcome a later `ps` settles against the live roster,\n  never a silent hang.\n- **Bounded spawn.** A gate caps concurrent and in-flight agents and a minimum-lifetime\n  floor bounds spawn/despawn churn, so a capability-holding but compromised peer cannot\n  fork-bomb the host. The gate runs at goal acceptance, before any identity is minted or\n  process launched, so a refused spawn leaves nothing behind.\n- **Declared environment boundary.** A spawned agent receives a fixed OS allow-list (PATH/HOME/\n  locale, including PATH entries connector binaries live in), the machine-wide `COTAL_*` operator\n  knobs, connector-declared provider inputs, explicitly shared MCP references, and names\n  deliberately added through `spawn.env`. It never inherits the manager's ambient environment, so\n  host-session markers (`CLAUDE_CODE_CHILD_SESSION` and the analogous names other hosts use) and\n  unrelated capabilities cannot become properties of every seat. Connection material rides a private\n  file instead of the environment.\n- **Instance addressing.** One space can hold more than one manager. Each keeps a stable\n  logical instance id across restarts and advances its process epoch when it comes back, so\n  peers address a specific manager without caring which process currently serves it. `cotal\n  spawn <persona> --detach --on <instance>` pins one instance (`ps`, `stop` and `attach` take\n  the same flag); an untargeted spawn rides class anycast and the acceptance records which\n  instance took it. `ps` and `status` scatter across every registered instance and label a\n  non-answering one as registered with no answer within the deadline, never dropping it.\n- **A manager holds a liveness lease, and nothing about it ends the process.** Each instance\n  keeps its own key in the space's manager bucket and refreshes it several times over inside the\n  key's TTL. A refresh that fails is a question, not a verdict, so the manager re-reads the key\n  before deciding what to do. If the key is still its own it adopts the broker's revision and\n  carries on. If the key is gone (it expired during a stall) it puts it back. If another process\n  holds it, it says so and keeps serving; which of the two goes is the operator's call. If the\n  broker cannot be asked at all it keeps serving and asks again, for as long as that takes. A\n  manager that cannot reach its broker gains nothing by ending itself, and the seats it holds\n  lose everything. Each change of state is one line in the manager's log, not one line per tick.\n- **Attach is a mesh session.** The console and dashboard discover agents over the **mesh**\n  (presence, `ps`). `cotal attach` no longer hands back a `127.0.0.1` URL: it redeems a\n  one-use, holder-bound session offer, and the terminal bytes stream over the mesh on\n  core-NATS session subjects scoped to the two parties, with backpressure surfaced as an\n  explicit drop notice rather than silent loss. Attach reaches managers on other machines through\n  the broker. The manager's own socket stays private. A late\n  attach still repaints the full screen from a replayed snapshot of a headless terminal\n  mirror (including alternate-screen TUIs). If the manager restarts, its successor refuses\n  the old session and the client surfaces \"manager restarted; re-attach\".\n- **The manager's console face is a separate, credentialed surface.** The manager still\n  serves the browser console over local HTTP: the static page plus the roster, the live feed,\n  and the route that mints the browser's own session. It binds loopback unless the operator\n  says otherwise (`cotal supervise --console-host`), and every route that carries mesh data\n  or mints a credential requires the manager's console token.\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Each managed agent runs under a durable **lifecycle**: a despawn retires it (settling\nand evicting the old incarnation) before its name frees for reuse, and a supervised restart\nrecovers the same lifecycle rather than minting a new one, so durables and credentials key\non the lifecycle, not the reusable name ([SPEC \xA713.1](../SPEC.md#131-lifecycle-identity);\n[identity & auth](identity-and-auth.md)). Destructive space-wide operations (history purge)\nstay operator-only.\n\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Addressing\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
+      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## A2A influence\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## NATS mapping\n\nThe messaging plane rides three subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)); the endpoint control surface adds its own rails\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| endpoint (control) | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026` ([\xA713.2](../SPEC.md#132-grammar)) |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the endpoint control surface on its own rails and streams\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)). Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches every contributed `kind:name`. Command metadata is cached for\n`--help`/completion; running a command or requesting a provider imports its owner lazily and\nuses the live object. Before that first import, the loader rebinds shared peers to the current\nhost under the extension-prefix lock; version skew or an unbindable peer fails loudly.\nThe repo's `@cotal-ai/web` dashboard and optional tmux/cmux/Orca/Herdr runtimes use this mechanism.\nRuntime resolution stays registry-driven and open-ended: a name with no registered/installed\nprovider fails loud (never a fallback), and a third-party runtime installs under its own package\nname. The CLI does carry a small, non-authoritative map of the first-party runtime names\n(`orca`/`tmux`/`cmux`/`herdr`) to their `@cotal-ai/*` packages, used only to print an exact `cotal ext add`\nhint for a known-but-uninstalled runtime and to list them in `cotal runtimes`; it never resolves or\nregisters a provider.\n\nMachine-local processes use the same registry. The base CLI contributes broker/control-plane\n`local-process` descriptors, while an installed package contributes its own (for example `web`).\nThat keeps `cotal down <component>` and `cotal status` extensible without teaching the base CLI\npackage-specific pidfiles. A provider process claims its declared pidfile with exclusive create;\nextension removal reserves that same path so startup cannot cross uninstall.\n\nBeyond the app-bound connectors, `@cotal-ai/pi` is a **host-native plugin**: a pi extension\nloaded into the user's own pi (CLI or SDK-embedded), placing a Cotal endpoint inside the\nsession's process and driving its run loop off the inbox. See\n[connect-pi](connect-pi.md).\n\n## Connector runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha), a host-native extension for\n[pi](connect-pi.md) (alpha). The [connectors matrix](connectors.md) compares them\nfeature-by-feature.\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A failed\npost-connect bind closes its partial transport before the retry loop starts another attempt.\nA manual `/reconnect` is the human-invoked counterpart.\n\n## Manager supervision\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh. The manager is not a privileged control plane: it is an ordinary\nservice endpoint on the same `ep` rails as any other daemon\n([\xA713](../SPEC.md#13-endpoint-control-surface-v04)), holding only the capability rows its\ncallers grant it. It owns process lifecycle and config binding (start / stop / restart,\nbinding env and policy) and has no say in what work the agents do. Agents coordinate\nlaterally; the manager only births and configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`**, **`cmux`**, **`orca`**, and **`herdr`** are\n  extensions that put each teammate in its own native terminal surface (explicit opt-ins\n  that throw when the extension isn't loaded, never a silent fallback); **byo** is the\n  floor (a human's own terminal, tracked via presence); **host** (Agent SDK, true mid-turn\n  interrupt) is the documented upgrade path ([roadmap](roadmap.md)).\n- **Served commands.** `spawn` (an action, below), `stop`, `ps`, `status`, `attach`,\n  `models`, `definePersona`, and `bind` are endpoint commands\n  ([\xA713.5](../SPEC.md#135-verbs)) any authorized node can send, policy-gated\n  ([identity & auth](identity-and-auth.md)). A caller learns them off the wire with `cotal\n  describe manager`; nothing is compiled in.\n- **Spawn is an action.** Asking for an agent no longer blocks the caller while the process\n  comes up. The manager accepts a spawn **goal** ([\xA713.6](../SPEC.md#136-composites)) and\n  immediately returns the allocated identity (the agent's name, its `owner`/`actor`/`uid`\n  triple, a `goalId`, and the executor coordinate `{lifecycleUid, epoch}`); progress events\n  then report the launch until a terminal outcome. Presence within the readiness window is\n  `succeeded`, an early exit is `failed`, and the window passing with neither is\n  `uncertain`: a bounded, reconcilable outcome a later `ps` settles against the live roster,\n  never a silent hang.\n- **Bounded spawn.** A gate caps concurrent and in-flight agents and a minimum-lifetime\n  floor bounds spawn/despawn churn, so a capability-holding but compromised peer cannot\n  fork-bomb the host. The gate runs at goal acceptance, before any identity is minted or\n  process launched, so a refused spawn leaves nothing behind.\n- **Declared environment boundary.** A spawned agent receives a fixed OS allow-list (PATH/HOME/\n  locale, including PATH entries connector binaries live in), the machine-wide `COTAL_*` operator\n  knobs, connector-declared provider inputs, explicitly shared MCP references, and names\n  deliberately added through `spawn.env`. It never inherits the manager's ambient environment, so\n  host-session markers (`CLAUDE_CODE_CHILD_SESSION` and the analogous names other hosts use) and\n  unrelated capabilities cannot become properties of every seat. Connection material rides a private\n  file instead of the environment.\n- **Instance addressing.** One space can hold more than one manager. Each keeps a stable\n  logical instance id across restarts and advances its process epoch when it comes back, so\n  peers address a specific manager without caring which process currently serves it. `cotal\n  spawn <persona> --detach --on <instance>` pins one instance (`ps`, `stop` and `attach` take\n  the same flag); an untargeted spawn rides class anycast and the acceptance records which\n  instance took it. `ps` and `status` scatter across every registered instance and label a\n  non-answering one as registered with no answer within the deadline, never dropping it.\n- **A manager holds a liveness lease, and nothing about it ends the process.** Each instance\n  keeps its own key in the space's manager bucket and refreshes it several times over inside the\n  key's TTL. A refresh that fails is a question, not a verdict, so the manager re-reads the key\n  before deciding what to do. If the key is still its own it adopts the broker's revision and\n  carries on. If the key is gone (it expired during a stall) it puts it back. If another process\n  holds it, it says so and keeps serving; which of the two goes is the operator's call. If the\n  broker cannot be asked at all it keeps serving and asks again, for as long as that takes. A\n  manager that cannot reach its broker gains nothing by ending itself, and the seats it holds\n  lose everything. Each change of state is one line in the manager's log, not one line per tick.\n- **Attach is a mesh session.** The console and dashboard discover agents over the **mesh**\n  (presence, `ps`). `cotal attach` no longer hands back a `127.0.0.1` URL: it redeems a\n  one-use, holder-bound session offer, and the terminal bytes stream over the mesh on\n  core-NATS session subjects scoped to the two parties, with backpressure surfaced as an\n  explicit drop notice rather than silent loss. Attach reaches managers on other machines through\n  the broker. The manager's own socket stays private. A late\n  attach still repaints the full screen from a replayed snapshot of a headless terminal\n  mirror (including alternate-screen TUIs). If the manager restarts, its successor refuses\n  the old session and the client surfaces \"manager restarted; re-attach\".\n- **The manager's console face is a separate, credentialed surface.** The manager still\n  serves the browser console over local HTTP: the static page plus the roster, the live feed,\n  and the route that mints the browser's own session. It binds loopback unless the operator\n  says otherwise (`cotal supervise --console-host`), and every route that carries mesh data\n  or mints a credential requires the manager's console token.\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Each managed agent runs under a durable **lifecycle**: a despawn retires it (settling\nand evicting the old incarnation) before its name frees for reuse, and a supervised restart\nrecovers the same lifecycle rather than minting a new one, so durables and credentials key\non the lifecycle, not the reusable name ([SPEC \xA713.1](../SPEC.md#131-lifecycle-identity);\n[identity & auth](identity-and-auth.md)). Destructive space-wide operations (history purge)\nstay operator-only.\n\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Addressing\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
     },
     {
       "slug": "mcp-tools",

package/dist/standalone.js

@@ -36567,6 +36567,14 @@ var CotalEndpoint = class _CotalEndpoint extends EventEmitter {
    *  reconnect calls it again after {@link clearConnectionScoped}; every binding is
    *  idempotent (durables bind by name, JetStream dedups by msgID, KV opens are idempotent). */
   async connectAndBind() {
+    try {
+      await this.bindConnection();
+    } catch (error51) {
+      await this.closeFailedBind();
+      throw error51;
+    }
+  }
+  async bindConnection() {
     this.clearConnectionScoped();
     if (this.bearerSource) {
       const stale = !this.currentBearer || bearerExpiryMs(this.currentBearer) - Date.now() < _CotalEndpoint.BEARER_REFRESH_MARGIN_MS;
@@ -36698,6 +36706,92 @@ var CotalEndpoint = class _CotalEndpoint extends EventEmitter {
         this.emit("error", err2);
       });
   }
+  /** A transport can connect before a later JetStream/KV/subscription bind fails. The caller will
+   * retry the whole start, so release that partial epoch first instead of overwriting `nc` and
+   * leaving one established socket behind per retry. `close()` is deliberate: a failed bind has no
+   * graceful delivery contract to drain, and cleanup itself must not extend the retry failure.
+   *
+   * A throwing `close()` is not hypothetical: nats.js `NatsConnectionImpl.close()` awaits the
+   * protocol close, which itself flushes outbound + tears down subscription state; any of those
+   * that reject leaves the underlying TCP transport ESTABLISHED even though every client handle
+   * on this endpoint has been cleared. The next `start()` on the same object then dials a fresh
+   * connection while the old socket stays live on the broker (`/varz.connections` climbs once per
+   * failed attempt). The recovery path is layered, from most graceful to most surgical, matching
+   * nats-core's public surface (nats.d.ts: `close`, `drain`, `isClosed`; protocol.d.ts owns the
+   * `transport` handle whose `close(err?)` is the socket teardown; transport.d.ts exposes a
+   * synchronous `disconnect()` for the case where even close rejects). We only touch a private
+   * (`nc.protocol.transport`) when the public API has already refused, and the ORIGINAL bind
+   * error is re-raised at every layer. The close error is diagnostic noise. The bind error is
+   * what the caller must see.
+   *
+   * The delivery-serve subs and `this.subs` array are handles created by a successful
+   * `armDeliveryControl` on a PREVIOUS epoch; a bind failure on the retry never rewrites them
+   * because arming is a late step. Left in place they point at a dead protocol and survive into
+   * the next retry. The reviewer flagged this as an untested handle class. Zero them here so a
+   * retry starts with the same empty state as a first attempt. */
+  async closeFailedBind() {
+    const failedNc = this.nc;
+    this.clearConnectionScoped();
+    this.nc = void 0;
+    this.js = void 0;
+    this.jsm = void 0;
+    this.kv = void 0;
+    this.channelKv = void 0;
+    this.membersKv = void 0;
+    this.aclKv = void 0;
+    this.membershipFeedKv = void 0;
+    this.deliveryKv = void 0;
+    this.managerLeaseKv = void 0;
+    if (this.deliveryServeSub) {
+      try {
+        this.deliveryServeSub.unsubscribe();
+      } catch {
+      }
+      this.deliveryServeSub = void 0;
+    }
+    if (this.deliveryAdminServeSub) {
+      try {
+        this.deliveryAdminServeSub.unsubscribe();
+      } catch {
+      }
+      this.deliveryAdminServeSub = void 0;
+    }
+    for (const sub of this.subs) {
+      try {
+        sub.unsubscribe();
+      } catch {
+      }
+    }
+    this.subs.length = 0;
+    if (!failedNc)
+      return;
+    try {
+      await failedNc.close();
+      return;
+    } catch {
+    }
+    if (!failedNc.isClosed?.()) {
+      try {
+        await failedNc.drain();
+        return;
+      } catch {
+      }
+    }
+    const proto = failedNc.protocol;
+    const transport = proto?.transport;
+    if (transport && !transport.isClosed) {
+      try {
+        await transport.close?.();
+      } catch {
+      }
+      if (!transport.isClosed) {
+        try {
+          transport.disconnect?.();
+        } catch {
+        }
+      }
+    }
+  }
   /** If stop() ran during a rebuild's `await connectAndBind`, the just-bound connection +
    *  heartbeat + supervisor would be left live on a stopped endpoint. Tear that fresh
    *  connection back down and report it. Reads `this.nc` in its own scope (a bare `this.nc`
@@ -56639,7 +56733,7 @@ config(en_default());
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.41.1",
+  "version": "0.41.3",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -56661,7 +56755,7 @@ var DOCS_BUNDLE = {
       "title": "Architecture",
       "kind": "Concept (informative)",
       "summary": "Cotal is built as a thin waist: the normative wire contract (subjects, message schemas, presence/discovery, delivery semantics, the auth grammar) is the standard (SPEC), and everything else is a pl\u2026",
-      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## A2A influence\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## NATS mapping\n\nThe messaging plane rides three subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)); the endpoint control surface adds its own rails\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| endpoint (control) | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026` ([\xA713.2](../SPEC.md#132-grammar)) |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the endpoint control surface on its own rails and streams\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)). Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches every contributed `kind:name`. Command metadata is cached for\n`--help`/completion; running a command or requesting a provider imports its owner lazily and\nuses the live object. Before that first import, the loader rebinds shared peers to the current\nhost under the extension-prefix lock; version skew or an unbindable peer fails loudly.\nThe repo's `@cotal-ai/web` dashboard and optional tmux/cmux/Orca/Herdr runtimes use this mechanism.\nRuntime resolution stays registry-driven and open-ended: a name with no registered/installed\nprovider fails loud (never a fallback), and a third-party runtime installs under its own package\nname. The CLI does carry a small, non-authoritative map of the first-party runtime names\n(`orca`/`tmux`/`cmux`/`herdr`) to their `@cotal-ai/*` packages, used only to print an exact `cotal ext add`\nhint for a known-but-uninstalled runtime and to list them in `cotal runtimes`; it never resolves or\nregisters a provider.\n\nMachine-local processes use the same registry. The base CLI contributes broker/control-plane\n`local-process` descriptors, while an installed package contributes its own (for example `web`).\nThat keeps `cotal down <component>` and `cotal status` extensible without teaching the base CLI\npackage-specific pidfiles. A provider process claims its declared pidfile with exclusive create;\nextension removal reserves that same path so startup cannot cross uninstall.\n\nBeyond the app-bound connectors, `@cotal-ai/pi` is a **host-native plugin**: a pi extension\nloaded into the user's own pi (CLI or SDK-embedded), placing a Cotal endpoint inside the\nsession's process and driving its run loop off the inbox. See\n[connect-pi](connect-pi.md).\n\n## Connector runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha), a host-native extension for\n[pi](connect-pi.md) (alpha). The [connectors matrix](connectors.md) compares them\nfeature-by-feature.\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A manual\n`/reconnect` is the human-invoked counterpart.\n\n## Manager supervision\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh. The manager is not a privileged control plane: it is an ordinary\nservice endpoint on the same `ep` rails as any other daemon\n([\xA713](../SPEC.md#13-endpoint-control-surface-v04)), holding only the capability rows its\ncallers grant it. It owns process lifecycle and config binding (start / stop / restart,\nbinding env and policy) and has no say in what work the agents do. Agents coordinate\nlaterally; the manager only births and configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`**, **`cmux`**, **`orca`**, and **`herdr`** are\n  extensions that put each teammate in its own native terminal surface (explicit opt-ins\n  that throw when the extension isn't loaded, never a silent fallback); **byo** is the\n  floor (a human's own terminal, tracked via presence); **host** (Agent SDK, true mid-turn\n  interrupt) is the documented upgrade path ([roadmap](roadmap.md)).\n- **Served commands.** `spawn` (an action, below), `stop`, `ps`, `status`, `attach`,\n  `models`, `definePersona`, and `bind` are endpoint commands\n  ([\xA713.5](../SPEC.md#135-verbs)) any authorized node can send, policy-gated\n  ([identity & auth](identity-and-auth.md)). A caller learns them off the wire with `cotal\n  describe manager`; nothing is compiled in.\n- **Spawn is an action.** Asking for an agent no longer blocks the caller while the process\n  comes up. The manager accepts a spawn **goal** ([\xA713.6](../SPEC.md#136-composites)) and\n  immediately returns the allocated identity (the agent's name, its `owner`/`actor`/`uid`\n  triple, a `goalId`, and the executor coordinate `{lifecycleUid, epoch}`); progress events\n  then report the launch until a terminal outcome. Presence within the readiness window is\n  `succeeded`, an early exit is `failed`, and the window passing with neither is\n  `uncertain`: a bounded, reconcilable outcome a later `ps` settles against the live roster,\n  never a silent hang.\n- **Bounded spawn.** A gate caps concurrent and in-flight agents and a minimum-lifetime\n  floor bounds spawn/despawn churn, so a capability-holding but compromised peer cannot\n  fork-bomb the host. The gate runs at goal acceptance, before any identity is minted or\n  process launched, so a refused spawn leaves nothing behind.\n- **Declared environment boundary.** A spawned agent receives a fixed OS allow-list (PATH/HOME/\n  locale, including PATH entries connector binaries live in), the machine-wide `COTAL_*` operator\n  knobs, connector-declared provider inputs, explicitly shared MCP references, and names\n  deliberately added through `spawn.env`. It never inherits the manager's ambient environment, so\n  host-session markers (`CLAUDE_CODE_CHILD_SESSION` and the analogous names other hosts use) and\n  unrelated capabilities cannot become properties of every seat. Connection material rides a private\n  file instead of the environment.\n- **Instance addressing.** One space can hold more than one manager. Each keeps a stable\n  logical instance id across restarts and advances its process epoch when it comes back, so\n  peers address a specific manager without caring which process currently serves it. `cotal\n  spawn <persona> --detach --on <instance>` pins one instance (`ps`, `stop` and `attach` take\n  the same flag); an untargeted spawn rides class anycast and the acceptance records which\n  instance took it. `ps` and `status` scatter across every registered instance and label a\n  non-answering one as registered with no answer within the deadline, never dropping it.\n- **A manager holds a liveness lease, and nothing about it ends the process.** Each instance\n  keeps its own key in the space's manager bucket and refreshes it several times over inside the\n  key's TTL. A refresh that fails is a question, not a verdict, so the manager re-reads the key\n  before deciding what to do. If the key is still its own it adopts the broker's revision and\n  carries on. If the key is gone (it expired during a stall) it puts it back. If another process\n  holds it, it says so and keeps serving; which of the two goes is the operator's call. If the\n  broker cannot be asked at all it keeps serving and asks again, for as long as that takes. A\n  manager that cannot reach its broker gains nothing by ending itself, and the seats it holds\n  lose everything. Each change of state is one line in the manager's log, not one line per tick.\n- **Attach is a mesh session.** The console and dashboard discover agents over the **mesh**\n  (presence, `ps`). `cotal attach` no longer hands back a `127.0.0.1` URL: it redeems a\n  one-use, holder-bound session offer, and the terminal bytes stream over the mesh on\n  core-NATS session subjects scoped to the two parties, with backpressure surfaced as an\n  explicit drop notice rather than silent loss. Attach reaches managers on other machines through\n  the broker. The manager's own socket stays private. A late\n  attach still repaints the full screen from a replayed snapshot of a headless terminal\n  mirror (including alternate-screen TUIs). If the manager restarts, its successor refuses\n  the old session and the client surfaces \"manager restarted; re-attach\".\n- **The manager's console face is a separate, credentialed surface.** The manager still\n  serves the browser console over local HTTP: the static page plus the roster, the live feed,\n  and the route that mints the browser's own session. It binds loopback unless the operator\n  says otherwise (`cotal supervise --console-host`), and every route that carries mesh data\n  or mints a credential requires the manager's console token.\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Each managed agent runs under a durable **lifecycle**: a despawn retires it (settling\nand evicting the old incarnation) before its name frees for reuse, and a supervised restart\nrecovers the same lifecycle rather than minting a new one, so durables and credentials key\non the lifecycle, not the reusable name ([SPEC \xA713.1](../SPEC.md#131-lifecycle-identity);\n[identity & auth](identity-and-auth.md)). Destructive space-wide operations (history purge)\nstay operator-only.\n\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Addressing\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
+      "body": "# Architecture\n\n> **Concept** (informative) \xB7 **For:** anyone who wants to know how Cotal is built, and why \xB7 **Normative:** [SPEC](../SPEC.md)\n\nCotal is built as a thin waist: the normative wire contract (subjects, message schemas,\npresence/discovery, delivery semantics, the auth grammar) is the standard\n([SPEC](../SPEC.md)), and everything else is a pluggable edge over existing building\nblocks. Identity, transport, storage, and discovery compose from proven pieces (NATS,\nJetStream, JWT/nkeys) rather than being reinvented. Adapters stay thin and swappable, and\nnothing adapter-specific leaks into the core.\n\n## A2A influence\n\nCotal reuses A2A's vocabulary and shapes so it stays interoperable rather than siloed, and\nimplements them over NATS/JetStream.\n\n**From A2A** come the *data shapes*: `AgentCard` (identity / role / tags / skills),\n`Message` / `Part` (text and data), and correlation ids (`contextId`). We do not adopt\nA2A's HTTP/JSON-RPC transport, `Task` RPCs, or its request/response server model, none of\nwhich fit lateral pub/sub.\n\nThe *addressing model* is Cotal's own: the hierarchical address `space / service / instance`\nand three delivery modes, multicast, unicast, anycast\n([presence & delivery](presence-and-delivery.md)). **Mentions** are a priority hint on a\nmulticast, not a routing target. NATS/JetStream is the data plane, adding the durability and\npresence a bare pub/sub layer leaves to the app.\n\nIdentity is an A2A `AgentCard` whose instance id is shaped to later become a **DID**\n(`did:key`) so authenticity can survive an untrusted relay ([roadmap](roadmap.md)).\n\n## NATS mapping\n\nThe messaging plane rides three subject kinds, with the sender encoded in the subject\nitself, where the server can police it, rather than in a self-asserted payload field\n([SPEC \xA73](../SPEC.md#3-subject-layout)); the endpoint control surface adds its own rails\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)):\n\n| Delivery | Subject |\n|---|---|\n| multicast | `cotal.<space>.chat.<owner>.<actor>.<channel\u2026>` |\n| unicast | `cotal.<space>.inst.<toOwner>.<toActor>.<owner>.<actor>` |\n| anycast | `cotal.<space>.svc.<role>.<owner>.<actor>` |\n| endpoint (control) | `cotal.<space>.ep.<one\\|all\\|inst\\|reply>.\u2026` ([\xA713.2](../SPEC.md#132-grammar)) |\n\nThe sender is a **principal**, an `owner.actor` pair: the account the agent acts on behalf\nof, then the agent's own handle under it ([identity & auth](identity-and-auth.md)). Two\ntokens instead of one means the broker can deny cross-owner *and* same-owner cross-actor\nforgery in the subject grammar itself.\n\nBehind the subjects, each space gets three **JetStream streams** (chat / DM / task, for\nstorage, per-reader bookmarks, and history), **KV buckets** for presence and the channel\nregistry, and the endpoint control surface on its own rails and streams\n([SPEC \xA713](../SPEC.md#13-endpoint-control-surface-v04)). Rather than re-implementing delivery\nguarantees, Cotal uses the native NATS mechanisms: streams for at-least-once and late\njoin, queue groups for anycast load-balancing, KV TTL for liveness ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding);\nthe reasoning: [presence & delivery](presence-and-delivery.md)). Isolation is one NATS\n**account per space** ([spaces & channels](spaces.md)); authorization is per-agent JWT\nACLs ([identity & auth](identity-and-auth.md)). Large artifacts are reserved for a\nper-space Object Store ([roadmap](roadmap.md)).\n\nWhether any of this *requires* NATS is answered in\n[transport vs protocol](transport.md): the contract is transport-agnostic; NATS/JetStream\nis the reference binding.\n\n## Package layout\n\n```\nexamples \u2500\u2500\u2192 implementations \u2500\u2500\u2192 workspace \u2500\u2500\u2192 core \u2190(peer)\u2500\u2500 extensions\n                (interoperate at runtime over NATS, not via imports)\n```\n\n- **`@cotal-ai/core`**, the protocol: subjects, schemas, the NATS client layer, and the\n  extension contracts (`Connector`, `Command`, `Runtime`) with the `Registry` they\n  self-register into. Depends on nothing else in the repo.\n- **`@cotal-ai/workspace`**, the machine-local operator layer over `~/.cotal`: mesh\n  registry, target resolution, auth-path helpers. Not part of the wire standard, so a\n  third party can embed core without inheriting workstation plumbing.\n- **`extensions/*`**: pluggable adapters (connectors, runtimes). Each **peer-depends** on\n  core (binding to the host's single core instance) and self-registers on import; an\n  unknown agent type **throws**, no silent fallback.\n- **`implementations/*`**, opinionated surfaces over core: the CLI, the manager, the\n  delivery daemon, the web dashboard. Implementations never import each other; they meet\n  at runtime, in a shared space over NATS. A composition root (the `cotal` binary, or an\n  example) wires the pieces it wants.\n- **`examples/*`**: use-cases and composition roots, never published\n  ([examples](examples.md)). An example only configures and orchestrates; new message\n  kinds or subjects go into core, generalized, never into an example.\n\nThe published binary also loads **operator-installed extensions**: `cotal ext add\n<npm-package>` installs into a cotal-owned prefix, imports once so the package\nself-registers, then caches every contributed `kind:name`. Command metadata is cached for\n`--help`/completion; running a command or requesting a provider imports its owner lazily and\nuses the live object. Before that first import, the loader rebinds shared peers to the current\nhost under the extension-prefix lock; version skew or an unbindable peer fails loudly.\nThe repo's `@cotal-ai/web` dashboard and optional tmux/cmux/Orca/Herdr runtimes use this mechanism.\nRuntime resolution stays registry-driven and open-ended: a name with no registered/installed\nprovider fails loud (never a fallback), and a third-party runtime installs under its own package\nname. The CLI does carry a small, non-authoritative map of the first-party runtime names\n(`orca`/`tmux`/`cmux`/`herdr`) to their `@cotal-ai/*` packages, used only to print an exact `cotal ext add`\nhint for a known-but-uninstalled runtime and to list them in `cotal runtimes`; it never resolves or\nregisters a provider.\n\nMachine-local processes use the same registry. The base CLI contributes broker/control-plane\n`local-process` descriptors, while an installed package contributes its own (for example `web`).\nThat keeps `cotal down <component>` and `cotal status` extensible without teaching the base CLI\npackage-specific pidfiles. A provider process claims its declared pidfile with exclusive create;\nextension removal reserves that same path so startup cannot cross uninstall.\n\nBeyond the app-bound connectors, `@cotal-ai/pi` is a **host-native plugin**: a pi extension\nloaded into the user's own pi (CLI or SDK-embedded), placing a Cotal endpoint inside the\nsession's process and driving its run loop off the inbox. See\n[connect-pi](connect-pi.md).\n\n## Connector runtime\n\nEvery coding-agent integration exposes the same four surfaces:\n\n| Surface | Carries |\n|---|---|\n| Outbound, ambient | lifecycle \u2192 presence and activity, automatically |\n| Outbound, deliberate | the messaging tools (`cotal_send` / `cotal_dm` / `cotal_anycast`) |\n| Inbound, pull | `cotal_inbox` |\n| Inbound, push | wake-and-inject into the live session |\n\nThe shared runtime lives in [`@cotal-ai/connector-core`](../extensions/connector-core):\nthe mesh agent, the [`cotal_*` tool surface](mcp-tools.md) (defined once in its tool\nspecs, so it cannot drift across hosts), and the delivery buffer with its attention\npolicy. Each adapter is a thin client\nover it that binds to its host's native mechanism: an installed plugin + MCP server for\n[Claude Code](connect-claude.md), an in-process plugin for\n[OpenCode](connect-opencode.md) (beta), a Python sidecar for\n[Hermes](connect-hermes.md) (alpha), a host-native extension for\n[pi](connect-pi.md) (alpha). The [connectors matrix](connectors.md) compares them\nfeature-by-feature.\n\nThe endpoint underneath self-heals: when the transport connection dies terminally, a\nsupervisor rebuilds it (rebuilds are serialized and coalesced), and unacked in-flight\nmessages redeliver on the rebound durables, so nothing is lost across the gap. A failed\npost-connect bind closes its partial transport before the retry loop starts another attempt.\nA manual `/reconnect` is the human-invoked counterpart.\n\n## Manager supervision\n\nThe CLI does not spawn agents itself; a long-lived **manager** owns their lifecycle,\nasked over the mesh. The manager is not a privileged control plane: it is an ordinary\nservice endpoint on the same `ep` rails as any other daemon\n([\xA713](../SPEC.md#13-endpoint-control-surface-v04)), holding only the capability rows its\ncallers grant it. It owns process lifecycle and config binding (start / stop / restart,\nbinding env and policy) and has no say in what work the agents do. Agents coordinate\nlaterally; the manager only births and configures them.\n\n- **Off the message hot path.** Each agent self-connects to the mesh through its own\n  connector. The manager owns processes in order to control them, but observes everything\n  through presence, so a bring-your-own-terminal agent it never spawned still shows up in\n  `ps`.\n- **Pluggable runtimes.** Spawning is abstracted behind a `Runtime` contract (like pm2 or\n  docker for agent TUIs): **`pty`** ships built-in (the manager owns a pseudo-terminal;\n  watch or type via `cotal attach`); **`tmux`**, **`cmux`**, **`orca`**, and **`herdr`** are\n  extensions that put each teammate in its own native terminal surface (explicit opt-ins\n  that throw when the extension isn't loaded, never a silent fallback); **byo** is the\n  floor (a human's own terminal, tracked via presence); **host** (Agent SDK, true mid-turn\n  interrupt) is the documented upgrade path ([roadmap](roadmap.md)).\n- **Served commands.** `spawn` (an action, below), `stop`, `ps`, `status`, `attach`,\n  `models`, `definePersona`, and `bind` are endpoint commands\n  ([\xA713.5](../SPEC.md#135-verbs)) any authorized node can send, policy-gated\n  ([identity & auth](identity-and-auth.md)). A caller learns them off the wire with `cotal\n  describe manager`; nothing is compiled in.\n- **Spawn is an action.** Asking for an agent no longer blocks the caller while the process\n  comes up. The manager accepts a spawn **goal** ([\xA713.6](../SPEC.md#136-composites)) and\n  immediately returns the allocated identity (the agent's name, its `owner`/`actor`/`uid`\n  triple, a `goalId`, and the executor coordinate `{lifecycleUid, epoch}`); progress events\n  then report the launch until a terminal outcome. Presence within the readiness window is\n  `succeeded`, an early exit is `failed`, and the window passing with neither is\n  `uncertain`: a bounded, reconcilable outcome a later `ps` settles against the live roster,\n  never a silent hang.\n- **Bounded spawn.** A gate caps concurrent and in-flight agents and a minimum-lifetime\n  floor bounds spawn/despawn churn, so a capability-holding but compromised peer cannot\n  fork-bomb the host. The gate runs at goal acceptance, before any identity is minted or\n  process launched, so a refused spawn leaves nothing behind.\n- **Declared environment boundary.** A spawned agent receives a fixed OS allow-list (PATH/HOME/\n  locale, including PATH entries connector binaries live in), the machine-wide `COTAL_*` operator\n  knobs, connector-declared provider inputs, explicitly shared MCP references, and names\n  deliberately added through `spawn.env`. It never inherits the manager's ambient environment, so\n  host-session markers (`CLAUDE_CODE_CHILD_SESSION` and the analogous names other hosts use) and\n  unrelated capabilities cannot become properties of every seat. Connection material rides a private\n  file instead of the environment.\n- **Instance addressing.** One space can hold more than one manager. Each keeps a stable\n  logical instance id across restarts and advances its process epoch when it comes back, so\n  peers address a specific manager without caring which process currently serves it. `cotal\n  spawn <persona> --detach --on <instance>` pins one instance (`ps`, `stop` and `attach` take\n  the same flag); an untargeted spawn rides class anycast and the acceptance records which\n  instance took it. `ps` and `status` scatter across every registered instance and label a\n  non-answering one as registered with no answer within the deadline, never dropping it.\n- **A manager holds a liveness lease, and nothing about it ends the process.** Each instance\n  keeps its own key in the space's manager bucket and refreshes it several times over inside the\n  key's TTL. A refresh that fails is a question, not a verdict, so the manager re-reads the key\n  before deciding what to do. If the key is still its own it adopts the broker's revision and\n  carries on. If the key is gone (it expired during a stall) it puts it back. If another process\n  holds it, it says so and keeps serving; which of the two goes is the operator's call. If the\n  broker cannot be asked at all it keeps serving and asks again, for as long as that takes. A\n  manager that cannot reach its broker gains nothing by ending itself, and the seats it holds\n  lose everything. Each change of state is one line in the manager's log, not one line per tick.\n- **Attach is a mesh session.** The console and dashboard discover agents over the **mesh**\n  (presence, `ps`). `cotal attach` no longer hands back a `127.0.0.1` URL: it redeems a\n  one-use, holder-bound session offer, and the terminal bytes stream over the mesh on\n  core-NATS session subjects scoped to the two parties, with backpressure surfaced as an\n  explicit drop notice rather than silent loss. Attach reaches managers on other machines through\n  the broker. The manager's own socket stays private. A late\n  attach still repaints the full screen from a replayed snapshot of a headless terminal\n  mirror (including alternate-screen TUIs). If the manager restarts, its successor refuses\n  the old session and the client surfaces \"manager restarted; re-attach\".\n- **The manager's console face is a separate, credentialed surface.** The manager still\n  serves the browser console over local HTTP: the static page plus the roster, the live feed,\n  and the route that mints the browser's own session. It binds loopback unless the operator\n  says otherwise (`cotal supervise --console-host`), and every route that carries mesh data\n  or mints a credential requires the manager's console token.\n\nThe result is that an agent can grow and shape its own team: ask for a teammate\n(`cotal_spawn`), mint a persona on the fly (`cotal_persona`), or tear one down\n(`cotal_despawn`). Every newcomer joins as a peer, not as a child of whoever requested\nit. Each managed agent runs under a durable **lifecycle**: a despawn retires it (settling\nand evicting the old incarnation) before its name frees for reuse, and a supervised restart\nrecovers the same lifecycle rather than minting a new one, so durables and credentials key\non the lifecycle, not the reusable name ([SPEC \xA713.1](../SPEC.md#131-lifecycle-identity);\n[identity & auth](identity-and-auth.md)). Destructive space-wide operations (history purge)\nstay operator-only.\n\n\n## Observers\n\nA watch surface is a read-only observer: an endpoint that consumes without registering\npresence (invisible to peers) while watching everyone else's. All three surfaces\n(terminal console, plain stream, web dashboard) derive from that one observer through a\nshared render-agnostic model, so no surface re-implements wire semantics. The guide is\n[watch a mesh](watch-a-mesh.md); the model is [MeshView](mesh-view.md).\n\n## Addressing\n\nThree identity layers, in increasing permanence\n([SPEC \xA72](../SPEC.md#2-identity), [\xA76](../SPEC.md#6-presence-and-discovery)):\n\n- **`name`** is a cosmetic, reusable human handle. Addressing by name is best-effort\n  convenience, with deterministic and fail-loud resolution: a unique live name resolves,\n  and a collision among live peers throws with the candidate ids rather than silently\n  picking one. The manager auto-numbers its own spawns (`reviewer` \u2192 `reviewer-2`).\n- **`role`** is the addressable service, which makes it the anycast address:\n  `svc.reviewer` reaches \"whoever is a reviewer\", so the label carries routing meaning.\n- **The instance id** is the authoritative address: the presence key, the unicast target,\n  the credential subject.\n\n**Instance continuity:** the id tracks *context* continuity, not the label. A resumed\nsession (same context window) keeps its id; presence, thread correlation, and in-flight\nDMs stay continuous. A fresh context, even reusing the name, is a **new** instance with a\nnew id: reusing an id across a discontinuous context would tell peers \"same agent, same\nmemory\" when the new session has none. One deliberate exception: OpenCode's `/new` inside\nthe same managed process keeps the mesh identity and advances only the thread correlation\nid: process continuity, not credential reuse.\n\n## Deferred\n\nSessions/moderator, signed envelopes + DID identity, instant offline, artifact delivery,\nauth-callout, and federation are designed for but not built yet; each is tracked, with\nits direction, in the [roadmap](roadmap.md).\n"
     },
     {
       "slug": "mcp-tools",

package/package.json

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