@ours.network/fleet 1.1.0 → 1.1.1

package/README.md

@@ -865,6 +865,60 @@ still up after 2 minutes the monitor gives up on that wake and records
 queued and its cursor is not committed until a later delivery is accepted). The
 agent's briefing tells it **not** to arm a native harness Monitor.
 
+Managed ACP sessions can opt into bounded stall recovery independently of mail delivery:
+
+```yaml
+monitor:
+  mode: fleet
+  stall_recovery: true       # omitted/false preserves existing behavior
+  stall_timeout_ms: 900000   # 15 minutes; integer 60000–86400000
+```
+
+The ACP session measures silence from its last live reasoning, output, plan, or tool
+update, excluding replay and retry/status chatter. It requires observable progress
+before detecting a stall. Repeated structured Codex response-stream retry errors
+can confirm a stall after one window; generic silence requires two windows (30
+minutes by default). Codex ACP 1.1.7 exposes no native-turn mapping, so strong retry
+evidence is used only on the first fresh, unsteered managed turn. Later and resumed
+turns use the generic path. Assistant text and stderr never authenticate a retry.
+
+Active tools, pending permissions, modal/unknown adapter status, unknown tool
+boundaries, in-flight steering, human cancellation, and shutdown prevent automatic
+interruption. Tool IDs are stored as a bounded set of hashes before the watchdog relies on their
+boundaries. Reuse across any ordinary or diagnostic turn, including after resume,
+makes the boundary uncertain; delayed terminal events cannot authorize cancellation.
+Missing, damaged, or exhausted history disables automatic cancellation and reports
+`blocked_evidence` after the conservative silence window.
+An untracked steering-started turn is left alone. A tracked turn with no meaningful
+event reports `blocked_evidence` after two windows from admission; turn age alone
+never authorizes cancellation.
+Native monitoring and non-ACP backends do not run this watchdog.
+
+Recovery sends one explicit ACP cancel, waits at most 15 seconds for settlement,
+and submits a diagnostic continuation in the same session and queue slot. Startup
+and queued prompts remain behind that continuation. It instructs the agent to check
+recorded terminal events and never replay ambiguous or completed side effects.
+The watchdog never kills, restarts, or respawns the adapter. Error/refusal settlement of cancellation reports a blocker without failing startup.
+A refused/failed or re-stalled continuation emits an actionable blocker without another cancellation;
+startup remains supervised when diagnostic recovery reports a blocker.
+
+The durable claim is deliberately stricter than one attempt per turn: at most one
+automatic recovery per ACP session ID, including after a supervisor restart. No
+claim is automatically cleared, even if incomplete. Its queue-only monitor policy
+is restored before admission on supervisor restart. During and after that attempt,
+mail wakes use queued delivery for all `monitor.interrupt` policies; explicit human
+interrupts retain their existing authority and supersede pending recovery. The
+`after_tool` timeout alone never authorizes watchdog cancellation. The feature must
+be enabled explicitly even when mail uses `interrupt: true` or `after_tool`.
+
+Body-free claim and audit records live under `<agentDir>/.stall-recovery/`; typed
+`stall_recovery` events and fixed supervisor log messages expose outcomes. Session
+and turn identifiers are hashed; prompt bodies, tool outputs, credentials, and
+workspace paths are excluded. On `blocked_*`, inspect the structured session events,
+verify completed actions, then continue manually if safe or report the remaining
+blocker. Do not clear a claim to retry an uncertain interruption. No room integration
+or identity binding is needed.
+
 With `monitor.mode: native`, ours-fleet does not start its supervisor monitor;
 the generated briefing instead instructs the harness to arm its own wake
 mechanism (the structured `ours api watch-notifications` JSONL stream for Claude Code,

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.1.0",
-  "buildId": "6a76080fd007",
-  "commit": "818954bbd80a4eb2c184af8cc784b98cc214c0e9",
+  "version": "1.1.1",
+  "buildId": "24bc68cc8165",
+  "commit": "f146310c646c05b381b1bada8d782fcfd3c47b25",
   "dirty": false,
-  "builtAt": "2026-09-05T14:01:06.755Z",
+  "builtAt": "2026-09-05T20:37:21.457Z",
   "capabilities": [
     "monitor.interrupt.after_tool"
   ]

package/dist/config.d.ts

@@ -68,6 +68,10 @@ export interface MonitorConfig {
      * a positive integer; resolved default is 3. Optional so old snapshots resolve.
      */
     turn_fail_threshold?: number;
+    /** Opt-in bounded ACP no-progress recovery; independent of mail interruption policy. */
+    stall_recovery?: boolean;
+    /** Progress silence window; default 15 minutes. Generic silence requires two windows. */
+    stall_timeout_ms?: number;
 }
 /** A trusted, fleet-owned ours mailbox which is never bound inside the agent. */
 export interface OwnerChannelConfig {

package/dist/config.js

@@ -27,7 +27,7 @@ export const NOTIFY_EVENT_TYPES = [
 /** Default wake sources when a role does not list its own. */
 export const DEFAULT_WAKE_SOURCES = ['message_received', 'file_received', 'local_contact_request', 'pending_message'];
 const MONITOR_KEYS = [
-    'mode', 'enabled', 'wake_sources', 'batch_ms', 'inject', 'interrupt', 'turn_fail_threshold',
+    'mode', 'enabled', 'wake_sources', 'batch_ms', 'inject', 'interrupt', 'turn_fail_threshold', 'stall_recovery', 'stall_timeout_ms',
 ];
 const INJECT_MODES = ['notification', 'full'];
 const MONITOR_MODES = ['fleet', 'native'];
@@ -74,6 +74,12 @@ export function validateMonitorConfig(raw, capabilities = CAPABILITIES) {
         && (typeof m.turn_fail_threshold !== 'number' || !Number.isInteger(m.turn_fail_threshold)
             || m.turn_fail_threshold < 1))
         problems.push('monitor.turn_fail_threshold: must be a positive integer');
+    if (m.stall_recovery !== undefined && typeof m.stall_recovery !== 'boolean')
+        problems.push('monitor.stall_recovery: must be true or false');
+    if (m.stall_timeout_ms !== undefined
+        && (typeof m.stall_timeout_ms !== 'number' || !Number.isSafeInteger(m.stall_timeout_ms)
+            || m.stall_timeout_ms < 60_000 || m.stall_timeout_ms > 86_400_000))
+        problems.push('monitor.stall_timeout_ms: must be an integer between 60000 and 86400000');
     if (m.wake_sources !== undefined) {
         if (!Array.isArray(m.wake_sources))
             problems.push('monitor.wake_sources: must be a list');
@@ -1164,6 +1170,8 @@ export function resolveMonitorConfig(defMonitor, roleMonitor, labels = {}) {
         batch_ms: merged.batch_ms ?? MONITOR_DEFAULT_BATCH_MS,
         inject: merged.inject ?? 'notification',
         interrupt: merged.interrupt ?? false,
+        ...(merged.stall_recovery !== undefined ? { stall_recovery: merged.stall_recovery } : {}),
+        ...(merged.stall_timeout_ms !== undefined ? { stall_timeout_ms: merged.stall_timeout_ms } : {}),
         turn_fail_threshold: merged.turn_fail_threshold ?? MONITOR_DEFAULT_TURN_FAIL_THRESHOLD,
     };
 }

package/dist/docs.d.ts

@@ -4,7 +4,7 @@
  * Keep this concise enough to place directly in an agent context. Unlike
  * Commander's per-command help, this describes how the pieces compose.
  */
-export declare const AI_DOCS = "# ours-fleet reference\n\nours-fleet runs persistent or temporary, identity-bound AI roles through a\nprovider-neutral managed-session interface:\n\n- harness: `claude-code` or `codex`\n- session: `acp` (default) or `codex-app-server` (Codex only)\n- lifetime: permanent (supervised, restartable) or `spawn --temp`\n\n## Discover and validate\n\n```sh\nours-fleet docs                         # this complete reference (`man` is an alias)\nours-fleet help <command>               # exact flags for one command\nours-fleet config [-c FILE]             # validate and print the merged plan; no changes\nours-fleet doctor [-c FILE] [--harness codex|claude-code]\nours-fleet version [--json]             # build identity, capabilities, every install on PATH\n```\n\nConfiguration v2 is `~/fleet.yaml` plus typed bare documents under the exact\nstem directories `~/fleet/agents`, `~/fleet/agent_templates`, `~/fleet/roles`, `~/fleet/brains`, and\n`~/fleet/room_templates`.\nThe manifest owns fleet-wide operational defaults and automation; each Agent\nselects one inline/ref Role and Brain and carries its operational fields.\nAgent Templates under `~/fleet/agent_templates` are inert reusable launch definitions;\nonly explicit files under `~/fleet/agents` are persistent lifecycle instances.\nRoom members use `agent_template` and receive immutable content-addressed snapshots.\nAn Agent Template may declare up to 64 temporary-only named `loops`; persistent Agent\ninstances reject them. Each loop requires `interval` (1m..30d) and bounded\nnonblank `prompt`, with optional `enabled` (default true), `initial_delay`\n(default interval, 0s..30d), and `jitter` (default 0s, < interval, <=1h).\nExecution is fixed skip-if-busy with no ordinary missed-tick backlog/replay;\nrestart recovery may preserve at most one recent late occurrence.\nLegacy top-level `roles:` and `fleet.d` are rejected. Validate the complete\ntrusted source set with `config` and `doctor` before starting or restarting.\n\nPermanent `spawn` writes `~/fleet/agents/Name.yaml`. The web console edits an\nexplicit `{manifest, agents, agent_templates}` model while Role/Brain presets remain read-only.\nIts aggregate revision includes every Agent/Role/Brain/Room-template source, previews a\nredacted per-document diff in an exact-stem private staging tree, and saves under\none root lock with a private multi-file backup and full rollback. A no-op is\nbyte-identical and creates no backup.\n\n## Build identity and install provenance\n\n`--version` prints a semver and nothing else, and a semver does NOT identify an\nartifact. Version bumps land in a release commit of their own, so every build cut\nbetween two releases carries the PREVIOUS version while already containing new\nbehaviour. One host ran two installs that both reported 0.16.0 \u2014 same version,\ndifferent build. One accepted `monitor.interrupt: after_tool`, the other\nrejected it as invalid. Their\n`dist/cli.js` were byte-identical \u2014 the divergence was in other modules.\n\nEvery build therefore stamps `dist/build-info.json` with a build id (first 12 hex\nof a sha256 over the rest of `dist/`), the commit it was cut from, and the\ncapability tokens the shipped code declares \u2014 for example\n`monitor.interrupt.after_tool`. Ask any executable what it is:\n\n```sh\nours-fleet version                      # ours-fleet 0.17.0+9f1c2a3b4d5e, capabilities, PATH installs\nours-fleet version --json               # the same as machine-readable JSON, no environment values\n```\n\nRead a capability, never a version number, to decide whether a setting is\nsupported. When a build rejects a value it knows the name of, it says which\ncapability is missing and which build rejected it, because another install on the\nsame host may accept the identical file. `config` prints the build that resolved\nthe plan; `status <Name>` says so when the build reporting on a role is not the\none that created it (roles record their creating build in `creation.json`).\n\n`ours-fleet doctor` runs an `install` check that lists every `ours-fleet` on\nPATH plus the one executing, and FAILS when two installs share a semver but are\ndifferent builds, or when the running artifact is a DIFFERENT artifact from the\none PATH resolves to. A second prefix holding identical content is not a skew\nand is not reported. A PATH entry the shell would not execute \u2014 a directory, or\na file without its execute bit \u2014 is not counted as an install at all.\nInstalls built before this stamp existed report `+unknown`; they are compared by\nhashing their `dist/` instead, so two pre-provenance installs are still told\napart. To fix a flagged host, remove or update the stale install \u2014 do not rely on\nPATH order.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init [-c FILE]               # interactive missing-default seed; TTY required\nours-fleet up|down [Name...]\nours-fleet restart [Name...]            # preserve/resume harness context\nours-fleet force-restart [Name...]      # fresh context; briefing is reloaded\nours-fleet ls\nours-fleet status|peek|attach|logs Name\nours-fleet logs -f Name\nours-fleet send Name \"prompt\"\nours-fleet rm Name\nours-fleet watchdog-report <name> [run-id] [--list] [--json]\nours-fleet watchdog-run <name>\n```\n\n`init` is an interactive missing-default workflow that preserves existing files byte-for-byte.\nIt names the resolved manifest and split directory, asks a default-No confirmation,\nthen subscriptions (Codex, Claude, or both), model assignment (one explicit model for\nevery job or explicit development/review/coordination choices), one reasoning level,\nand a final default-No review. Quick/Balanced/Thorough generate low/medium/high.\nModel pickers show packaged supported IDs; catalog membership is not a recommendation\nor entitlement claim. Run `ours-fleet doctor` for local Codex availability; Claude\nentitlement is checked when a role launches. The generated brains contain no\n`model_chain`, so Fleet never silently substitutes another model.\n\nAt either confirmation, N, Enter, Escape, Ctrl-C, Ctrl-D, or EOF cancels. In a picker,\nEscape, Ctrl-C, Ctrl-D, or EOF cancels; Enter records the highlight or continues a\nnon-empty multi-select, N is ignored, and an empty subscription selection remains blocked.\nEvery cancellation before final approval performs no host or configuration mutation.\nRedirected/non-TTY invocation is refused with the same guarantee. After the final Yes,\nhost setup precedes publication. Path ownership/type/mode/symlink and\nsame-filesystem checks run before host setup and again under a per-setup lock. Publication\nstages and validates the complete combined setup, backs up whichever old target(s) exist,\nand retains a private recovery record. A hard process/host termination cannot promise\nrollback; inspect host integration and private init stage/recovery evidence.\n\n`peek`, `attach`, and text `send` use the structured agent session.\nAttachment also accepts `/permit <permission-id> <option-id>`, `/interrupt`,\nand `/detach`.\n\n## Local web console\n\nThe npm package includes the web console; installed users do not clone the repo\nor run `npm run build`:\n\n```sh\nnpm i -g @ours.network/fleet\nours-fleet init\nours-fleet doctor\nours-fleet web                         # install/update service, start, pair browser\n```\n\nThe normal command uses stable `http://127.0.0.1:49271/`, installs an\nowner-level systemd user service (Linux) or LaunchAgent (macOS), and opens a\nfive-minute one-use pairing link in the local browser. After pairing, bookmark\nthe plain URL or install the PWA. To pair a new, signed-out, or revoked browser,\nrun `ours-fleet web open`.\n\n```sh\nours-fleet web status\nours-fleet web start|stop|restart\nours-fleet web open\nours-fleet web revoke-all              # revoke every browser and active session\nours-fleet web uninstall\nours-fleet web serve --port 0 --no-open # isolated foreground/testing mode\n```\n\nThe console is IPv4-loopback-only by default. Both `localhost` and\n`127.0.0.1` are accepted locally. For an nginx/TLS reverse proxy, keep the\ndefault bind and declare the exact browser origin:\n\n`ours-fleet web install --public-origin https://fleet.example.com --password-file /secure/fleet-password`\n\nFleet reads the password file during setup and persists only a salted scrypt\nverifier. New browsers authenticate and retain rotating HttpOnly/SameSite\ntrusted-device credentials. If nginx already authenticates, the operator may\ndeliberately select `--no-password`; the CLI and browser warn that anyone\nreaching the origin can control the fleet. First setup requires an explicit\nchoice: `--password-file` or `--pairing` for protected access, or\n`--no-password` for intentional unprotected access.\n\nUse `--bind ADDRESS` only for an intentional direct listen. A non-loopback\nbind is rejected unless `--public-origin` is also present. Host/Origin checks\nuse the declaration and do not trust forwarded headers. Configure nginx to\nproxy HTTP and WebSocket upgrades to `127.0.0.1:49271` and terminate TLS;\nfleet accepts nginx's loopback upstream Host, so no Host rewrite is required.\nBrowser credentials add Secure for HTTPS, and `revoke-all` invalidates all\ntrusted devices. Role creation offers harness-scoped known-model choices\nwhile still accepting a typed model ID; blank explicitly uses the selected\nharness's own default.\n\n## Spawn\n\n```sh\nours-fleet spawn [--temp] [Name | --name Name] \\\n  --brain BRAIN_ID --role ROLE_ID \\\n  --cwd /absolute/path --identity Identity --coordinator Coordinator \\\n  --approval ask|auto|allow \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait --isolation-file /path/isolation.yaml\n```\n\nPermanent spawn writes `~/fleet/agents/Name.yaml` and starts a supervised role.\n`--temp` writes active state under `~/.ours-fleet/tmp` and starts an independent\ntransient supervisor (a collected systemd unit or submitted launchd job). It is\nnot enabled across reboot and does not die when the role that spawned it restarts.\nBrain definitions own the managed session backend. When a temporary role's bound identity\ncloses or its session ends, the supervisor, monitor and live roster entry retire\ntogether; state moves intact to `~/.ours-fleet/recovery/temporary` with a\ntermination record. Failed launches use the same archive rather than deleting\ntheir briefing, provenance, logs or partial supervisor metadata.\n\nNamed `down` and `rm` commands can target an exact state-backed temporary role\neven though it is absent from merged fleet YAML. The recorded transient unit/job\nis authoritative. Missing/incomplete ownership metadata is reconciled only from\nan exact `_run-temp <role>` process-table match: one match may be adopted, zero\nsettles as stopped, and ambiguity or an unreadable table fails closed. Launching\nrecords receive a bounded grace so a not-yet-registered transient unit cannot be\nmistaken for a stopped one. Stale recorded supervisors are reclaimed in bounded\nbatches by moving their state to the same recovery archive, never by blind deletion.\n\nEvery temporary role creates a new session-owned identity by calling ours MCP\n`create_temporary_identity` with its exact assigned name. It never binds a\npre-existing identity and never falls back to permanent `create_identity`.\nFleet does not inspect, preserve, or provision an ours identity for temporary\nspawn; creation belongs exclusively to the launched temporary agent session.\nCollisions, missing tool support, and creation errors stop safely without\nforce-adopting or deleting identity state. Permanent roles\nare provisioned by fleet before launch and never delegate normal identity\ncreation to the harness.\n\nThe temporary supervisor treats its first positive identity observation as the\nlifecycle readiness gate: a cold harness may take as long as needed to read its\nbriefing and bind, without a fixed first-bind retirement timer. After readiness,\nonly sustained authoritative absence closes the role. Unreachable, malformed, or\nvalid-but-empty daemon indexes are ambiguous and reset closure debounce rather\nthan becoming cleanup authority.\n\nInside a managed role, public `ours-fleet` commands cross an authenticated\nsupervisor attribution boundary before Commander parsing. The original CLI remains\nthe executor inside the role's existing OS sandbox, and ordinary CLI validation is\nthe source of truth. Hidden worker entry points remain internal; public lifecycle and\noperator commands are not restricted by the proxy.\n\nCommand invocation, raw argv, read-only work, validation failures, and generic\noutcomes are never forwarded to the Owner-visible channel. Fleet announces only\nconfirmed Agent, Task, and Room lifecycle changes. Local diagnostics retain\nstructurally redacted command metadata. Lifecycle delivery uncertainty is logged,\nnever recursively announced, and never reruns or blindly retries an effect.\nRoom participant summaries describe creation and activation. Fleet has no public\npost-create Room membership mutation, so it does not claim a separate membership event.\n\nOmitted Brain and Role selections, working directory, coordinator, neutral permissions,\nand fleet monitor policy inherit from the calling Agent. Explicit options always win.\nIdentity, mission/profile text, environment, owner routing, auth proxy, room startup,\nisolation, worklog, and sensitive inline Brain values never inherit implicitly.\nThis automatic proxy is a convenience and\nattribution mechanism, not an isolation boundary: an unrestricted role can still\ninvoke another binary path directly. Host/operator shells keep the ordinary direct\nCLI behavior.\n\nBrain owns harness, session, model, reasoning effort, token limits, and native harness\noptions. Removed runtime flags are rejected with migration guidance rather than silently\nreinterpreted. A selection is a stable ID or an explicit `inline:{...}` mapping.\n\nPackaged Developer, Critic, and LocalCoordinator Agent Templates set\n`monitor: { mode: fleet, interrupt: after_tool }`. Every member of the standard\n`single`, `pair`, and `team` Room Templates therefore resolves to fleet-owned,\nafter-tool delivery. Explicit per-member and custom Agent Template values remain\nauthoritative and merge key by key.\n\n## fleet.yaml\n\n```yaml\napi_version: ours.network/fleet/v2\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nwatchdogs:\n  nightwatch:                       # [A-Za-z0-9_-], must not collide with a role name\n    coordinator: FleetCoordinator   # required \u2014 where alerts go\n    # everything below is optional\n    enabled: true                   # default true; false = configured but never scheduled\n    interval: 10m                   # default 10m; 30s | 10m | 2h, minimum 1m\n    watch: [Alice, CodexReviewer]   # explicit lists are exact; omit for configured + live temp roles\n    agent: { ref: WatchdogAgent }   # required: declared Agent ID, or canonical inline Agent definition\n    identity: Watchdog-nightwatch   # default: Watchdog-<name>\n    timeout: 5m                     # default 5m; a run past this is killed and recorded as error\n    keep_reports: 50                # default 50 reports retained per watchdog\n    alert_cooldown: 60m             # default 60m before the same finding alerts again\n    prompt_file: /abs/extra.md      # optional extra focus, APPENDED to the fixed contract\n```\n\nAn Agent is a separate bare document under `~/fleet/agents/<ID>.yaml`:\n\n```yaml\nrole: { inline: { mission: Coordinate work and delegate implementation. } }\nbrain: { inline: { harness: codex, session: codex-app-server, model: gpt-model-id } }\nidentity: Coordinator\ncwd: ${work_root}/project\noversee: [{ agent: Worker, interval: 5m }]\n```\n\nA watchdog observes and reports; it never restarts, stops, spawns, or removes a\nrole, answers a pending permission, edits a workspace, or approves anything on\nthe owner's behalf. `watchdogs:` may appear only in the base config\n(`~/fleet.yaml` or `-c FILE`); Agent/Role/Brain documents never own it.\nThe selected Agent owns Brain, Role, permissions, isolation, and every other\nagent setting. Legacy watchdog `harness`, `model`, `session`, and\n`isolation` fields fail with migration guidance.\nWhen `watch:` is omitted, each run watches the configured roles plus temporary\nfleet roles that are live when the run starts. An explicit `watch:` list is\nnever augmented.\n\nAgent operational values override manifest operational defaults. Role and Brain\nownership never cross-merges. `${name}` substitutes entries from `vars`.\nBrain fields include `max_tokens` and `autocompact_pct`; isolation is Agent-owned.\nUse README.md for the complete isolation policy and resource-cap schema.\n\nSupervised roles connect to the operator-configured ours daemon; they do not own its\nlifecycle. Fleet strips the obsolete, presence-sensitive `OURS_AUTOSTART` variable from\nagent-session children; `ours-mcp proxy` is client-only and never starts a daemon. Start\nthe shared daemon only through an explicit operator or installer/setup flow.\n\n## Rooms and tasks\n\n`init` materializes editable `single`, `pair`, and `team` Room templates plus\ntheir exact-cased Agent, Role, and Brain presets. The command prints the packaged\npreset revision and source directory. Inspect provenance and content before use:\n\n```sh\nours-fleet config [-c FILE]\nours-fleet template list [-c FILE]\nours-fleet template show team [-c FILE]\nours-fleet task create --title \"Solo task\" --template single [-c FILE]\nours-fleet task create --title \"Reviewed change\" --template pair [-c FILE]\nours-fleet task create --title \"Phased delivery\" --template team [-c FILE]\nours-fleet spawn --temp Scout --role SELECTION --brain SELECTION --loops-file PRIVATE.yaml\nours-fleet task start TASK --member developer --loops-file PRIVATE.yaml\nours-fleet task start TASK --member critic --no-loops\n```\n\n`--loops-file` must be an owner-only, non-symlink regular file <=1 MB containing\nexactly one top-level non-empty `loops:` mapping. `--no-loops` explicitly\ndisables loops. They are mutually exclusive and rejected for permanent spawn.\nFor a grouped room member the whole CLI block overrides its Agent Template;\nthe template overrides omission. Omission preserves historical no-loop behavior\nand never inherits manifest wildcard loops. Fleet validates before side effects,\nseals normalized timings plus exact private prompts, and reuses that snapshot for\nidempotent start, retry, recovery, and replacement. Trusted authoring and the\nprivate sealed runtime retain exact prompts; resolved launch, task, room,\nprovenance, and audit presentations show source, policy, timing, prompt bytes,\nand prompt SHA-256 instead of prompt text.\n\nAn alternate manifest `-c /path/custom.yaml` uses `/path/custom/` as its split\nroot. Repeated init only fills missing files and never adopts a newer default.\nExact known revision-3 through revision-5 packaged-bootstrap and generated role defaults have an exact-semantic,\nfail-closed migration (dry-run by default):\n\n`ours-fleet migrate-role-defaults [-c FILE]`\n`ours-fleet migrate-role-defaults [-c FILE] --write`\n\nReview removals, replacements, additions, preserved custom files, staging path,\nand recovery path. Same-named custom files stay byte-identical; dangling custom\nreferences refuse publication, and a successful rerun is a no-op. For explicit\nsingle-file adoption, copy from init's reported packaged source beside the target\nas `.new-default`, inspect `diff -u TARGET TARGET.new-default`, then replace it.\n\nThe exact generated six-worker legacy starter Agent set has its own fail-closed\nmigration (dry-run by default):\n\n`ours-fleet migrate-agent-templates [-c FILE]`\n`ours-fleet migrate-agent-templates [-c FILE] --write`\n\nReview the dry-run moves, addition, staging path, and retained recovery-backup path\nbefore `--write`. Customized/partial known starters and unsafe trees refuse without\nmutation; unrelated custom persistent Agents remain persistent. A manifest-level template\nmay shadow a same-named file only with `override_builtin: true` and a higher\nversion; this compatibility marker is deprecated and reported as a diagnostic.\n\nRooms always use `ours-cowork`; there is no room-provider selector. Configure\nthe cowork daemon connection and room owner directly:\n\n```yaml\nrooms:\n  cowork:\n    config: /home/me/.ours-cowork/config.json\n  owner:\n    expected_cid: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n    public_invite_file: /home/me/.ours-fleet/owner-room-invite.txt\n  defaults:\n    template: team\n    attach_owner: true\n    close_when_task_done: true\ntasks:\n  default_room_template: team\n  create_mode: start\n  close_room_on_done: true\n```\n\nFleet launches each template member with a dedicated one-time Cowork invite.\nThe generated temporary-agent briefing contains the exact identity name, invite,\nCowork role, and task. The agent creates that identity itself with ours MCP\n`create_temporary_identity`, accepts the invite with `add_contact`, and starts\nwork immediately. A room is ready only after the Cowork room (and its task, when\ntask-bound) is durably active, every configured member seat is authenticated and active with its matching\nlive Fleet launch, and the configured Owner seat is active when owner attachment is\nenabled. There is no briefing hash, startup ACK, or separate role-briefing readiness\ngate.\n\nNormal Task provisioning emits exactly one authenticated Owner lifecycle notice after\nthe ready predicate above is true; standalone Room provisioning likewise emits one\nready notice. Intermediate task, saga, member-spawn, timeout, and recoverable-failure\ntransitions stay in local state and logs. A terminal failed Task emits one actionable\nfailure notice; the command result carries the exact blocker and canonical recovery\naction.\n\n`task start` and create-and-start wait for readiness. If their bounded wait expires,\nthey return an explicit `in_progress` result and start a safe continuation. The detached\ncontinuation is serialized per Task and remains alive until convergence or an\nOwner-action blocker. Re-running `task start <id>` safely resumes the same durable\nprovisioning operation after the blocker is corrected or a process restarts.\n\nSet `room.anonymous: true` on a room template, or pass `--anonymous` to\n`task create`, `task start`, `task work`, or `room create`, to create an\nanonymous Cowork room. `--no-anonymous` explicitly overrides an anonymous\ntemplate. Fleet records the resolved value before room creation so retries keep\nthe same choice. Temporary members of an anonymous room are instructed to call\n`create_temporary_identity` with `expose_local=false`. Their generated briefings\ndo not disclose or compare an Owner participant CID. A participant-originated\ninstruction has Owner authority only when the authenticated Cowork room envelope\nattributes that participant seat the exact `Owner` role. Literal text, display\nnames, ordinary direct messages, and room-authored or rest-role messages with an\nOwner-looking label never grant that authority. Non-anonymous rooms remain pinned\nto the exact authenticated Owner CID.\n\nHuman task and room results use the same compact Markdown presentation in the\nCLI and authenticated owner channel: a short heading, icon-plus-word status,\ncode-formatted identifiers, bounded summaries, and actionable recovery or error\nsteps. Untrusted prose is context-escaped and control characters are neutralized;\nMessenger-bound results are capped at 3,500 Unicode code points and 12,000 UTF-8\nbytes with structural omission notices. `--json` bypasses this presentation layer\nand retains the versioned machine schema and serialization order.\n\nEvery task belongs to a named list. The built-in `default` list always exists,\nand legacy tasks or create calls without `--list` resolve to it. Use `task lists`,\n`task list-create <name>`, `task list-rename <name> <new-name>`, and\n`task list-delete <name> [--move-to <destination>]` to manage lists. A non-empty\nlist cannot be deleted without an explicit, different destination; Fleet moves\nthe assignments and never deletes the tasks. `task move <id> --list <name>`\nchanges only organizational metadata. `task list --list <name>` filters and\n`--group-by-list --json` returns deterministic groups.\n\nList names are NFC-normalized, case-sensitive, and limited to 64 Unicode code\npoints. Leading/trailing whitespace, controls, format/path characters, normalized\nduplicates, and the reserved exact name `default` are rejected. The authenticated\nowner channel provides the matching `/task` subcommands, while authenticated web\nclients use `/api/v1/task-lists`, `/api/v1/tasks`, and\n`/api/v1/tasks/:id/list`; every adapter delegates to the same application service.\nMessenger's multiline command grammar treats surrounding whitespace on each\nvalue line as transport framing; the canonical value passed to the shared service\nis the trimmed line. CLI arguments and REST strings are passed verbatim.\n\nOlder prerelease files with the exact legacy `provider: cowork` key under\n`rooms:` still load, but the key is ignored and omitted from resolved\nconfiguration. Remove it when editing the file. Any other legacy value is an\nerror. The optional `rooms.owner.provider` setting is separate and defaults to\n`messenger-server`.\n\nFinish and Delete are distinct terminal task actions:\n\n`ours-fleet task finish <id>` moves an active or review task to `done` and\ndeletes its associated Cowork room after retiring its members. The room then\ndisappears from normal Fleet and Cowork views; its brief, messages, repository\nreferences, and attachments are not retained as an inspectable archive.\nThe prerelease configuration names `tasks.close_room_on_done` and\n`rooms.defaults.close_when_task_done` are retained for compatibility, but\n`true` now means this close-then-delete behavior.\n\n`ours-fleet room delete <id> <id>` is the canonical destructive room command.\n`room close <id> <id>` remains a deprecated alias with identical deletion\nsemantics. Older prerelease `closed` room records are deleted directly the next\ntime `room list` reconciles Fleet with Cowork.\n\n`ours-fleet task delete <id> <id>` permanently deletes a task in ANY lifecycle\nstate \u2014 backlog, provisioning, active, blocked, review, done, cancelled, failed,\nor partially settled. The exact task ID is required twice for confirmation. A\ndurable deletion intent is persisted before any side effect; the cleanup worker\nthen retires managed room members with evidence, closes and deletes an attached\nroom (tolerating already-missing remote rooms), releases the sealed launch\nsnapshot, and unlinks the task record last. While cleanup settles the task is\nhidden from normal listings and every lifecycle mutation is rejected; if\ncleanup cannot complete (for example Cowork is unreachable), the deletion stays\nin a precise resumable state \u2014 repeat the identical delete command to converge\nafter outages, crashes, or restarts. Deletion\nnever fabricates a `done` transition. A metadata-only deletion receipt\n(acceptance actor, original state, timestamps, completion) is retained under\n`deletion-receipts/` as durable audit evidence. An already-missing task is an\nidempotent no-op. The Owner-channel equivalent is `/task delete <id> <id>`; the\nmanagement API equivalent is `DELETE /api/v1/tasks/<id>?confirm=<id>` (200 when\nsettled, 202 while pending; `GET /api/v1/tasks?includeDeleting=true` exposes\ndeletion-pending tasks to operators).\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|auto|allow`: portable permission policy. `deny` remains a\n  deprecated, fail-closed compatibility alias for existing fleet files.\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what a managed session does when no console can\n  answer a request\n\nThe backend translates this common intent. Native Codex app-server roles reject\npermission aliases in `harness_options`; Codex ACP and Claude retain their\nlegacy native-override compatibility. Do not choose `allow`/`unrestricted`\nor Claude `bypassPermissions` without explicit authorization.\n\n### Creation-time isolation\n\n`ours-fleet spawn --isolation-file <path>` supplies a role's sandbox policy at\ncreation, so the FIRST launch is already confined \u2014 a role that only gains\n`isolation:` on a later `up` ran unsandboxed until then.\n\nThe file holds exactly the `isolation:` mapping documented above and nothing\nelse \u2014 the same schema, validated by the same code, so a policy written here\ncannot mean something different from the identical block in fleet.yaml:\n\n```yaml\nnetwork: deny\nfs:\n  read: [/opt/reference]\nresources:\n  mem: 2G\n```\n\nInvalid files are rejected before anything is created: no config, no state\ndirectory, no identity reservation. Works for both permanent and `--temp` roles.\n\n### Never-prompt failure\n\nThe failure this section exists to prevent leaves no error message anywhere.\n\nAn unattended role has no console. When the harness needs a permission decision\nthere is nobody to ask, so the request is refused INSIDE the harness \u2014 no\nprompt, no error, no log line. The agent simply does less than its briefing told\nit to, reports success, and nothing distinguishes that from having done the\nwork. Two settings produce it:\n\n1. a permission mode that suppresses the prompt without granting the action\n   (Claude `dontAsk`, which is why neutral `allow` maps to\n   `bypassPermissions` instead); and\n2. `unattended: deny`, which refuses every request that reaches it.\n\n**Automatic decisions are now recorded.** Every permission request decided\nwithout a human emits a completed event into\n`~/.ours-fleet/agents/<Name>/.session-events.jsonl` carrying the decision,\nwhether policy or a person made it, the policy that produced it\n(`permissions.unattended=deny` vs `permissions.approval=deny`/`=allow`),\nthe reason, and the option selected. `ours-fleet peek` and `attach` render\nthem. Automatic denial asks for a one-shot rejection, never a standing one, so a\nsingle unattended refusal cannot disable a tool for the rest of the session.\n\nA role that can auto-deny logs one line at startup saying so.\n\nTo detect an under-permissioned role BEFORE it runs, use the capability floor\nbelow: `ours-fleet doctor` fails such a role rather than letting it discover\nthe problem silently at work.\n\n### The unattended capability floor\n\nAn unattended role has no console, so a permission request cannot be answered \u2014\nit is refused, silently, inside the harness. The agent then does less than it\nwas told to and reports no error. To make that visible before launch,\n`ours-fleet config` and `ours-fleet doctor` resolve each role's neutral\npermissions through its harness and check the result against a fixed floor:\n\n- `read-state` \u2014 read its briefing, ROUTINES.md, and WORKLOG.md\n- `write-state` \u2014 append its WORKLOG and its own state files\n- `messaging` \u2014 bind its identity, send and receive ours mail\n- `monitor` \u2014 arm and observe its mail monitor\n- `workspace-edit` \u2014 edit and test files in its working directory\n- `status-commands` \u2014 run the inspection commands its briefing prescribes\n\n`doctor` reports this per role as `unattended floor: <Role>`. A role with\n`unattended: deny` that cannot meet the floor FAILS doctor, because it will\ndeny those requests with nobody to see it; with `unattended: wait` it warns,\nbecause a human can still attach and answer.\n\nSecurity meaning: native Codex maps `ask` \u2192 `untrusted`, `auto` \u2192\n`on-request`, and `allow` \u2192 `never`; its independent filesystem mapping is\n`read-only` \u2192 `read-only`, `workspace` \u2192 `workspace-write`, and\n`unrestricted` \u2192 `danger-full-access`. Users configure only the Fleet names.\nClaude maps `ask` to `default`, `auto` to `acceptEdits`, and `allow` to\n`bypassPermissions`. Codex ACP retains its adapter-specific coupled modes:\n`auto` selects `agent`, while `allow` selects `agent-full-access`. These\nmodes genuinely permit the actions the role was authorized to take \u2014\n`dontAsk` only suppresses the prompt while still refusing the action. Nothing\nother than an explicit `allow` becomes non-interactive. Legacy `deny` keeps\nits conservative Codex `on-request` / Claude `plan` translation. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\n\nACP carries agent-advertised session mode IDs and `session/set_mode`, but those\nIDs are agent-specific and ACP defines no portable permission-policy capability.\nFleet therefore uses the ACP primitive where an adapter exposes a matching mode\nand otherwise performs the harness translation above. The bundled Codex ACP\nadapter couples approval and sandboxing in its advertised mode IDs. Neutral\n`allow` therefore selects `agent-full-access` and widens `filesystem:\nworkspace` or `read-only` to `danger-full-access`; neutral `auto` selects\n`agent` and `workspace-write` even when the neutral filesystem value differs.\nAn explicit `harness_options.sandbox` selects its corresponding ACP preset and\nstill wins, as does an explicit native approval override. `config` and\n`doctor` report a coupled-mode mismatch as approximate. Use per-role\n`isolation:` as the outer boundary for an `allow` ACP role. The live session\nreports both its effective normalized mode and the exact native mode selected.\n\nSee also: `spawn --approval/--filesystem/--unattended` set this intent at\ncreation, and `ours-fleet config` prints each role's neutral settings, their\nnative translation, and any warning \u2014 the same text `doctor` reports.\n\nClaude `harness_options`: `permission_mode` (default, acceptEdits, plan,\ndontAsk, bypassPermissions), `plugins`, `mem_palace`,\n`mem_palace_midsession_autosave`, `mcp_servers` and `mcp_servers_only`.\n\n`mcp_servers` declares MCP servers for the role, in `.mcp.json`'s own shape\n(a map of name to `{ command, args, env }`, or `{ type: http|sse, url,\nheaders }`). By default they are ADDED to whatever the OS user running the role\nalready has configured. The Claude Code adapter sends them in `session/new`.\n\nWhen `mcp_servers` is absent, Fleet sends ACP's protocol-required empty\n`mcpServers` array without an exclusive override, so the agent keeps its inherited\nservers. An explicitly empty configured set is different: Fleet preserves that intent\nthrough the bundled adapter's compatibility path and disables every inherited server.\n\n`mcp_servers_only: true` makes the declared set EXCLUSIVE through\n`strictMcpConfig`. It is all-or-nothing and it ignores every\nother MCP configuration: project `.mcp.json`, user settings, and **plugins**.\nThe ours connector is normally installed as a plugin, so a strict role that does\nnot re-declare it has no `send_message` and no `get_messages` \u2014 it cannot even\nreport that it has gone mute. Fleet therefore refuses a strict role whose\n`mcp_servers` does not name the connector; declare it explicitly, e.g.\n`ours: { command: ours-mcp, args: [proxy] }`.\n\nBoth options, and `plugins`, reach an ACP session through the bundled Claude ACP\nagent's `_meta` vocabulary. A role that sets `session_options.acp.command` runs\nan agent fleet did not choose and cannot be promised them, so that combination is\nrefused at validation rather than accepted and dropped. This narrows a role's\ntool surface; it does not stop the harness deferring tool schemas, which is the\nharness's own decision.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `search`,\n`config`, `add_dirs`, and `monitor`; Codex ACP additionally supports\n`profile`. Native app-server roles reject `profile` because Codex does not\naccept `--profile` for `app-server`. They\nmust express approval and filesystem authority through the shared\n`permissions:` block, never through harness options. The adapter translates\n`ask|auto|allow` to Codex `untrusted|on-request|never` and translates\n`read-only|workspace|unrestricted` to Codex\n`read-only|workspace-write|danger-full-access`. Native `config` currently\nallows only `model_reasoning_effort`; ACP retains the broader Codex config surface.\n\nFor Codex, the opt-in `session: codex-app-server` directly runs Codex's native\nJSONL app server behind Fleet's provider-neutral session contract. It supports native item\nstreaming, commentary/final phases, prompt admission, steering, interruption,\npermission requests, durable conversation projection, and thread resume. Packaged\nCodex brains and the init wizard continue to select `session: acp` for compatibility;\nClaude Code also uses ACP. Native Codex defaults to `codex app-server` (or `ours-codex app-server`\nwhen launcher auto finds it). Override the exact command when necessary:\n\n`session_options: { codex_app_server: { command: [codex, app-server] } }`\n\nAn exact command override receives no appended profile, search, or subcommand\narguments. Native sessions persist their Codex thread in Fleet's `.session-id`\nand participate in its bounded fresh/resume recovery; cross-provider conversation\nportability is never assumed.\n\n## ACP adapters\n\nThe maintained `@agentclientprotocol/codex-acp` and\n`@agentclientprotocol/claude-agent-acp` runtimes are bundled automatically as\noptional ours-fleet dependencies. The supervisor resolves their executable\nentrypoints internally, so default ACP roles do not depend on global PATH.\nours-fleet and both maintained adapters require Node 22 or newer.\n\nOverride an adapter only when necessary with `session_options.acp.command`\n(string or argv list). If optional dependencies were deliberately omitted,\nours-fleet falls back to a compatible globally installed `codex-acp` or\n`claude-agent-acp`. `ours-fleet doctor -c FILE` verifies the resolved adapter.\n\n## Reliable mail wake\n\n`monitor.mode` selects exactly one wake owner:\n\n- `fleet` (default): the ours-fleet supervisor consumes body-free daemon\n  events and advances its durable cursor only after delivery is accepted. ACP\n  uses live steering when supported and falls back to structured\n  `session/prompt`.\n- `native`: ours-fleet starts no supervisor monitor; the generated briefing\n  instructs Claude Code or Codex to arm its harness-native wake mechanism.\n\nSet `monitor.interrupt: true` in fleet mode to cancel active work before every\nconfigured wake. Set it to `after_tool` to preserve an active ACP tool (and any\npending permission), then steer the wake at the first tool-terminal boundary\nwithout cancellation. A hung boundary is bounded at 120 seconds and falls back\nto non-cancelling steering/queueing; adapters without authenticated tool events\nuse the same conservative fallback. Explicit human/control interrupts remain\nimmediate. The policy is content-blind because the supervisor cannot inspect\nencrypted message bodies. Message bodies are released only when the role calls\nthe ours `get_messages` tool.\n\nThe default is `false`. For a temporary role whose mission intentionally arrives\nafter its readiness announcement, set `mode: fleet` and `interrupt: true`\nexplicitly. The readiness announcement does not change the transport: the\nmission remains ordinary ours mail, fleet injects only the body-free wake, and\nthe role calls `get_messages` before acting. Every later configured wake uses\nthe same interruption policy.\n\nLegacy `monitor.enabled: true|false` remains accepted as an alias for\n`mode: fleet|native`; use `mode` in new configuration. Codex's separate\n`harness_options.monitor: true` is native-monitor consent, not monitor-owner\nselection.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\n\n## Trusted owner channel\n\nAny managed role may declare a separate ours identity which fleet \u2014 never the agent \u2014\ncreates when missing and binds:\n\n```yaml\nowner_channel:\n  identity: Coordinator Owner Channel\n  owners: [authenticated-owner-contact-cid]\n  agent: authenticated-managed-agent-cid\n  interrupt: false\n  progress_interval_ms: 30000\n  comments: true\n  attachments:\n    enabled: true\n    max_files_per_request: 4\n    max_file_bytes: 10485760\n    max_request_bytes: 20971520\n    retention_ms: 86400000\n```\n\nPermanent role identities are also reconciled before launch. Fleet creates a\nmissing role identity with local exposure and local auto-accept enabled. A\nmissing owner-channel identity uses the safer inverse policy: both are disabled.\nThe short provisioning lease is released before the agent or channel binds.\nTemporary role identities remain connector-owned because their creating lease\ndefines their cleanup lifetime.\n\nThis does not replace the role identity. Normal identity mail remains untrusted\npeer input: the agent reads it through `get_messages` and replies through\n`send_message`. Mail arriving on the dedicated channel from a CID in `owners`\nis injected as a direct `[fleet-owner]` prompt. Mail from the exact `agent`\nCID is forwarded as a new message to the latest authenticated owner conversation;\nits files may also be relayed through this channel. A reply reference selects the\nowner of that authenticated source wire instead of the latest conversation.\nEvery other CID is rejected and warned about without reflecting its body. Fleet sends\naccepted/queued/progress/interrupted/failure notices and routes the ACP turn's\nfinal assistant text back to the authenticated sender with its source wire ID.\nFor file replies of every kind \u2014 a response artifact, a proactive note, or an\nin-turn attachment \u2014 the agent calls ours `send_file` to the channel identity\nand may pair it with a reply-linked caption; fleet, not the agent, chooses the\nowner. That is the only delivery route an agent is given: a tool call either\ndelivers or reports an error, where a file written to disk does neither.\nOwner messages whose trimmed text starts with `/` are deterministic\nsupervisor commands and never enter the model: `/help` (alias `/commands`),\n`/status`, `/comments [status|on|off]`, `/interrupt`, `/clear`,\n`/compact`, `/model <model-id>`, `/restart`, `/force-restart`, `/ls`,\n`/peek`, `/worklog`, and\n`/version`. Unknown or malformed commands answer with the help text instead of\nbeing forwarded; plain messages reach the agent unchanged. `/clear`,\n`/compact`, and `/model` are forwarded only when the role's bundled ACP\nadapter executes them locally (claude-code: all three; codex: `/compact`\nonly) and are otherwise refused with a notice, so slash text never reaches the\nmodel as a prompt.\n\nThe supervisor advertises the same primary registry entries as recipient-scoped\nours typed commands. Their single arguments field is converted back to the text\nafter the slash command name and enters the same dispatcher; aliases stay\nslash-only. Typed handlers repeat the live authenticated Owner-CID check before\ndispatch and return a null protocol completion because the existing correlated\nowner-channel reply remains the result.\n\nWhile a request runs, the agent's live ACP commentary is relayed as messages\nprefixed with the single stable label `\uD83D\uDFE1 Live update:`, so an owner can see\nexactly which messages the setting controls. `owner_channel.comments`\n(default `true`, so existing channels keep their current behavior) is the\nRESTART BASELINE; `/comments on|off` changes only the running session and is\ndeliberately not persisted, so a restart always returns to the checked-in\nconfiguration. `/comments status` reports the live value, the baseline, and\nwhether the backend emits live comments at all. Suppressing live comments never\nsuppresses receipts, progress notices, or the final answer.\n\nOwner documents, images, and voice messages use the same authenticated sender\nand source-wire boundary. Fleet inspects body-free metadata first and rejects\ndisabled, over-count, or over-size requests before selective\nretrieval. Unauthorized CIDs are never retrieved or answered. Reply-linked text\nand files from the same sender become one ordered request; a file-only wake also\nstarts a turn. Retrieved bytes must match their structured size and SHA-256,\nwhile MIME values, extensions, file categories, and declared-versus-detected mismatches\nremain report-only metadata. Symlinks or non-regular paths fail closed. Sanitized copies live only in a mode-0700 request directory as\nmode-0600 files and are removed after completion or bounded stale retention.\n\nThe legacy `attachments.allowed_mime` key is accepted and ignored so existing\nconfigurations keep loading; it is omitted from resolved configuration and cannot\naffect admission.\n\nVoice prompts include a bounded transcript only when typed daemon metadata reports success.\nFailure or unavailability is explicit and preserves the private audio path as the\ninput for direct review. Run `ours config show --json` and inspect `sttConfigured` without\nrevealing provider credentials.\nA mode-0600 message claim journal stores only wire ID, persistent-history\nsequence, and claim time. Fleet journals the exact body-free oldest-first slice\nbefore calling `getMessages` with that slice length, rejects a returned set\nmismatch, and loads a crash-recovered body only through `getHistoryItem`.\nThe attachment crash journal contains only authenticated CID and wire routing\ndata; it never stores captions, filenames, paths, transcript text, or bytes.\nJournaled read files resume through `getFileInfo` and `fetchFile`. A claimed\nagent caption is loaded from history and rejoined before the group is admitted. Fleet\nresolves one authenticated owner route before retrieving bytes, admits every file\nbefore emitting the caption or any file, and sends every part to that same route.\nUnknown correlated routes remain queued without retrieval and receive one bounded\ncorrelated notice. Admission rejection consumes the whole group with one NACK;\nonce emission starts, a transport error becomes terminal uncertain delivery and\nthe group is never blind-retried. Bounded v2 source-wire routing state is migrated\nfrom v1 on read. Corrupt state disables attachment admission rather than weakening\nprovenance checks.\n\nThe channel identity must be unique and must not be a role identity. The bridge\npersists bounded wire IDs only, never message/reply plaintext, and requeues input\nbefore starting its turn for at-least-once crash recovery. It currently requires\nthe structured agent-session interface so correlated final replies retain their\ndelivery guarantee.\n\n### Live contact and owner administration\n\nThe supervisor which is already running the managed role remains the sole binder of\n`owner_channel.identity`. The CLI reaches that exact live `OwnerChannel`\nthrough the role's token-authenticated, mode-0600 Unix control socket for contact\ninspection and setup; it never starts another ours client and never force-binds:\n\nRapid supervised restart is serialized by a role-scoped single-binder lease.\nThe predecessor closes its authenticated control socket and MCP proxy before\nreleasing ownership. The replacement waits at most five seconds and retries the\ndaemon bind only when PID/start-marker metadata proves the holder was the same\nrole and owner-channel identity. Foreign, live, corrupt, or otherwise\nunverifiable ownership remains fail-closed; fleet never uses `force=true`.\n\nIf that matching predecessor misses the bound, its still-authenticated control\nroute may send one fixed, digest-deduplicated recovery notice through the latest\nauthenticated owner conversation (or the sole configured owner). Notice\nplaintext is never persisted. With no safe deterministic route fleet guesses no\nrecipient and leaves the actionable failure in the web console and role logs.\nThe remote recovery action is `/restart`; inspect repeated failures with\n`ours-fleet logs <Role>` or the web console.\n\n```sh\nours-fleet owner-channel contact list <Role>\nours-fleet owner-channel contact invite <Role> [--name <label>]\nours-fleet owner-channel contact add <Role> (--invite-file <path> | --invite-stdin) [--name <label>]\nours-fleet owner-channel owner list <Role>\nours-fleet owner-channel owner authorize <Role> <exact-64-hex-contact-cid>\nours-fleet owner-channel owner revoke <Role> <exact-64-hex-contact-cid>\n```\n\nContact establishment and owner authorization are separate security steps.\n`contact add` never authorizes: invite redemption is pending until the peer\nverifies it. Once `contact list` reports the established contact, authorize\nits exact immutable CID explicitly. Invite creation emits invite material only\non stdout; acceptance reads it from a file or stdin, not argv.\n\nConfigured `owners` remain the baseline. On legacy channels without `agent`,\nlive authorizations/revocations are an immediately effective, restart-persistent\noverlay. Managed-agent CID gating makes fleet configuration authoritative and\ndisables live owner mutation and direct control-socket sends. `owner list` labels\nbaseline versus dynamic entries and effective status. The atomic mode-0600 file\ncontains bounded CIDs and audit actions only. Corruption disables all effective\nowners and refuses mutation rather than resurrecting authority; revoking the\nlast effective owner is always refused.\n\nA missing/stopped role, role without `owner_channel`, unavailable\nMCP client, or a role entering shutdown returns an actionable error with no\nside effects. Management uses no network listener and never logs or persists\ninvite material.\n\nFor any non-final message\u2014progress, blocker, suggestion, or later proactive note\u2014\nthe managed agent calls ordinary ours `send_message` to the channel identity.\nFleet checks only that the authenticated sender CID exactly equals `agent`, then\nforwards the text as a new message. There is no task/request/update type, phase,\nreply correlation, or owner recipient argument. A sole owner is the safe fallback;\nwith multiple owners and no inbound route history the relay fails closed. Devices\nsharing one identity share its CID; separate owner identities hand off the route\nwhen either sends channel mail. The ACP final is separate: fleet extracts it from\nthe completed turn and deterministically replies to the initiating owner wire.\n\nThe bounded mode-0600 route state stores CIDs, wire IDs, timestamps, delivery state,\nand hashes but never message plaintext. Unauthorized attempts produce a bounded\nCID-only owner warning; attempted bodies are neither reflected nor persisted.\n\nFor a mobile owner, establish the contact first, wait for peer verification,\nauthorize its exact CID, and revoke that same CID when access ends. The bounded\nmode-0600 CID overlay survives supervisor restart and remains fail-closed on\ncorruption. Update bodies remain memory-only. After a crash/restart, unfinished\ndeferred owner input follows the existing at-least-once replay path; the restarted\nsupervisor remains the sole binder.\n\n## Stable config and YAML migration\n\n`ours-fleet config --json` emits schemaVersion 1 resolved plans. Environment\nvalues and mission/persona/bio bodies are withheld; environment keys are sorted\nand values are marked redacted. Additive fields may appear in schema 1, while a\nremoval or semantic reuse requires a new schema version.\n\nYAML parsing always rejects duplicate keys. The current default\n`--yaml-mode compat` warns with file/line/column for anchors, aliases, explicit\ntags, non-scalar keys, and multiple documents. Use `--yaml-mode strict` in CI\nnow; strict becomes the next-major default and compat is the temporary migration\nescape hatch.\n\n## Bounded worklogs, auth proxy, and model recovery\n\nWORKLOG rotation is enabled by default with\n`worklog: { max_kb: 1024, keep_tail_kb: 256, max_archives: 12 }`. Maps may\noverride individual values; `worklog: false` on a role or in defaults opts out.\nFleet rotates only at that role's launch/resume lifecycle boundary. Concurrent\nchanges defer rotation. The active file keeps a bounded UTF-8 tail and advances\nto a line boundary when a complete line fits. If one logical line alone exceeds\nthe budget, its newest suffix remains and the rotation manifest records the\nmid-line start and omitted byte count. The complete prior inode receives a\ncollision-safe UTC archive name, and\n`.worklog-rotation.json` records restart provenance. `max_archives` bounds\nrecent archives beside WORKLOG.md; older complete archives move to\n`WORKLOG.archives/` without deletion. All archives share the role's sensitive\nstate boundary. Fleet refuses a symlinked/non-regular live log or a symlinked\ncold-archive boundary before replacing the live path and best-effort removes a\nduplicate publication left by a detected failure while the original inode is\nstill available. The manifest records SHA-256 digests for the archive and live\nbytes observed when it is written. These checks address ordinary path hazards,\nnot intentional path mutation by a malicious concurrent process with the same\nUnix authority; that is outside the threat model and requires OS-level isolation.\n\nACP tool diffs are bounded before entering web conversation events. Existing\nsmall before/after diffs are unchanged. Oversized whole-file snapshots are\nreduced to the actual changed region plus path, operation, original byte counts,\ndigest, and omission metadata. Each retained side is a newest-content UTF-8 tail\nof at most 64 KiB, advanced to a line boundary when a complete line fits. An\noverlong single line keeps its newest suffix and explicitly records a mid-line\nstart. Paths retain at most a 4 KiB suffix with byte count, digest, and omitted\nprefix metadata; the complete normalized update is capped at 320 KiB. A large\nappend therefore retains current appended content, not the historical prefix.\nThe live web-console transcript includes only the current runner generation and\nexcludes adapter session/load replay. Replayed events remain durable with\nagent_replay provenance for diagnosis and recovery.\n\n`auth_proxy: { kind: anthropic, base_url, required, health_url }` is Claude-only\nand loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects\ncredential env keys. The privileged reference companion is\n`contrib/anthropic-auth-proxy.mjs`; deploy it separately as a dedicated account\nwith a 0600 token file and per-role listener access. Fleet never installs it or\nreads its credential.\n\n`model_chain` is an ordered authorization list and its first entry must equal\n`model`. Only sustained high-confidence entitlement/quota 429 evidence advances\none entry. Transient 429, overload, auth, policy, and unknown errors never\ndown-shift. Runtime state is atomic in .model-recovery.json; exhaustion is\nfail-closed and held down. Change the declared chain/model and restart to\nreconcile explicitly; no chain preserves detection-only behavior.\n";
+export declare const AI_DOCS = "# ours-fleet reference\n\nours-fleet runs persistent or temporary, identity-bound AI roles through a\nprovider-neutral managed-session interface:\n\n- harness: `claude-code` or `codex`\n- session: `acp` (default) or `codex-app-server` (Codex only)\n- lifetime: permanent (supervised, restartable) or `spawn --temp`\n\n## Discover and validate\n\n```sh\nours-fleet docs                         # this complete reference (`man` is an alias)\nours-fleet help <command>               # exact flags for one command\nours-fleet config [-c FILE]             # validate and print the merged plan; no changes\nours-fleet doctor [-c FILE] [--harness codex|claude-code]\nours-fleet version [--json]             # build identity, capabilities, every install on PATH\n```\n\nConfiguration v2 is `~/fleet.yaml` plus typed bare documents under the exact\nstem directories `~/fleet/agents`, `~/fleet/agent_templates`, `~/fleet/roles`, `~/fleet/brains`, and\n`~/fleet/room_templates`.\nThe manifest owns fleet-wide operational defaults and automation; each Agent\nselects one inline/ref Role and Brain and carries its operational fields.\nAgent Templates under `~/fleet/agent_templates` are inert reusable launch definitions;\nonly explicit files under `~/fleet/agents` are persistent lifecycle instances.\nRoom members use `agent_template` and receive immutable content-addressed snapshots.\nAn Agent Template may declare up to 64 temporary-only named `loops`; persistent Agent\ninstances reject them. Each loop requires `interval` (1m..30d) and bounded\nnonblank `prompt`, with optional `enabled` (default true), `initial_delay`\n(default interval, 0s..30d), and `jitter` (default 0s, < interval, <=1h).\nExecution is fixed skip-if-busy with no ordinary missed-tick backlog/replay;\nrestart recovery may preserve at most one recent late occurrence.\nLegacy top-level `roles:` and `fleet.d` are rejected. Validate the complete\ntrusted source set with `config` and `doctor` before starting or restarting.\n\nPermanent `spawn` writes `~/fleet/agents/Name.yaml`. The web console edits an\nexplicit `{manifest, agents, agent_templates}` model while Role/Brain presets remain read-only.\nIts aggregate revision includes every Agent/Role/Brain/Room-template source, previews a\nredacted per-document diff in an exact-stem private staging tree, and saves under\none root lock with a private multi-file backup and full rollback. A no-op is\nbyte-identical and creates no backup.\n\n## Build identity and install provenance\n\n`--version` prints a semver and nothing else, and a semver does NOT identify an\nartifact. Version bumps land in a release commit of their own, so every build cut\nbetween two releases carries the PREVIOUS version while already containing new\nbehaviour. One host ran two installs that both reported 0.16.0 \u2014 same version,\ndifferent build. One accepted `monitor.interrupt: after_tool`, the other\nrejected it as invalid. Their\n`dist/cli.js` were byte-identical \u2014 the divergence was in other modules.\n\nEvery build therefore stamps `dist/build-info.json` with a build id (first 12 hex\nof a sha256 over the rest of `dist/`), the commit it was cut from, and the\ncapability tokens the shipped code declares \u2014 for example\n`monitor.interrupt.after_tool`. Ask any executable what it is:\n\n```sh\nours-fleet version                      # ours-fleet 0.17.0+9f1c2a3b4d5e, capabilities, PATH installs\nours-fleet version --json               # the same as machine-readable JSON, no environment values\n```\n\nRead a capability, never a version number, to decide whether a setting is\nsupported. When a build rejects a value it knows the name of, it says which\ncapability is missing and which build rejected it, because another install on the\nsame host may accept the identical file. `config` prints the build that resolved\nthe plan; `status <Name>` says so when the build reporting on a role is not the\none that created it (roles record their creating build in `creation.json`).\n\n`ours-fleet doctor` runs an `install` check that lists every `ours-fleet` on\nPATH plus the one executing, and FAILS when two installs share a semver but are\ndifferent builds, or when the running artifact is a DIFFERENT artifact from the\none PATH resolves to. A second prefix holding identical content is not a skew\nand is not reported. A PATH entry the shell would not execute \u2014 a directory, or\na file without its execute bit \u2014 is not counted as an install at all.\nInstalls built before this stamp existed report `+unknown`; they are compared by\nhashing their `dist/` instead, so two pre-provenance installs are still told\napart. To fix a flagged host, remove or update the stale install \u2014 do not rely on\nPATH order.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init [-c FILE]               # interactive missing-default seed; TTY required\nours-fleet up|down [Name...]\nours-fleet restart [Name...]            # preserve/resume harness context\nours-fleet force-restart [Name...]      # fresh context; briefing is reloaded\nours-fleet ls\nours-fleet status|peek|attach|logs Name\nours-fleet logs -f Name\nours-fleet send Name \"prompt\"\nours-fleet rm Name\nours-fleet watchdog-report <name> [run-id] [--list] [--json]\nours-fleet watchdog-run <name>\n```\n\n`init` is an interactive missing-default workflow that preserves existing files byte-for-byte.\nIt names the resolved manifest and split directory, asks a default-No confirmation,\nthen subscriptions (Codex, Claude, or both), model assignment (one explicit model for\nevery job or explicit development/review/coordination choices), one reasoning level,\nand a final default-No review. Quick/Balanced/Thorough generate low/medium/high.\nModel pickers show packaged supported IDs; catalog membership is not a recommendation\nor entitlement claim. Run `ours-fleet doctor` for local Codex availability; Claude\nentitlement is checked when a role launches. The generated brains contain no\n`model_chain`, so Fleet never silently substitutes another model.\n\nAt either confirmation, N, Enter, Escape, Ctrl-C, Ctrl-D, or EOF cancels. In a picker,\nEscape, Ctrl-C, Ctrl-D, or EOF cancels; Enter records the highlight or continues a\nnon-empty multi-select, N is ignored, and an empty subscription selection remains blocked.\nEvery cancellation before final approval performs no host or configuration mutation.\nRedirected/non-TTY invocation is refused with the same guarantee. After the final Yes,\nhost setup precedes publication. Path ownership/type/mode/symlink and\nsame-filesystem checks run before host setup and again under a per-setup lock. Publication\nstages and validates the complete combined setup, backs up whichever old target(s) exist,\nand retains a private recovery record. A hard process/host termination cannot promise\nrollback; inspect host integration and private init stage/recovery evidence.\n\n`peek`, `attach`, and text `send` use the structured agent session.\nAttachment also accepts `/permit <permission-id> <option-id>`, `/interrupt`,\nand `/detach`.\n\n## Local web console\n\nThe npm package includes the web console; installed users do not clone the repo\nor run `npm run build`:\n\n```sh\nnpm i -g @ours.network/fleet\nours-fleet init\nours-fleet doctor\nours-fleet web                         # install/update service, start, pair browser\n```\n\nThe normal command uses stable `http://127.0.0.1:49271/`, installs an\nowner-level systemd user service (Linux) or LaunchAgent (macOS), and opens a\nfive-minute one-use pairing link in the local browser. After pairing, bookmark\nthe plain URL or install the PWA. To pair a new, signed-out, or revoked browser,\nrun `ours-fleet web open`.\n\n```sh\nours-fleet web status\nours-fleet web start|stop|restart\nours-fleet web open\nours-fleet web revoke-all              # revoke every browser and active session\nours-fleet web uninstall\nours-fleet web serve --port 0 --no-open # isolated foreground/testing mode\n```\n\nThe console is IPv4-loopback-only by default. Both `localhost` and\n`127.0.0.1` are accepted locally. For an nginx/TLS reverse proxy, keep the\ndefault bind and declare the exact browser origin:\n\n`ours-fleet web install --public-origin https://fleet.example.com --password-file /secure/fleet-password`\n\nFleet reads the password file during setup and persists only a salted scrypt\nverifier. New browsers authenticate and retain rotating HttpOnly/SameSite\ntrusted-device credentials. If nginx already authenticates, the operator may\ndeliberately select `--no-password`; the CLI and browser warn that anyone\nreaching the origin can control the fleet. First setup requires an explicit\nchoice: `--password-file` or `--pairing` for protected access, or\n`--no-password` for intentional unprotected access.\n\nUse `--bind ADDRESS` only for an intentional direct listen. A non-loopback\nbind is rejected unless `--public-origin` is also present. Host/Origin checks\nuse the declaration and do not trust forwarded headers. Configure nginx to\nproxy HTTP and WebSocket upgrades to `127.0.0.1:49271` and terminate TLS;\nfleet accepts nginx's loopback upstream Host, so no Host rewrite is required.\nBrowser credentials add Secure for HTTPS, and `revoke-all` invalidates all\ntrusted devices. Role creation offers harness-scoped known-model choices\nwhile still accepting a typed model ID; blank explicitly uses the selected\nharness's own default.\n\n## Spawn\n\n```sh\nours-fleet spawn [--temp] [Name | --name Name] \\\n  --brain BRAIN_ID --role ROLE_ID \\\n  --cwd /absolute/path --identity Identity --coordinator Coordinator \\\n  --approval ask|auto|allow \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait --isolation-file /path/isolation.yaml\n```\n\nPermanent spawn writes `~/fleet/agents/Name.yaml` and starts a supervised role.\n`--temp` writes active state under `~/.ours-fleet/tmp` and starts an independent\ntransient supervisor (a collected systemd unit or submitted launchd job). It is\nnot enabled across reboot and does not die when the role that spawned it restarts.\nBrain definitions own the managed session backend. When a temporary role's bound identity\ncloses or its session ends, the supervisor, monitor and live roster entry retire\ntogether; state moves intact to `~/.ours-fleet/recovery/temporary` with a\ntermination record. Failed launches use the same archive rather than deleting\ntheir briefing, provenance, logs or partial supervisor metadata.\n\nNamed `down` and `rm` commands can target an exact state-backed temporary role\neven though it is absent from merged fleet YAML. The recorded transient unit/job\nis authoritative. Missing/incomplete ownership metadata is reconciled only from\nan exact `_run-temp <role>` process-table match: one match may be adopted, zero\nsettles as stopped, and ambiguity or an unreadable table fails closed. Launching\nrecords receive a bounded grace so a not-yet-registered transient unit cannot be\nmistaken for a stopped one. Stale recorded supervisors are reclaimed in bounded\nbatches by moving their state to the same recovery archive, never by blind deletion.\n\nEvery temporary role creates a new session-owned identity by calling ours MCP\n`create_temporary_identity` with its exact assigned name. It never binds a\npre-existing identity and never falls back to permanent `create_identity`.\nFleet does not inspect, preserve, or provision an ours identity for temporary\nspawn; creation belongs exclusively to the launched temporary agent session.\nCollisions, missing tool support, and creation errors stop safely without\nforce-adopting or deleting identity state. Permanent roles\nare provisioned by fleet before launch and never delegate normal identity\ncreation to the harness.\n\nThe temporary supervisor treats its first positive identity observation as the\nlifecycle readiness gate: a cold harness may take as long as needed to read its\nbriefing and bind, without a fixed first-bind retirement timer. After readiness,\nonly sustained authoritative absence closes the role. Unreachable, malformed, or\nvalid-but-empty daemon indexes are ambiguous and reset closure debounce rather\nthan becoming cleanup authority.\n\nInside a managed role, public `ours-fleet` commands cross an authenticated\nsupervisor attribution boundary before Commander parsing. The original CLI remains\nthe executor inside the role's existing OS sandbox, and ordinary CLI validation is\nthe source of truth. Hidden worker entry points remain internal; public lifecycle and\noperator commands are not restricted by the proxy.\n\nCommand invocation, raw argv, read-only work, validation failures, and generic\noutcomes are never forwarded to the Owner-visible channel. Fleet announces only\nconfirmed Agent, Task, and Room lifecycle changes. Local diagnostics retain\nstructurally redacted command metadata. Lifecycle delivery uncertainty is logged,\nnever recursively announced, and never reruns or blindly retries an effect.\nRoom participant summaries describe creation and activation. Fleet has no public\npost-create Room membership mutation, so it does not claim a separate membership event.\n\nOmitted Brain and Role selections, working directory, coordinator, neutral permissions,\nand fleet monitor policy inherit from the calling Agent. Explicit options always win.\nIdentity, mission/profile text, environment, owner routing, auth proxy, room startup,\nisolation, worklog, and sensitive inline Brain values never inherit implicitly.\nThis automatic proxy is a convenience and\nattribution mechanism, not an isolation boundary: an unrestricted role can still\ninvoke another binary path directly. Host/operator shells keep the ordinary direct\nCLI behavior.\n\nBrain owns harness, session, model, reasoning effort, token limits, and native harness\noptions. Removed runtime flags are rejected with migration guidance rather than silently\nreinterpreted. A selection is a stable ID or an explicit `inline:{...}` mapping.\n\nPackaged Developer, Critic, and LocalCoordinator Agent Templates set\n`monitor: { mode: fleet, interrupt: after_tool }`. Every member of the standard\n`single`, `pair`, and `team` Room Templates therefore resolves to fleet-owned,\nafter-tool delivery. Explicit per-member and custom Agent Template values remain\nauthoritative and merge key by key.\n\nManaged ACP stall recovery is opt-in: `monitor: { mode: fleet, stall_recovery: true,\n stall_timeout_ms: 900000 }`. The validated timeout is 60000\u201386400000 milliseconds.\nOmitted/false preserves existing behavior. Silence is measured from meaningful live\nprogress; replay and retry chatter do not reset it. Strong authenticated retry\nevidence requires one window, generic silence two. Tools, permissions, modal or\nunknown boundaries, steering and human cancellation protect the turn. Recovery\nuses one bounded cancel and diagnostic continuation in the same ACP session/queue\nslot; it never restarts the adapter. Startup and queued mail wait behind recovery.\nA durable claim permits at most one automatic attempt per ACP session ID, including\nacross supervisor restarts; later mail is non-cancelling. Failed or re-stalled\nrecovery reports a blocker. Inspect `.stall-recovery/audit.jsonl` and recorded\nterminal events before continuing; never replay ambiguous or completed mutations.\nNative monitoring/non-ACP sessions are unchanged. No room or identity coupling.\n\n## fleet.yaml\n\n```yaml\napi_version: ours.network/fleet/v2\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nwatchdogs:\n  nightwatch:                       # [A-Za-z0-9_-], must not collide with a role name\n    coordinator: FleetCoordinator   # required \u2014 where alerts go\n    # everything below is optional\n    enabled: true                   # default true; false = configured but never scheduled\n    interval: 10m                   # default 10m; 30s | 10m | 2h, minimum 1m\n    watch: [Alice, CodexReviewer]   # explicit lists are exact; omit for configured + live temp roles\n    agent: { ref: WatchdogAgent }   # required: declared Agent ID, or canonical inline Agent definition\n    identity: Watchdog-nightwatch   # default: Watchdog-<name>\n    timeout: 5m                     # default 5m; a run past this is killed and recorded as error\n    keep_reports: 50                # default 50 reports retained per watchdog\n    alert_cooldown: 60m             # default 60m before the same finding alerts again\n    prompt_file: /abs/extra.md      # optional extra focus, APPENDED to the fixed contract\n```\n\nAn Agent is a separate bare document under `~/fleet/agents/<ID>.yaml`:\n\n```yaml\nrole: { inline: { mission: Coordinate work and delegate implementation. } }\nbrain: { inline: { harness: codex, session: codex-app-server, model: gpt-model-id } }\nidentity: Coordinator\ncwd: ${work_root}/project\noversee: [{ agent: Worker, interval: 5m }]\n```\n\nA watchdog observes and reports; it never restarts, stops, spawns, or removes a\nrole, answers a pending permission, edits a workspace, or approves anything on\nthe owner's behalf. `watchdogs:` may appear only in the base config\n(`~/fleet.yaml` or `-c FILE`); Agent/Role/Brain documents never own it.\nThe selected Agent owns Brain, Role, permissions, isolation, and every other\nagent setting. Legacy watchdog `harness`, `model`, `session`, and\n`isolation` fields fail with migration guidance.\nWhen `watch:` is omitted, each run watches the configured roles plus temporary\nfleet roles that are live when the run starts. An explicit `watch:` list is\nnever augmented.\n\nAgent operational values override manifest operational defaults. Role and Brain\nownership never cross-merges. `${name}` substitutes entries from `vars`.\nBrain fields include `max_tokens` and `autocompact_pct`; isolation is Agent-owned.\nUse README.md for the complete isolation policy and resource-cap schema.\n\nSupervised roles connect to the operator-configured ours daemon; they do not own its\nlifecycle. Fleet strips the obsolete, presence-sensitive `OURS_AUTOSTART` variable from\nagent-session children; `ours-mcp proxy` is client-only and never starts a daemon. Start\nthe shared daemon only through an explicit operator or installer/setup flow.\n\n## Rooms and tasks\n\n`init` materializes editable `single`, `pair`, and `team` Room templates plus\ntheir exact-cased Agent, Role, and Brain presets. The command prints the packaged\npreset revision and source directory. Inspect provenance and content before use:\n\n```sh\nours-fleet config [-c FILE]\nours-fleet template list [-c FILE]\nours-fleet template show team [-c FILE]\nours-fleet task create --title \"Solo task\" --template single [-c FILE]\nours-fleet task create --title \"Reviewed change\" --template pair [-c FILE]\nours-fleet task create --title \"Phased delivery\" --template team [-c FILE]\nours-fleet spawn --temp Scout --role SELECTION --brain SELECTION --loops-file PRIVATE.yaml\nours-fleet task start TASK --member developer --loops-file PRIVATE.yaml\nours-fleet task start TASK --member critic --no-loops\n```\n\n`--loops-file` must be an owner-only, non-symlink regular file <=1 MB containing\nexactly one top-level non-empty `loops:` mapping. `--no-loops` explicitly\ndisables loops. They are mutually exclusive and rejected for permanent spawn.\nFor a grouped room member the whole CLI block overrides its Agent Template;\nthe template overrides omission. Omission preserves historical no-loop behavior\nand never inherits manifest wildcard loops. Fleet validates before side effects,\nseals normalized timings plus exact private prompts, and reuses that snapshot for\nidempotent start, retry, recovery, and replacement. Trusted authoring and the\nprivate sealed runtime retain exact prompts; resolved launch, task, room,\nprovenance, and audit presentations show source, policy, timing, prompt bytes,\nand prompt SHA-256 instead of prompt text.\n\nAn alternate manifest `-c /path/custom.yaml` uses `/path/custom/` as its split\nroot. Repeated init only fills missing files and never adopts a newer default.\nExact known revision-3 through revision-5 packaged-bootstrap and generated role defaults have an exact-semantic,\nfail-closed migration (dry-run by default):\n\n`ours-fleet migrate-role-defaults [-c FILE]`\n`ours-fleet migrate-role-defaults [-c FILE] --write`\n\nReview removals, replacements, additions, preserved custom files, staging path,\nand recovery path. Same-named custom files stay byte-identical; dangling custom\nreferences refuse publication, and a successful rerun is a no-op. For explicit\nsingle-file adoption, copy from init's reported packaged source beside the target\nas `.new-default`, inspect `diff -u TARGET TARGET.new-default`, then replace it.\n\nThe exact generated six-worker legacy starter Agent set has its own fail-closed\nmigration (dry-run by default):\n\n`ours-fleet migrate-agent-templates [-c FILE]`\n`ours-fleet migrate-agent-templates [-c FILE] --write`\n\nReview the dry-run moves, addition, staging path, and retained recovery-backup path\nbefore `--write`. Customized/partial known starters and unsafe trees refuse without\nmutation; unrelated custom persistent Agents remain persistent. A manifest-level template\nmay shadow a same-named file only with `override_builtin: true` and a higher\nversion; this compatibility marker is deprecated and reported as a diagnostic.\n\nRooms always use `ours-cowork`; there is no room-provider selector. Configure\nthe cowork daemon connection and room owner directly:\n\n```yaml\nrooms:\n  cowork:\n    config: /home/me/.ours-cowork/config.json\n  owner:\n    expected_cid: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n    public_invite_file: /home/me/.ours-fleet/owner-room-invite.txt\n  defaults:\n    template: team\n    attach_owner: true\n    close_when_task_done: true\ntasks:\n  default_room_template: team\n  create_mode: start\n  close_room_on_done: true\n```\n\nFleet launches each template member with a dedicated one-time Cowork invite.\nThe generated temporary-agent briefing contains the exact identity name, invite,\nCowork role, and task. The agent creates that identity itself with ours MCP\n`create_temporary_identity`, accepts the invite with `add_contact`, and starts\nwork immediately. A room is ready only after the Cowork room (and its task, when\ntask-bound) is durably active, every configured member seat is authenticated and active with its matching\nlive Fleet launch, and the configured Owner seat is active when owner attachment is\nenabled. There is no briefing hash, startup ACK, or separate role-briefing readiness\ngate.\n\nNormal Task provisioning emits exactly one authenticated Owner lifecycle notice after\nthe ready predicate above is true; standalone Room provisioning likewise emits one\nready notice. Intermediate task, saga, member-spawn, timeout, and recoverable-failure\ntransitions stay in local state and logs. A terminal failed Task emits one actionable\nfailure notice; the command result carries the exact blocker and canonical recovery\naction.\n\n`task start` and create-and-start wait for readiness. If their bounded wait expires,\nthey return an explicit `in_progress` result and start a safe continuation. The detached\ncontinuation is serialized per Task and remains alive until convergence or an\nOwner-action blocker. Re-running `task start <id>` safely resumes the same durable\nprovisioning operation after the blocker is corrected or a process restarts.\n\nSet `room.anonymous: true` on a room template, or pass `--anonymous` to\n`task create`, `task start`, `task work`, or `room create`, to create an\nanonymous Cowork room. `--no-anonymous` explicitly overrides an anonymous\ntemplate. Fleet records the resolved value before room creation so retries keep\nthe same choice. Temporary members of an anonymous room are instructed to call\n`create_temporary_identity` with `expose_local=false`. Their generated briefings\ndo not disclose or compare an Owner participant CID. A participant-originated\ninstruction has Owner authority only when the authenticated Cowork room envelope\nattributes that participant seat the exact `Owner` role. Literal text, display\nnames, ordinary direct messages, and room-authored or rest-role messages with an\nOwner-looking label never grant that authority. Non-anonymous rooms remain pinned\nto the exact authenticated Owner CID.\n\nHuman task and room results use the same compact Markdown presentation in the\nCLI and authenticated owner channel: a short heading, icon-plus-word status,\ncode-formatted identifiers, bounded summaries, and actionable recovery or error\nsteps. Untrusted prose is context-escaped and control characters are neutralized;\nMessenger-bound results are capped at 3,500 Unicode code points and 12,000 UTF-8\nbytes with structural omission notices. `--json` bypasses this presentation layer\nand retains the versioned machine schema and serialization order.\n\nEvery task belongs to a named list. The built-in `default` list always exists,\nand legacy tasks or create calls without `--list` resolve to it. Use `task lists`,\n`task list-create <name>`, `task list-rename <name> <new-name>`, and\n`task list-delete <name> [--move-to <destination>]` to manage lists. A non-empty\nlist cannot be deleted without an explicit, different destination; Fleet moves\nthe assignments and never deletes the tasks. `task move <id> --list <name>`\nchanges only organizational metadata. `task list --list <name>` filters and\n`--group-by-list --json` returns deterministic groups.\n\nList names are NFC-normalized, case-sensitive, and limited to 64 Unicode code\npoints. Leading/trailing whitespace, controls, format/path characters, normalized\nduplicates, and the reserved exact name `default` are rejected. The authenticated\nowner channel provides the matching `/task` subcommands, while authenticated web\nclients use `/api/v1/task-lists`, `/api/v1/tasks`, and\n`/api/v1/tasks/:id/list`; every adapter delegates to the same application service.\nMessenger's multiline command grammar treats surrounding whitespace on each\nvalue line as transport framing; the canonical value passed to the shared service\nis the trimmed line. CLI arguments and REST strings are passed verbatim.\n\nOlder prerelease files with the exact legacy `provider: cowork` key under\n`rooms:` still load, but the key is ignored and omitted from resolved\nconfiguration. Remove it when editing the file. Any other legacy value is an\nerror. The optional `rooms.owner.provider` setting is separate and defaults to\n`messenger-server`.\n\nFinish and Delete are distinct terminal task actions:\n\n`ours-fleet task finish <id>` moves an active or review task to `done` and\ndeletes its associated Cowork room after retiring its members. The room then\ndisappears from normal Fleet and Cowork views; its brief, messages, repository\nreferences, and attachments are not retained as an inspectable archive.\nThe prerelease configuration names `tasks.close_room_on_done` and\n`rooms.defaults.close_when_task_done` are retained for compatibility, but\n`true` now means this close-then-delete behavior.\n\n`ours-fleet room delete <id> <id>` is the canonical destructive room command.\n`room close <id> <id>` remains a deprecated alias with identical deletion\nsemantics. Older prerelease `closed` room records are deleted directly the next\ntime `room list` reconciles Fleet with Cowork.\n\n`ours-fleet task delete <id> <id>` permanently deletes a task in ANY lifecycle\nstate \u2014 backlog, provisioning, active, blocked, review, done, cancelled, failed,\nor partially settled. The exact task ID is required twice for confirmation. A\ndurable deletion intent is persisted before any side effect; the cleanup worker\nthen retires managed room members with evidence, closes and deletes an attached\nroom (tolerating already-missing remote rooms), releases the sealed launch\nsnapshot, and unlinks the task record last. While cleanup settles the task is\nhidden from normal listings and every lifecycle mutation is rejected; if\ncleanup cannot complete (for example Cowork is unreachable), the deletion stays\nin a precise resumable state \u2014 repeat the identical delete command to converge\nafter outages, crashes, or restarts. Deletion\nnever fabricates a `done` transition. A metadata-only deletion receipt\n(acceptance actor, original state, timestamps, completion) is retained under\n`deletion-receipts/` as durable audit evidence. An already-missing task is an\nidempotent no-op. The Owner-channel equivalent is `/task delete <id> <id>`; the\nmanagement API equivalent is `DELETE /api/v1/tasks/<id>?confirm=<id>` (200 when\nsettled, 202 while pending; `GET /api/v1/tasks?includeDeleting=true` exposes\ndeletion-pending tasks to operators).\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|auto|allow`: portable permission policy. `deny` remains a\n  deprecated, fail-closed compatibility alias for existing fleet files.\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what a managed session does when no console can\n  answer a request\n\nThe backend translates this common intent. Native Codex app-server roles reject\npermission aliases in `harness_options`; Codex ACP and Claude retain their\nlegacy native-override compatibility. Do not choose `allow`/`unrestricted`\nor Claude `bypassPermissions` without explicit authorization.\n\n### Creation-time isolation\n\n`ours-fleet spawn --isolation-file <path>` supplies a role's sandbox policy at\ncreation, so the FIRST launch is already confined \u2014 a role that only gains\n`isolation:` on a later `up` ran unsandboxed until then.\n\nThe file holds exactly the `isolation:` mapping documented above and nothing\nelse \u2014 the same schema, validated by the same code, so a policy written here\ncannot mean something different from the identical block in fleet.yaml:\n\n```yaml\nnetwork: deny\nfs:\n  read: [/opt/reference]\nresources:\n  mem: 2G\n```\n\nInvalid files are rejected before anything is created: no config, no state\ndirectory, no identity reservation. Works for both permanent and `--temp` roles.\n\n### Never-prompt failure\n\nThe failure this section exists to prevent leaves no error message anywhere.\n\nAn unattended role has no console. When the harness needs a permission decision\nthere is nobody to ask, so the request is refused INSIDE the harness \u2014 no\nprompt, no error, no log line. The agent simply does less than its briefing told\nit to, reports success, and nothing distinguishes that from having done the\nwork. Two settings produce it:\n\n1. a permission mode that suppresses the prompt without granting the action\n   (Claude `dontAsk`, which is why neutral `allow` maps to\n   `bypassPermissions` instead); and\n2. `unattended: deny`, which refuses every request that reaches it.\n\n**Automatic decisions are now recorded.** Every permission request decided\nwithout a human emits a completed event into\n`~/.ours-fleet/agents/<Name>/.session-events.jsonl` carrying the decision,\nwhether policy or a person made it, the policy that produced it\n(`permissions.unattended=deny` vs `permissions.approval=deny`/`=allow`),\nthe reason, and the option selected. `ours-fleet peek` and `attach` render\nthem. Automatic denial asks for a one-shot rejection, never a standing one, so a\nsingle unattended refusal cannot disable a tool for the rest of the session.\n\nA role that can auto-deny logs one line at startup saying so.\n\nTo detect an under-permissioned role BEFORE it runs, use the capability floor\nbelow: `ours-fleet doctor` fails such a role rather than letting it discover\nthe problem silently at work.\n\n### The unattended capability floor\n\nAn unattended role has no console, so a permission request cannot be answered \u2014\nit is refused, silently, inside the harness. The agent then does less than it\nwas told to and reports no error. To make that visible before launch,\n`ours-fleet config` and `ours-fleet doctor` resolve each role's neutral\npermissions through its harness and check the result against a fixed floor:\n\n- `read-state` \u2014 read its briefing, ROUTINES.md, and WORKLOG.md\n- `write-state` \u2014 append its WORKLOG and its own state files\n- `messaging` \u2014 bind its identity, send and receive ours mail\n- `monitor` \u2014 arm and observe its mail monitor\n- `workspace-edit` \u2014 edit and test files in its working directory\n- `status-commands` \u2014 run the inspection commands its briefing prescribes\n\n`doctor` reports this per role as `unattended floor: <Role>`. A role with\n`unattended: deny` that cannot meet the floor FAILS doctor, because it will\ndeny those requests with nobody to see it; with `unattended: wait` it warns,\nbecause a human can still attach and answer.\n\nSecurity meaning: native Codex maps `ask` \u2192 `untrusted`, `auto` \u2192\n`on-request`, and `allow` \u2192 `never`; its independent filesystem mapping is\n`read-only` \u2192 `read-only`, `workspace` \u2192 `workspace-write`, and\n`unrestricted` \u2192 `danger-full-access`. Users configure only the Fleet names.\nClaude maps `ask` to `default`, `auto` to `acceptEdits`, and `allow` to\n`bypassPermissions`. Codex ACP retains its adapter-specific coupled modes:\n`auto` selects `agent`, while `allow` selects `agent-full-access`. These\nmodes genuinely permit the actions the role was authorized to take \u2014\n`dontAsk` only suppresses the prompt while still refusing the action. Nothing\nother than an explicit `allow` becomes non-interactive. Legacy `deny` keeps\nits conservative Codex `on-request` / Claude `plan` translation. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\n\nACP carries agent-advertised session mode IDs and `session/set_mode`, but those\nIDs are agent-specific and ACP defines no portable permission-policy capability.\nFleet therefore uses the ACP primitive where an adapter exposes a matching mode\nand otherwise performs the harness translation above. The bundled Codex ACP\nadapter couples approval and sandboxing in its advertised mode IDs. Neutral\n`allow` therefore selects `agent-full-access` and widens `filesystem:\nworkspace` or `read-only` to `danger-full-access`; neutral `auto` selects\n`agent` and `workspace-write` even when the neutral filesystem value differs.\nAn explicit `harness_options.sandbox` selects its corresponding ACP preset and\nstill wins, as does an explicit native approval override. `config` and\n`doctor` report a coupled-mode mismatch as approximate. Use per-role\n`isolation:` as the outer boundary for an `allow` ACP role. The live session\nreports both its effective normalized mode and the exact native mode selected.\n\nSee also: `spawn --approval/--filesystem/--unattended` set this intent at\ncreation, and `ours-fleet config` prints each role's neutral settings, their\nnative translation, and any warning \u2014 the same text `doctor` reports.\n\nClaude `harness_options`: `permission_mode` (default, acceptEdits, plan,\ndontAsk, bypassPermissions), `plugins`, `mem_palace`,\n`mem_palace_midsession_autosave`, `mcp_servers` and `mcp_servers_only`.\n\n`mcp_servers` declares MCP servers for the role, in `.mcp.json`'s own shape\n(a map of name to `{ command, args, env }`, or `{ type: http|sse, url,\nheaders }`). By default they are ADDED to whatever the OS user running the role\nalready has configured. The Claude Code adapter sends them in `session/new`.\n\nWhen `mcp_servers` is absent, Fleet sends ACP's protocol-required empty\n`mcpServers` array without an exclusive override, so the agent keeps its inherited\nservers. An explicitly empty configured set is different: Fleet preserves that intent\nthrough the bundled adapter's compatibility path and disables every inherited server.\n\n`mcp_servers_only: true` makes the declared set EXCLUSIVE through\n`strictMcpConfig`. It is all-or-nothing and it ignores every\nother MCP configuration: project `.mcp.json`, user settings, and **plugins**.\nThe ours connector is normally installed as a plugin, so a strict role that does\nnot re-declare it has no `send_message` and no `get_messages` \u2014 it cannot even\nreport that it has gone mute. Fleet therefore refuses a strict role whose\n`mcp_servers` does not name the connector; declare it explicitly, e.g.\n`ours: { command: ours-mcp, args: [proxy] }`.\n\nBoth options, and `plugins`, reach an ACP session through the bundled Claude ACP\nagent's `_meta` vocabulary. A role that sets `session_options.acp.command` runs\nan agent fleet did not choose and cannot be promised them, so that combination is\nrefused at validation rather than accepted and dropped. This narrows a role's\ntool surface; it does not stop the harness deferring tool schemas, which is the\nharness's own decision.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `search`,\n`config`, `add_dirs`, and `monitor`; Codex ACP additionally supports\n`profile`. Native app-server roles reject `profile` because Codex does not\naccept `--profile` for `app-server`. They\nmust express approval and filesystem authority through the shared\n`permissions:` block, never through harness options. The adapter translates\n`ask|auto|allow` to Codex `untrusted|on-request|never` and translates\n`read-only|workspace|unrestricted` to Codex\n`read-only|workspace-write|danger-full-access`. Native `config` currently\nallows only `model_reasoning_effort`; ACP retains the broader Codex config surface.\n\nFor Codex, the opt-in `session: codex-app-server` directly runs Codex's native\nJSONL app server behind Fleet's provider-neutral session contract. It supports native item\nstreaming, commentary/final phases, prompt admission, steering, interruption,\npermission requests, durable conversation projection, and thread resume. Packaged\nCodex brains and the init wizard continue to select `session: acp` for compatibility;\nClaude Code also uses ACP. Native Codex defaults to `codex app-server` (or `ours-codex app-server`\nwhen launcher auto finds it). Override the exact command when necessary:\n\n`session_options: { codex_app_server: { command: [codex, app-server] } }`\n\nAn exact command override receives no appended profile, search, or subcommand\narguments. Native sessions persist their Codex thread in Fleet's `.session-id`\nand participate in its bounded fresh/resume recovery; cross-provider conversation\nportability is never assumed.\n\n## ACP adapters\n\nThe maintained `@agentclientprotocol/codex-acp` and\n`@agentclientprotocol/claude-agent-acp` runtimes are bundled automatically as\noptional ours-fleet dependencies. The supervisor resolves their executable\nentrypoints internally, so default ACP roles do not depend on global PATH.\nours-fleet and both maintained adapters require Node 22 or newer.\n\nOverride an adapter only when necessary with `session_options.acp.command`\n(string or argv list). If optional dependencies were deliberately omitted,\nours-fleet falls back to a compatible globally installed `codex-acp` or\n`claude-agent-acp`. `ours-fleet doctor -c FILE` verifies the resolved adapter.\n\n## Reliable mail wake\n\n`monitor.mode` selects exactly one wake owner:\n\n- `fleet` (default): the ours-fleet supervisor consumes body-free daemon\n  events and advances its durable cursor only after delivery is accepted. ACP\n  uses live steering when supported and falls back to structured\n  `session/prompt`.\n- `native`: ours-fleet starts no supervisor monitor; the generated briefing\n  instructs Claude Code or Codex to arm its harness-native wake mechanism.\n\nSet `monitor.interrupt: true` in fleet mode to cancel active work before every\nconfigured wake. Set it to `after_tool` to preserve an active ACP tool (and any\npending permission), then steer the wake at the first tool-terminal boundary\nwithout cancellation. A hung boundary is bounded at 120 seconds and falls back\nto non-cancelling steering/queueing; adapters without authenticated tool events\nuse the same conservative fallback. Explicit human/control interrupts remain\nimmediate. The policy is content-blind because the supervisor cannot inspect\nencrypted message bodies. Message bodies are released only when the role calls\nthe ours `get_messages` tool.\n\nThe default is `false`. For a temporary role whose mission intentionally arrives\nafter its readiness announcement, set `mode: fleet` and `interrupt: true`\nexplicitly. The readiness announcement does not change the transport: the\nmission remains ordinary ours mail, fleet injects only the body-free wake, and\nthe role calls `get_messages` before acting. Every later configured wake uses\nthe same interruption policy.\n\nLegacy `monitor.enabled: true|false` remains accepted as an alias for\n`mode: fleet|native`; use `mode` in new configuration. Codex's separate\n`harness_options.monitor: true` is native-monitor consent, not monitor-owner\nselection.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\n\n## Trusted owner channel\n\nAny managed role may declare a separate ours identity which fleet \u2014 never the agent \u2014\ncreates when missing and binds:\n\n```yaml\nowner_channel:\n  identity: Coordinator Owner Channel\n  owners: [authenticated-owner-contact-cid]\n  agent: authenticated-managed-agent-cid\n  interrupt: false\n  progress_interval_ms: 30000\n  comments: true\n  attachments:\n    enabled: true\n    max_files_per_request: 4\n    max_file_bytes: 10485760\n    max_request_bytes: 20971520\n    retention_ms: 86400000\n```\n\nPermanent role identities are also reconciled before launch. Fleet creates a\nmissing role identity with local exposure and local auto-accept enabled. A\nmissing owner-channel identity uses the safer inverse policy: both are disabled.\nThe short provisioning lease is released before the agent or channel binds.\nTemporary role identities remain connector-owned because their creating lease\ndefines their cleanup lifetime.\n\nThis does not replace the role identity. Normal identity mail remains untrusted\npeer input: the agent reads it through `get_messages` and replies through\n`send_message`. Mail arriving on the dedicated channel from a CID in `owners`\nis injected as a direct `[fleet-owner]` prompt. Mail from the exact `agent`\nCID is forwarded as a new message to the latest authenticated owner conversation;\nits files may also be relayed through this channel. A reply reference selects the\nowner of that authenticated source wire instead of the latest conversation.\nEvery other CID is rejected and warned about without reflecting its body. Fleet sends\naccepted/queued/progress/interrupted/failure notices and routes the ACP turn's\nfinal assistant text back to the authenticated sender with its source wire ID.\nFor file replies of every kind \u2014 a response artifact, a proactive note, or an\nin-turn attachment \u2014 the agent calls ours `send_file` to the channel identity\nand may pair it with a reply-linked caption; fleet, not the agent, chooses the\nowner. That is the only delivery route an agent is given: a tool call either\ndelivers or reports an error, where a file written to disk does neither.\nOwner messages whose trimmed text starts with `/` are deterministic\nsupervisor commands and never enter the model: `/help` (alias `/commands`),\n`/status`, `/comments [status|on|off]`, `/interrupt`, `/clear`,\n`/compact`, `/model <model-id>`, `/restart`, `/force-restart`, `/ls`,\n`/peek`, `/worklog`, and\n`/version`. Unknown or malformed commands answer with the help text instead of\nbeing forwarded; plain messages reach the agent unchanged. `/clear`,\n`/compact`, and `/model` are forwarded only when the role's bundled ACP\nadapter executes them locally (claude-code: all three; codex: `/compact`\nonly) and are otherwise refused with a notice, so slash text never reaches the\nmodel as a prompt.\n\nThe supervisor advertises the same primary registry entries as recipient-scoped\nours typed commands. Their single arguments field is converted back to the text\nafter the slash command name and enters the same dispatcher; aliases stay\nslash-only. Typed handlers repeat the live authenticated Owner-CID check before\ndispatch and return a null protocol completion because the existing correlated\nowner-channel reply remains the result.\n\nWhile a request runs, the agent's live ACP commentary is relayed as messages\nprefixed with the single stable label `\uD83D\uDFE1 Live update:`, so an owner can see\nexactly which messages the setting controls. `owner_channel.comments`\n(default `true`, so existing channels keep their current behavior) is the\nRESTART BASELINE; `/comments on|off` changes only the running session and is\ndeliberately not persisted, so a restart always returns to the checked-in\nconfiguration. `/comments status` reports the live value, the baseline, and\nwhether the backend emits live comments at all. Suppressing live comments never\nsuppresses receipts, progress notices, or the final answer.\n\nOwner documents, images, and voice messages use the same authenticated sender\nand source-wire boundary. Fleet inspects body-free metadata first and rejects\ndisabled, over-count, or over-size requests before selective\nretrieval. Unauthorized CIDs are never retrieved or answered. Reply-linked text\nand files from the same sender become one ordered request; a file-only wake also\nstarts a turn. Retrieved bytes must match their structured size and SHA-256,\nwhile MIME values, extensions, file categories, and declared-versus-detected mismatches\nremain report-only metadata. Symlinks or non-regular paths fail closed. Sanitized copies live only in a mode-0700 request directory as\nmode-0600 files and are removed after completion or bounded stale retention.\n\nThe legacy `attachments.allowed_mime` key is accepted and ignored so existing\nconfigurations keep loading; it is omitted from resolved configuration and cannot\naffect admission.\n\nVoice prompts include a bounded transcript only when typed daemon metadata reports success.\nFailure or unavailability is explicit and preserves the private audio path as the\ninput for direct review. Run `ours config show --json` and inspect `sttConfigured` without\nrevealing provider credentials.\nA mode-0600 message claim journal stores only wire ID, persistent-history\nsequence, and claim time. Fleet journals the exact body-free oldest-first slice\nbefore calling `getMessages` with that slice length, rejects a returned set\nmismatch, and loads a crash-recovered body only through `getHistoryItem`.\nThe attachment crash journal contains only authenticated CID and wire routing\ndata; it never stores captions, filenames, paths, transcript text, or bytes.\nJournaled read files resume through `getFileInfo` and `fetchFile`. A claimed\nagent caption is loaded from history and rejoined before the group is admitted. Fleet\nresolves one authenticated owner route before retrieving bytes, admits every file\nbefore emitting the caption or any file, and sends every part to that same route.\nUnknown correlated routes remain queued without retrieval and receive one bounded\ncorrelated notice. Admission rejection consumes the whole group with one NACK;\nonce emission starts, a transport error becomes terminal uncertain delivery and\nthe group is never blind-retried. Bounded v2 source-wire routing state is migrated\nfrom v1 on read. Corrupt state disables attachment admission rather than weakening\nprovenance checks.\n\nThe channel identity must be unique and must not be a role identity. The bridge\npersists bounded wire IDs only, never message/reply plaintext, and requeues input\nbefore starting its turn for at-least-once crash recovery. It currently requires\nthe structured agent-session interface so correlated final replies retain their\ndelivery guarantee.\n\n### Live contact and owner administration\n\nThe supervisor which is already running the managed role remains the sole binder of\n`owner_channel.identity`. The CLI reaches that exact live `OwnerChannel`\nthrough the role's token-authenticated, mode-0600 Unix control socket for contact\ninspection and setup; it never starts another ours client and never force-binds:\n\nRapid supervised restart is serialized by a role-scoped single-binder lease.\nThe predecessor closes its authenticated control socket and MCP proxy before\nreleasing ownership. The replacement waits at most five seconds and retries the\ndaemon bind only when PID/start-marker metadata proves the holder was the same\nrole and owner-channel identity. Foreign, live, corrupt, or otherwise\nunverifiable ownership remains fail-closed; fleet never uses `force=true`.\n\nIf that matching predecessor misses the bound, its still-authenticated control\nroute may send one fixed, digest-deduplicated recovery notice through the latest\nauthenticated owner conversation (or the sole configured owner). Notice\nplaintext is never persisted. With no safe deterministic route fleet guesses no\nrecipient and leaves the actionable failure in the web console and role logs.\nThe remote recovery action is `/restart`; inspect repeated failures with\n`ours-fleet logs <Role>` or the web console.\n\n```sh\nours-fleet owner-channel contact list <Role>\nours-fleet owner-channel contact invite <Role> [--name <label>]\nours-fleet owner-channel contact add <Role> (--invite-file <path> | --invite-stdin) [--name <label>]\nours-fleet owner-channel owner list <Role>\nours-fleet owner-channel owner authorize <Role> <exact-64-hex-contact-cid>\nours-fleet owner-channel owner revoke <Role> <exact-64-hex-contact-cid>\n```\n\nContact establishment and owner authorization are separate security steps.\n`contact add` never authorizes: invite redemption is pending until the peer\nverifies it. Once `contact list` reports the established contact, authorize\nits exact immutable CID explicitly. Invite creation emits invite material only\non stdout; acceptance reads it from a file or stdin, not argv.\n\nConfigured `owners` remain the baseline. On legacy channels without `agent`,\nlive authorizations/revocations are an immediately effective, restart-persistent\noverlay. Managed-agent CID gating makes fleet configuration authoritative and\ndisables live owner mutation and direct control-socket sends. `owner list` labels\nbaseline versus dynamic entries and effective status. The atomic mode-0600 file\ncontains bounded CIDs and audit actions only. Corruption disables all effective\nowners and refuses mutation rather than resurrecting authority; revoking the\nlast effective owner is always refused.\n\nA missing/stopped role, role without `owner_channel`, unavailable\nMCP client, or a role entering shutdown returns an actionable error with no\nside effects. Management uses no network listener and never logs or persists\ninvite material.\n\nFor any non-final message\u2014progress, blocker, suggestion, or later proactive note\u2014\nthe managed agent calls ordinary ours `send_message` to the channel identity.\nFleet checks only that the authenticated sender CID exactly equals `agent`, then\nforwards the text as a new message. There is no task/request/update type, phase,\nreply correlation, or owner recipient argument. A sole owner is the safe fallback;\nwith multiple owners and no inbound route history the relay fails closed. Devices\nsharing one identity share its CID; separate owner identities hand off the route\nwhen either sends channel mail. The ACP final is separate: fleet extracts it from\nthe completed turn and deterministically replies to the initiating owner wire.\n\nThe bounded mode-0600 route state stores CIDs, wire IDs, timestamps, delivery state,\nand hashes but never message plaintext. Unauthorized attempts produce a bounded\nCID-only owner warning; attempted bodies are neither reflected nor persisted.\n\nFor a mobile owner, establish the contact first, wait for peer verification,\nauthorize its exact CID, and revoke that same CID when access ends. The bounded\nmode-0600 CID overlay survives supervisor restart and remains fail-closed on\ncorruption. Update bodies remain memory-only. After a crash/restart, unfinished\ndeferred owner input follows the existing at-least-once replay path; the restarted\nsupervisor remains the sole binder.\n\n## Stable config and YAML migration\n\n`ours-fleet config --json` emits schemaVersion 1 resolved plans. Environment\nvalues and mission/persona/bio bodies are withheld; environment keys are sorted\nand values are marked redacted. Additive fields may appear in schema 1, while a\nremoval or semantic reuse requires a new schema version.\n\nYAML parsing always rejects duplicate keys. The current default\n`--yaml-mode compat` warns with file/line/column for anchors, aliases, explicit\ntags, non-scalar keys, and multiple documents. Use `--yaml-mode strict` in CI\nnow; strict becomes the next-major default and compat is the temporary migration\nescape hatch.\n\n## Bounded worklogs, auth proxy, and model recovery\n\nWORKLOG rotation is enabled by default with\n`worklog: { max_kb: 1024, keep_tail_kb: 256, max_archives: 12 }`. Maps may\noverride individual values; `worklog: false` on a role or in defaults opts out.\nFleet rotates only at that role's launch/resume lifecycle boundary. Concurrent\nchanges defer rotation. The active file keeps a bounded UTF-8 tail and advances\nto a line boundary when a complete line fits. If one logical line alone exceeds\nthe budget, its newest suffix remains and the rotation manifest records the\nmid-line start and omitted byte count. The complete prior inode receives a\ncollision-safe UTC archive name, and\n`.worklog-rotation.json` records restart provenance. `max_archives` bounds\nrecent archives beside WORKLOG.md; older complete archives move to\n`WORKLOG.archives/` without deletion. All archives share the role's sensitive\nstate boundary. Fleet refuses a symlinked/non-regular live log or a symlinked\ncold-archive boundary before replacing the live path and best-effort removes a\nduplicate publication left by a detected failure while the original inode is\nstill available. The manifest records SHA-256 digests for the archive and live\nbytes observed when it is written. These checks address ordinary path hazards,\nnot intentional path mutation by a malicious concurrent process with the same\nUnix authority; that is outside the threat model and requires OS-level isolation.\n\nACP tool diffs are bounded before entering web conversation events. Existing\nsmall before/after diffs are unchanged. Oversized whole-file snapshots are\nreduced to the actual changed region plus path, operation, original byte counts,\ndigest, and omission metadata. Each retained side is a newest-content UTF-8 tail\nof at most 64 KiB, advanced to a line boundary when a complete line fits. An\noverlong single line keeps its newest suffix and explicitly records a mid-line\nstart. Paths retain at most a 4 KiB suffix with byte count, digest, and omitted\nprefix metadata; the complete normalized update is capped at 320 KiB. A large\nappend therefore retains current appended content, not the historical prefix.\nThe live web-console transcript includes only the current runner generation and\nexcludes adapter session/load replay. Replayed events remain durable with\nagent_replay provenance for diagnosis and recovery.\n\n`auth_proxy: { kind: anthropic, base_url, required, health_url }` is Claude-only\nand loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects\ncredential env keys. The privileged reference companion is\n`contrib/anthropic-auth-proxy.mjs`; deploy it separately as a dedicated account\nwith a 0600 token file and per-role listener access. Fleet never installs it or\nreads its credential.\n\n`model_chain` is an ordered authorization list and its first entry must equal\n`model`. Only sustained high-confidence entitlement/quota 429 evidence advances\none entry. Transient 429, overload, auth, policy, and unknown errors never\ndown-shift. Runtime state is atomic in .model-recovery.json; exhaustion is\nfail-closed and held down. Change the declared chain/model and restart to\nreconcile explicitly; no chain preserves detection-only behavior.\n";
 /**
  * What every shipped spawn-skill variant must say, and must not say.
  *

package/dist/docs.js

@@ -257,6 +257,20 @@ Packaged Developer, Critic, and LocalCoordinator Agent Templates set
 after-tool delivery. Explicit per-member and custom Agent Template values remain
 authoritative and merge key by key.
 
+Managed ACP stall recovery is opt-in: \`monitor: { mode: fleet, stall_recovery: true,
+ stall_timeout_ms: 900000 }\`. The validated timeout is 60000–86400000 milliseconds.
+Omitted/false preserves existing behavior. Silence is measured from meaningful live
+progress; replay and retry chatter do not reset it. Strong authenticated retry
+evidence requires one window, generic silence two. Tools, permissions, modal or
+unknown boundaries, steering and human cancellation protect the turn. Recovery
+uses one bounded cancel and diagnostic continuation in the same ACP session/queue
+slot; it never restarts the adapter. Startup and queued mail wait behind recovery.
+A durable claim permits at most one automatic attempt per ACP session ID, including
+across supervisor restarts; later mail is non-cancelling. Failed or re-stalled
+recovery reports a blocker. Inspect \`.stall-recovery/audit.jsonl\` and recorded
+terminal events before continuing; never replay ambiguous or completed mutations.
+Native monitoring/non-ACP sessions are unchanged. No room or identity coupling.
+
 ## fleet.yaml
 
 \`\`\`yaml

package/dist/harness/claude-code-session.js

@@ -31,6 +31,9 @@ export class ClaudeCodeAgentSessionAdapter {
             permissionMode: options.permissionMode,
             permissionMetadataSource: acpAdapterState(launch.adapterState).permissionMetadataSource,
             scrubObsoleteOursAutostart: true,
+            ...(role.monitor?.mode === 'fleet' && role.monitor.stall_recovery ? {
+                stallRecovery: { timeoutMs: role.monitor.stall_timeout_ms },
+            } : {}),
             log: options.log,
         });
     }

package/dist/harness/codex-session.js

@@ -46,6 +46,9 @@ export class CodexAgentSessionAdapter {
             permissionMode: options.permissionMode,
             permissionMetadataSource: acpAdapterState(launch.adapterState).permissionMetadataSource,
             scrubObsoleteOursAutostart: true,
+            ...(role.monitor?.mode === 'fleet' && role.monitor.stall_recovery ? {
+                stallRecovery: { timeoutMs: role.monitor.stall_timeout_ms },
+            } : {}),
             log: options.log,
         });
     }

package/dist/runner.js

@@ -612,7 +612,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         arbiter = new RoleTurnArbiter(agentSession);
         sessionHandle = arbiter;
         unsubscribeRecovery = agentSession.subscribe(event => {
-            if (event.kind !== 'error' || !event.text)
+            if (event.kind !== 'error' || !event.text || event.origin?.kind === 'stall-watchdog')
                 return;
             const evidence = classifyFailureText(event.text, sessionBackend, new Date(deps.now()).toISOString());
             if (evidence)
@@ -747,7 +747,8 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         // valid. Keep every unproven cancellation, refusal, shutdown, and genuine
         // failure terminal so a role that never accepted its briefing is not
         // silently reported as healthy.
-        const interruptedForWake = isRecoverableTempStartupCancellation(temp, started);
+        const interruptedForWake = isRecoverableTempStartupCancellation(temp, started)
+            || (started.outcome === 'cancelled' && started.cancellationSource === 'stall-watchdog');
         if (!started.succeeded && !interruptedForWake) {
             monitor?.stop();
             await control.close();
@@ -772,7 +773,9 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             throw new Error(`[${name}] ${sessionLabel} startup prompt ${started.outcome}` +
                 `${started.detail ? `: ${started.detail}` : ''}`);
         }
-        if (interruptedForWake)
+        if (started.cancellationSource === 'stall-watchdog')
+            deps.log(`[${name}] ${sessionLabel} startup diagnostic recovery requires operator attention; keeping supervisor alive`);
+        else if (interruptedForWake)
             deps.log(`[${name}] ${sessionLabel} startup prompt cancelled by ${started.cancellationSource}; `
                 + 'keeping temporary supervisor alive');
         sessionStartupComplete = true;

package/dist/session/acp.d.ts

@@ -27,6 +27,12 @@ export declare const CODEX_DISABLE_INHERITED_MCP_ENV = "OURS_FLEET_CODEX_DISABLE
 export declare function promptContentBlocks(text: string, origin?: PromptOrigin): acp.ContentBlock[];
 export declare function runtimeSelector(options: acp.SessionConfigOption[] | null | undefined, category: string): RuntimeSelectorMetadata | undefined;
 export interface AcpSessionOptions {
+    /** Opt-in Fleet watchdog, owned by this ACP session, never a process restart. */
+    stallRecovery?: {
+        timeoutMs?: number;
+        tickMs?: number;
+        cancelWaitMs?: number;
+    };
     name: string;
     /** Harness identity used only for honest optional capability reporting. */
     harness?: string;
@@ -144,6 +150,15 @@ export declare class AcpSession implements AgentSession {
     private terminate;
     /** ACP-authenticated in-flight calls, including independently reserved permissions. */
     private readonly activeToolCalls;
+    private stallWatchdog?;
+    private stallToolHistory?;
+    private stallRecoveryClaimed;
+    private managedTurnCount;
+    private steeringWasUsed;
+    private steeringRequests;
+    private retryNativeTurnId?;
+    private stallTimer?;
+    private stallAttempt?;
     private readonly toolBoundaryWaiters;
     private activeTurn?;
     private constructor();
@@ -275,7 +290,13 @@ export declare class AcpSession implements AgentSession {
     private declaredMcpServers;
     private initialize;
     private captureRuntimeMetadata;
+    private startStallWatchdog;
+    private checkStallWatchdog;
+    private stallObservation;
+    private recoverStall;
+    /** Keep the original queue slot (including startup) until recovery finishes. */
     private runPrompt;
+    private runSinglePrompt;
     private steerPrompt;
     private requestPermission;
     /**
@@ -294,6 +315,8 @@ export declare class AcpSession implements AgentSession {
      * malformed requests on the ordinary fail-closed path.
      */
     private isEffectiveCodexProtectedMcpApproval;
+    /** Pinned codex-acp 1.1.7 structured metadata, never stderr or assistant text. */
+    private recordStallMetadata;
     private recordUpdate;
     /**
      * Codex ACP's phase extension is the only currently supported visibility

package/dist/session/acp.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { Readable, Writable } from 'node:stream';
@@ -7,6 +7,7 @@ import * as acp from '@agentclientprotocol/sdk';
 import { normalizeSessionUpdate } from './conversation-normalizer.js';
 import { ConversationEventStore } from './conversation-store.js';
 import { SessionEvents } from './events.js';
+import { DEFAULT_STALL_TIMEOUT_MS, STALL_RECOVERY_PROMPT, StallWatchdog, StallToolHistory, hasStallRecoveryClaim } from './stall-watchdog.js';
 import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, sessionBackendCapabilities, turnResult, } from './types.js';
 const CANCEL_SETTLE_GRACE_MS = 15_000;
 const CANCEL_TERMINATE_GRACE_MS = 5_000;
@@ -158,6 +159,7 @@ function canonicallyWithin(root, candidates) {
 function conversationSource(origin) {
     switch (origin?.kind) {
         case 'owner-admin-console': return { source: 'owner_admin_console', persistBody: true };
+        case 'stall-watchdog': return { source: 'fleet_monitor', persistBody: false };
         case 'startup': return { source: 'startup', persistBody: true };
         case 'owner': return { source: 'owner_channel', persistBody: false };
         case 'fleet-monitor': return { source: 'fleet_monitor', persistBody: false };
@@ -265,6 +267,15 @@ export class AcpSession {
     terminate;
     /** ACP-authenticated in-flight calls, including independently reserved permissions. */
     activeToolCalls = new Map();
+    stallWatchdog;
+    stallToolHistory;
+    stallRecoveryClaimed = false;
+    managedTurnCount = 0;
+    steeringWasUsed = false;
+    steeringRequests = 0;
+    retryNativeTurnId;
+    stallTimer;
+    stallAttempt;
     toolBoundaryWaiters = new Set();
     activeTurn;
     constructor(options, child, connection) {
@@ -285,6 +296,9 @@ export class AcpSession {
         this.terminated.catch(() => undefined);
         child.stderr.on('data', chunk => options.log(`[${options.name}] acp: ${String(chunk).trimEnd()}`));
         child.once('exit', (code, signal) => {
+            if (this.stallTimer)
+                clearInterval(this.stallTimer);
+            this.stallTimer = undefined;
             if (this.cancelForceKill)
                 clearTimeout(this.cancelForceKill);
             this.cancelForceKill = undefined;
@@ -341,7 +355,8 @@ export class AcpSession {
         let instance;
         const app = acp.client({ name: 'ours-fleet' })
             .onNotification(acp.methods.client.session.update, ({ params }) => {
-            instance?.recordUpdate(params.update);
+            if (instance && (!instance.sessionId || params.sessionId === instance.sessionId))
+                instance.recordUpdate(params.update);
         })
             .onRequest(acp.methods.client.session.requestPermission, ({ params }) => {
             if (!instance)
@@ -353,6 +368,7 @@ export class AcpSession {
         instance = new AcpSession(options, child, connection);
         try {
             await instance.initialize();
+            instance.startStallWatchdog();
             instance.recoverOpenPrompts();
             return instance;
         }
@@ -471,10 +487,14 @@ export class AcpSession {
     reserveTool(toolCallId) {
         if (toolCallId)
             this.toolCall(toolCallId).lifecycle = true;
+        else if (this.activeTurn)
+            this.activeTurn.boundaryUnknown = true;
     }
     reservePermission(toolCallId, permissionId) {
         if (toolCallId)
             this.toolCall(toolCallId).permissions.set(permissionId, 'pending');
+        else if (this.activeTurn)
+            this.activeTurn.boundaryUnknown = true;
     }
     allowPermission(toolCallId, permissionId) {
         if (!toolCallId)
@@ -559,6 +579,8 @@ export class AcpSession {
      * steering response from becoming a tight replay loop.
      */
     async steerOrQueueWake(text, options) {
+        if (this.stallRecoveryClaimed)
+            return this.submitPrompt(text, { ...options, interrupt: false, steer: false });
         const steered = await this.steerPrompt(text);
         if (steered.accepted || steered.detail !== 'ACP steering failed'
             || this.closing || !this.isAlive())
@@ -622,6 +644,8 @@ export class AcpSession {
      * for it is what turned a busy agent into a timeout and then into "dead".
      */
     async queuePrompt(text, options = {}) {
+        if (this.stallRecoveryClaimed && options.origin?.kind === 'fleet-monitor')
+            options = { ...options, interrupt: false, steer: false };
         if (this.cancelRecoveryReason)
             throw new SessionControlError('control-unavailable', 'ACP adapter restart is in progress after the cancellation deadline', ACP_CANCEL_DEADLINE_EXCEEDED);
         if (this.closing || !this.sessionId || !this.isAlive())
@@ -781,6 +805,8 @@ export class AcpSession {
         }
     }
     async cancelActive(source) {
+        if (this.stallAttempt && source !== 'stall-watchdog' && source !== 'fleet-monitor')
+            this.stallAttempt.superseded = true;
         if (!this.sessionId)
             return;
         const active = this.activeTurn;
@@ -989,6 +1015,11 @@ export class AcpSession {
     }
     async close() {
         this.closing = true;
+        if (this.stallTimer)
+            clearInterval(this.stallTimer);
+        this.stallTimer = undefined;
+        if (this.stallAttempt)
+            this.stallAttempt.superseded = true;
         if (this.cancelEscalation)
             clearTimeout(this.cancelEscalation);
         this.cancelEscalation = undefined;
@@ -1130,13 +1161,158 @@ export class AcpSession {
         this.runtimeModel = runtimeSelector(options, 'model');
         this.reasoningEffort = runtimeSelector(options, 'thought_level') ?? reasoningFromModelId(modelId);
     }
+    startStallWatchdog() {
+        if (!this.options.stallRecovery)
+            return;
+        const timeoutMs = this.options.stallRecovery.timeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+        this.stallRecoveryClaimed = hasStallRecoveryClaim(this.options.stateDir, this.sessionId);
+        this.stallToolHistory = new StallToolHistory(this.options.stateDir, this.sessionId, this.options.mode === 'resume');
+        this.stallWatchdog = new StallWatchdog({
+            stateDir: this.options.stateDir, timeoutMs, previouslyClaimed: this.stallRecoveryClaimed, now: () => Date.now(),
+            observe: () => this.stallObservation(),
+            recover: (observed, report) => this.recoverStall(observed, report),
+            diagnostic: diagnostic => {
+                if (['interrupt_requested', 'blocked_previous_attempt', 'blocked_persistence'].includes(diagnostic.status))
+                    this.stallRecoveryClaimed = true;
+                this.events.emit('stall_recovery', { status: diagnostic.status, stallDiagnostic: diagnostic });
+                this.options.log(`[${this.options.name}] ACP stall recovery: ${diagnostic.status}; `
+                    + 'inspect structured session events before continuing; never replay uncertain side effects');
+            },
+        });
+        this.stallTimer = setInterval(() => this.checkStallWatchdog(), this.options.stallRecovery.tickMs ?? Math.min(10_000, timeoutMs));
+        this.stallTimer.unref?.();
+    }
+    checkStallWatchdog() {
+        void this.stallWatchdog?.tick();
+        const attempt = this.stallAttempt;
+        if (attempt?.recoveryStartedAt === undefined || attempt.blocked || attempt.superseded)
+            return;
+        const observed = this.stallObservation();
+        if (!observed?.safe || observed.turnId !== attempt.recoveryId)
+            return;
+        const last = observed.lastProgressAt || attempt.recoveryStartedAt;
+        const timeoutMs = this.options.stallRecovery?.timeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+        if (Date.now() - last >= timeoutMs * 2) {
+            attempt.blocked = true;
+            try {
+                attempt.report('blocked_restall');
+            }
+            catch { /* durable claim already prevents retry */ }
+        }
+    }
+    stallObservation() {
+        const active = this.activeTurn;
+        if (!active || !this.sessionId)
+            return undefined;
+        return {
+            sessionId: this.sessionId, generation: this.sessionGeneration, turnId: active.id,
+            startedAt: active.startedAt, lastProgressAt: active.lastProgressAt, progressCount: active.progressCount,
+            transportFailures: active.transportFailures,
+            boundaryEvidenceAvailable: this.stallToolHistory?.available() !== false,
+            safe: this.isAlive() && !this.closing && this.readiness === 'running'
+                && !active.cancellationSource && !active.boundaryUnknown && !this.steeringOccupied
+                && this.steeringRequests === 0 && this.stallToolHistory?.available() !== false
+                && this.activeToolCalls.size === 0 && this.pendingPermissions.size === 0,
+        };
+    }
+    async recoverStall(observed, report) {
+        const current = this.stallObservation();
+        if (!current?.safe || current.turnId !== observed.turnId
+            || current.lastProgressAt !== observed.lastProgressAt || current.progressCount !== observed.progressCount) {
+            report('superseded');
+            return;
+        }
+        const active = this.activeTurn;
+        let resolveReady;
+        const ready = new Promise(resolve => { resolveReady = resolve; });
+        const attempt = this.stallAttempt = {
+            turnId: active.id, recoveryId: randomUUID(), ready, superseded: false,
+            report, resumed: false, blocked: false,
+        };
+        active.cancellationSource = 'stall-watchdog';
+        // This intentionally does not use cancelActive: automatic recovery may
+        // never enter its SIGTERM/SIGKILL escalation or settle a permission.
+        let timer;
+        try {
+            const completed = await Promise.race([
+                (async () => {
+                    await this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId });
+                    await active.settled;
+                    return true;
+                })(),
+                new Promise(resolve => {
+                    timer = setTimeout(() => resolve(false), this.options.stallRecovery?.cancelWaitMs ?? CANCEL_SETTLE_GRACE_MS);
+                    timer.unref?.();
+                }),
+            ]);
+            if (!completed || attempt.superseded || this.closing || !this.isAlive()) {
+                attempt.blocked = true;
+                report(attempt.superseded || this.closing ? 'superseded' : 'blocked_cancel');
+                resolveReady(false);
+            }
+            else
+                resolveReady(true);
+        }
+        catch {
+            attempt.blocked = true;
+            try {
+                report('blocked_cancel');
+            }
+            finally {
+                resolveReady(false);
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Keep the original queue slot (including startup) until recovery finishes. */
     async runPrompt(text, turnId = randomUUID(), origin) {
+        const result = await this.runSinglePrompt(text, turnId, origin);
+        const attempt = this.stallAttempt;
+        if (!attempt || attempt.turnId !== turnId)
+            return result;
+        const ready = await attempt.ready;
+        if (attempt.superseded || this.closing)
+            return result;
+        if (!ready || result.outcome !== 'cancelled' || result.cancellationSource !== 'stall-watchdog') {
+            // An RPC error/refusal/ambiguous terminal answer to cancellation is not
+            // permission to replay work or to fail startup and restart the process.
+            if (!attempt.blocked) {
+                attempt.blocked = true;
+                try {
+                    attempt.report('blocked_cancel');
+                }
+                catch { /* claim remains durable */ }
+            }
+            return turnResult(true, 'cancelled', 'diagnostic cancellation requires operator attention', undefined, 'stall-watchdog');
+        }
+        try {
+            attempt.report('recovery_started');
+            attempt.recoveryStartedAt = Date.now();
+            const recoveryOrigin = origin?.kind === 'scheduled-loop'
+                ? origin : { kind: 'stall-watchdog' };
+            this.admitToLedger(attempt.recoveryId, STALL_RECOVERY_PROMPT, 0, { origin: recoveryOrigin });
+            const recovered = await this.runSinglePrompt(STALL_RECOVERY_PROMPT, attempt.recoveryId, recoveryOrigin);
+            attempt.report(attempt.superseded ? 'superseded'
+                : recovered.succeeded && attempt.resumed ? 'recovery_completed' : 'blocked_recovery');
+            // A failed diagnostic turn must not make startup tear down the session.
+            return recovered.succeeded && attempt.resumed ? recovered : turnResult(true, 'cancelled', 'diagnostic recovery requires operator attention', undefined, 'stall-watchdog');
+        }
+        catch {
+            return turnResult(true, 'cancelled', 'diagnostic recovery requires operator attention', undefined, 'stall-watchdog');
+        }
+    }
+    async runSinglePrompt(text, turnId = randomUUID(), origin) {
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
         this.readiness = 'running';
+        this.managedTurnCount++;
+        this.retryNativeTurnId = undefined;
         let settle;
         const settled = new Promise(resolve => { settle = resolve; });
-        this.activeTurn = { id: turnId, output: '', origin, settled, settle };
+        this.activeTurn = { toolEvidence: new Map(), startedAt: Date.now(), toolIds: new Set(), lastProgressAt: 0, progressCount: 0, transportFailures: 0, boundaryUnknown: false, id: turnId, output: '', origin, settled, settle };
         this.events.emit('state', { turnId, status: 'running', origin });
         this.conversation.appendSafe({
             kind: 'prompt.started', sessionGeneration: this.sessionGeneration,
@@ -1180,7 +1356,8 @@ export class AcpSession {
             this.lastError = origin?.kind === 'scheduled-loop' ? 'scheduled-loop turn failed' : detail;
             this.readiness = this.isAlive() ? 'idle' : 'failed';
             this.events.emit('error', {
-                turnId, origin,
+                turnId, origin: this.activeTurn?.cancellationSource === 'stall-watchdog'
+                    ? { kind: 'stall-watchdog' } : origin,
                 text: origin?.kind === 'scheduled-loop' ? 'scheduled-loop turn failed' : this.lastError,
             });
             if (this.isAlive())
@@ -1208,8 +1385,10 @@ export class AcpSession {
         }
     }
     async steerPrompt(text) {
+        this.steeringWasUsed = true;
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
+        this.steeringRequests++;
         try {
             const response = await Promise.race([
                 this.connection.agent.request('_session/steering', {
@@ -1234,6 +1413,9 @@ export class AcpSession {
             this.events.emit('error', { text: detail });
             return turnResult(false, 'failed', detail);
         }
+        finally {
+            this.steeringRequests--;
+        }
     }
     requestPermission(params) {
         // `kinds` is a PRIORITY order. Scanning the agent's option array instead
@@ -1409,6 +1591,48 @@ export class AcpSession {
             && params.options.some(option => option.optionId === 'allow_once' && option.kind === 'allow_once')
             && params.options.some(option => option.optionId === 'decline' && option.kind === 'reject_once');
     }
+    /** Pinned codex-acp 1.1.7 structured metadata, never stderr or assistant text. */
+    recordStallMetadata(update) {
+        if (this.options.permissionMetadataSource !== 'codex-acp'
+            || update.sessionUpdate !== 'session_info_update' || !this.activeTurn)
+            return;
+        const meta = update._meta?.codex;
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+            return;
+        const codex = meta;
+        const status = codex.threadStatus;
+        if (Object.prototype.hasOwnProperty.call(codex, 'threadStatus')) {
+            const value = status && typeof status === 'object' && !Array.isArray(status)
+                ? status : {};
+            // Unknown or modal thread status is a permanent conservative fence for
+            // this turn. A later delayed idle/active status must not clear it.
+            if (value.type !== 'active' || !Array.isArray(value.activeFlags)
+                || value.activeFlags.length > 0)
+                this.activeTurn.boundaryUnknown = true;
+        }
+        const error = codex.error;
+        if (!error || typeof error !== 'object' || Array.isArray(error))
+            return;
+        const value = error;
+        const info = value.codexErrorInfo;
+        if (value.willRetry !== true || typeof value.turnId !== 'string' || !value.turnId
+            || !info || typeof info !== 'object' || Array.isArray(info))
+            return;
+        if (!['responseStreamConnectionFailed', 'responseStreamDisconnected']
+            .some(key => Object.prototype.hasOwnProperty.call(info, key)))
+            return;
+        // ACP 1.1.7 does not expose a native-turn-to-prompt mapping. Only the first
+        // fresh managed turn with no steering can be correlated without guessing;
+        // later/resumed turns retain the conservative generic no-progress path.
+        if (this.options.mode !== 'fresh' || this.managedTurnCount !== 1 || this.steeringWasUsed)
+            return;
+        if (this.retryNativeTurnId && this.retryNativeTurnId !== value.turnId) {
+            this.activeTurn.boundaryUnknown = true;
+            return;
+        }
+        this.retryNativeTurnId = value.turnId;
+        this.activeTurn.transportFailures++;
+    }
     recordUpdate(update) {
         // Replayed history is not current activity: `session/load` would otherwise
         // make a cold session look like it had just been working. The same reason
@@ -1418,6 +1642,53 @@ export class AcpSession {
             this.lastUpdateAt = new Date().toISOString();
             this.refreshSteeringOccupancy();
         }
+        if (!this.replaying && this.activeTurn) {
+            this.recordStallMetadata(update);
+            const active = this.activeTurn;
+            const kind = update.sessionUpdate;
+            if (this.options.stallRecovery && (kind === 'tool_call' || kind === 'tool_call_update')) {
+                if (!update.toolCallId || active.toolIds.size >= 4096)
+                    active.boundaryUnknown = true;
+                else
+                    active.toolIds.add(update.toolCallId);
+                if (this.stallToolHistory?.observe(update.toolCallId, active.id) === false)
+                    active.boundaryUnknown = true;
+            }
+            let meaningful = ((kind === 'agent_message_chunk' || kind === 'agent_thought_chunk')
+                && (update.content.type !== 'text' || update.content.text.length > 0))
+                || kind === 'tool_call' || kind === 'tool_call_update' || kind === 'plan';
+            if (this.options.stallRecovery && (kind === 'tool_call' || kind === 'tool_call_update' || kind === 'plan')) {
+                const fingerprint = createHash('sha256').update(JSON.stringify(update)).digest('hex');
+                if (kind === 'plan') {
+                    meaningful = fingerprint !== active.planEvidence;
+                    active.planEvidence = fingerprint;
+                }
+                else if (active.toolEvidence.size < 4096 || active.toolEvidence.has(update.toolCallId)) {
+                    meaningful = fingerprint !== active.toolEvidence.get(update.toolCallId);
+                    active.toolEvidence.set(update.toolCallId, fingerprint);
+                }
+            }
+            if (this.options.stallRecovery && ![
+                'agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update', 'plan',
+                'available_commands_update', 'current_mode_update', 'config_option_update', 'session_info_update', 'usage_update',
+            ].includes(kind))
+                active.boundaryUnknown = true;
+            if (meaningful) {
+                active.lastProgressAt = Date.now();
+                active.progressCount++;
+                active.transportFailures = 0;
+                const attempt = this.stallAttempt;
+                if (attempt?.recoveryId === active.id && !attempt.resumed) {
+                    attempt.resumed = true;
+                    try {
+                        attempt.report('progress_resumed');
+                    }
+                    catch {
+                        attempt.blocked = true;
+                    }
+                }
+            }
+        }
         const scheduled = this.activeTurn?.origin?.kind === 'scheduled-loop';
         const messagePhase = update.sessionUpdate === 'agent_message_chunk'
             ? this.codexMessagePhase(update) : undefined;
@@ -1475,6 +1746,9 @@ export class AcpSession {
                     this.releaseTool(update.toolCallId);
                 else if (update.status !== undefined)
                     this.reserveTool(update.toolCallId);
+                else if (this.options.stallRecovery && this.activeTurn
+                    && !this.activeToolCalls.has(update.toolCallId))
+                    this.activeTurn.boundaryUnknown = true;
                 break;
             default:
                 break;

package/dist/session/stall-watchdog.d.ts

@@ -0,0 +1,60 @@
+export declare const DEFAULT_STALL_TIMEOUT_MS: number;
+export declare const STALL_RECOVERY_PROMPT: string;
+export type StallStatus = 'interrupt_requested' | 'recovery_started' | 'progress_resumed' | 'recovery_completed' | 'blocked_cancel' | 'blocked_recovery' | 'blocked_restall' | 'blocked_persistence' | 'blocked_previous_attempt' | 'blocked_evidence' | 'superseded';
+export interface StallDiagnostic {
+    version: 1;
+    kind: 'stall_recovery';
+    eventId: string;
+    session: string;
+    turn: string;
+    status: StallStatus;
+    evidence: 'adapter_transport' | 'no_progress';
+    idleMs: number;
+}
+export interface StallObservation {
+    sessionId: string;
+    generation: string;
+    turnId: string;
+    startedAt: number;
+    lastProgressAt: number;
+    progressCount: number;
+    transportFailures: number;
+    safe: boolean;
+    boundaryEvidenceAvailable?: boolean;
+}
+/** Presence, including an incomplete claim, restores conservative mail policy. */
+export declare function hasStallRecoveryClaim(stateDir: string, sessionId: string): boolean;
+/** ACP has no turn IDs on tool updates. Reuse across turns is ambiguous. */
+export declare class StallToolHistory {
+    private readonly turns;
+    private healthy;
+    private readonly directory;
+    private readonly path;
+    private readonly session;
+    constructor(stateDir: string, sessionId: string, resume: boolean);
+    available(): boolean;
+    /** Record before relying on a tool event. False means cancellation is unsafe. */
+    observe(toolId: string, turnId: string): boolean;
+    private persist;
+}
+/**
+ * One durable attempt per ACP session, deliberately stricter than one per turn.
+ * A restarted supervisor never guesses whether cancellation or recovery ran.
+ * Claim files are never reclaimed automatically, including malformed/empty ones.
+ */
+export declare class StallWatchdog {
+    private readonly options;
+    private checking;
+    private disabled;
+    private unavailableTurn?;
+    constructor(options: {
+        stateDir: string;
+        timeoutMs: number;
+        previouslyClaimed?: boolean;
+        now(): number;
+        observe(): StallObservation | undefined;
+        recover(observed: StallObservation, report: (status: StallStatus) => void): Promise<void>;
+        diagnostic(event: StallDiagnostic): void;
+    });
+    tick(): Promise<void>;
+}

package/dist/session/stall-watchdog.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60_000;
+export const STALL_RECOVERY_PROMPT = 'This is a diagnostic interruption. The previous turn showed no progress. '
+    + 'Inspect recorded terminal events and re-check completed actions before continuing. '
+    + 'Never assume an issued side effect failed: do not replay ambiguous or already-completed mutations. '
+    + 'Continue the previous task if safe; otherwise report an actionable blocker.';
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/** Presence, including an incomplete claim, restores conservative mail policy. */
+export function hasStallRecoveryClaim(stateDir, sessionId) {
+    try {
+        lstatSync(join(stateDir, '.stall-recovery', `${digest(sessionId)}.claim`));
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ENOENT';
+    }
+}
+/** ACP has no turn IDs on tool updates. Reuse across turns is ambiguous. */
+export class StallToolHistory {
+    turns = new Map();
+    healthy = true;
+    directory;
+    path;
+    session;
+    constructor(stateDir, sessionId, resume) {
+        this.session = digest(sessionId);
+        this.directory = join(stateDir, '.stall-recovery');
+        this.path = join(this.directory, `${this.session}.tools.json`);
+        try {
+            const stored = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (stored.version !== 1 || stored.session !== this.session || !Array.isArray(stored.tools)
+                || stored.tools.length > 4096 || !stored.tools.every((id) => typeof id === 'string' && /^[a-f0-9]{64}$/.test(id)))
+                throw new Error('invalid history');
+            for (const id of stored.tools)
+                this.turns.set(id, 'previous-generation');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT' || resume)
+                this.healthy = false;
+            else {
+                try {
+                    mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+                    this.persist();
+                    const fd = openSync(stateDir, 'r');
+                    try {
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                catch {
+                    this.healthy = false;
+                }
+            }
+        }
+    }
+    available() { return this.healthy; }
+    /** Record before relying on a tool event. False means cancellation is unsafe. */
+    observe(toolId, turnId) {
+        if (!this.healthy || !toolId)
+            return false;
+        const id = digest(toolId);
+        const previous = this.turns.get(id);
+        if (previous !== undefined)
+            return previous === turnId;
+        if (this.turns.size >= 4096) {
+            this.healthy = false;
+            return false;
+        }
+        this.turns.set(id, turnId);
+        try {
+            this.persist();
+        }
+        catch {
+            this.healthy = false;
+        }
+        return this.healthy;
+    }
+    persist() {
+        replaceFileAtomically(this.path, JSON.stringify({ version: 1, session: this.session,
+            tools: [...this.turns.keys()] }) + '\n');
+        const fd = openSync(this.directory, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}
+/**
+ * One durable attempt per ACP session, deliberately stricter than one per turn.
+ * A restarted supervisor never guesses whether cancellation or recovery ran.
+ * Claim files are never reclaimed automatically, including malformed/empty ones.
+ */
+export class StallWatchdog {
+    options;
+    checking = false;
+    disabled = false;
+    unavailableTurn;
+    constructor(options) {
+        this.options = options;
+    }
+    async tick() {
+        if (this.checking || this.disabled)
+            return;
+        const observed = this.options.observe();
+        if (!observed)
+            return;
+        const missingBoundary = observed.boundaryEvidenceAvailable === false;
+        if (!observed.safe && !missingBoundary && !this.options.previouslyClaimed)
+            return;
+        const missingEvidence = observed.progressCount === 0 || missingBoundary;
+        // Turn age can only produce an informational blocker, never cancellation.
+        const idleMs = this.options.now() - (observed.progressCount === 0 ? observed.startedAt : observed.lastProgressAt);
+        // Generic silence needs two full windows. Authenticated repeated transport
+        // failures strengthen evidence, but never bypass protected-operation checks.
+        const threshold = this.options.timeoutMs * (!missingEvidence && observed.transportFailures >= 2 ? 1 : 2);
+        if (!Number.isFinite(idleMs) || (idleMs < threshold && !this.options.previouslyClaimed))
+            return;
+        this.checking = true;
+        const session = digest(observed.sessionId);
+        const turn = digest(observed.generation + '\0' + observed.turnId);
+        const directory = join(this.options.stateDir, '.stall-recovery');
+        const report = (status) => {
+            const event = {
+                version: 1, kind: 'stall_recovery', eventId: `${turn}:${status}`,
+                session, turn, status, idleMs: Math.floor(idleMs),
+                evidence: observed.transportFailures >= 2 ? 'adapter_transport' : 'no_progress',
+            };
+            const fd = openSync(join(directory, 'audit.jsonl'), 'a', 0o600);
+            try {
+                writeFileSync(fd, JSON.stringify(event) + '\n');
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            this.options.diagnostic(event);
+        };
+        try {
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const parentFd = openSync(this.options.stateDir, 'r');
+            try {
+                fsyncSync(parentFd);
+            }
+            finally {
+                closeSync(parentFd);
+            }
+            if (this.options.previouslyClaimed) {
+                this.disabled = true;
+                report('blocked_previous_attempt');
+                return;
+            }
+            if (missingEvidence) {
+                if (this.unavailableTurn !== turn) {
+                    this.unavailableTurn = turn;
+                    report('blocked_evidence');
+                }
+                return;
+            }
+            let fd;
+            try {
+                fd = openSync(join(directory, `${session}.claim`), 'wx', 0o600);
+            }
+            catch (error) {
+                this.disabled = true;
+                if (error.code === 'EEXIST') {
+                    report('blocked_previous_attempt');
+                    return;
+                }
+                throw error;
+            }
+            // Even a crash before this write leaves a permanent conservative fence.
+            try {
+                writeFileSync(fd, JSON.stringify({ version: 1, session, turn }) + '\n');
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            const dirFd = openSync(directory, 'r');
+            try {
+                fsyncSync(dirFd);
+            }
+            finally {
+                closeSync(dirFd);
+            }
+            this.disabled = true;
+            report('interrupt_requested');
+            // No await between the durable claim and the adapter's final atomic
+            // observation check. Recovery itself must re-check before session/cancel.
+            await this.options.recover(observed, report);
+        }
+        catch {
+            this.disabled = true;
+            // Never include an exception string: it may contain paths or wire data.
+            this.options.diagnostic({ version: 1, kind: 'stall_recovery',
+                eventId: `${turn}:blocked_persistence`, session, turn,
+                status: 'blocked_persistence', evidence: 'no_progress', idleMs: Math.floor(idleMs) });
+        }
+        finally {
+            this.checking = false;
+        }
+    }
+}

package/dist/session/types.d.ts

@@ -13,9 +13,11 @@ import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPr
  */
 export type SessionReadiness = 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed';
 export type TurnOutcome = 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
-export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown';
+export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown' | 'stall-watchdog';
 export type PromptOrigin = {
     kind: 'startup';
+} | {
+    kind: 'stall-watchdog';
 } | {
     kind: 'local-console';
 } | {
@@ -221,7 +223,7 @@ export interface AgentSessionCapabilities {
 }
 /** Conservative static capabilities used before a live session is reachable. */
 export declare function sessionBackendCapabilities(backend: SessionBackendId, harness?: string): AgentSessionCapabilities;
-export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'monitor_delivery' | 'turn_stop' | 'error';
+export type SessionEventKind = 'state' | 'agent_text' | 'thought' | 'tool_call' | 'tool_update' | 'permission' | 'stall_recovery' | 'monitor_delivery' | 'turn_stop' | 'error';
 /** What a settled permission request resolved to. */
 export type PermissionDecision = 'allowed' | 'denied' | 'cancelled';
 export interface SessionEvent {
@@ -263,6 +265,7 @@ export interface SessionEvent {
     /** The option actually selected, when one was. */
     optionId?: string;
     /** Body-free evidence for monitor safe-boundary delivery. */
+    stallDiagnostic?: import('./stall-watchdog.js').StallDiagnostic;
     monitorPolicy?: 'after_tool';
     activeToolCount?: number;
     waitedMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",