@ours.network/fleet 0.14.1 → 0.15.1

package/README.md

@@ -68,6 +68,7 @@ The state dir contract:
 | `.identity`, `.cwd`, `.session-id`, `.booted`, `.exit-status`, `.config-path` | supervisor | dot-marker state — session resume and boot bookkeeping |
 | `.monitor-state.json`, `.monitor-status` | supervisor monitor | atomic body-free cursor/pending state and health |
 | `.owner-channel-state.json` | owner-channel bridge | bounded wire-ID dedupe only; never message/reply plaintext |
+| `.owner-channel-binder.lock/`, `.owner-channel-binder.json` | owner-channel supervisor | mode-0600 role/identity + PID/start-marker ownership and release metadata; never mail plaintext or credentials |
 | `.session-events.jsonl`, `.control.sock`, `.control-token` | ACP backend | bounded typed console projection and private attachment control |
 
 ## Prerequisites
@@ -202,6 +203,16 @@ authenticated identity existence check and reports verified, missing, or
 unknown evidence; a newly launched harness follows its generated first-boot
 instructions to choose or create and bind the identity. The console never
 claims that the host created an identity and never deletes one.
+
+For a temporary role, those first-boot instructions preserve and bind an
+existing identity when one is present. If the assigned identity is missing,
+the role capability-detects the ours MCP `create_temporary_identity` tool and
+uses it when available, so the newly created identity is owned and cleaned up
+by that connector session lifecycle. Older ours servers remain compatible via
+`create_identity`. A collision or creation error stops for operator review;
+fleet never force-adopts or deletes identity state. Permanent roles continue to
+use normal `create_identity` bootstrap behavior.
+
 `node-pty` is optional: if its native module cannot load, ACP and all
 non-terminal features remain available and tmux Terminal is disabled with a
 diagnostic.
@@ -573,6 +584,22 @@ channel identity. Add it to the control plane just like another contact, then
 message it directly.
 
 The running supervisor remains the only process which binds that identity.
+Rapid supervised restart uses a role-scoped single-binder lease. The old
+supervisor closes its MCP proxy and authenticated control socket before
+releasing the lease; the replacement waits a bounded five seconds and retries a
+daemon bind only when the lease proves that holder was the same role and channel
+identity. A foreign, live, or unverifiable holder remains fail-closed and is
+never evicted with `force=true`.
+
+If the matching predecessor does not release within that bound, the replacement
+asks the predecessor's still-authenticated control socket to emit one fixed
+recovery notice. The predecessor uses only its existing latest-owner route (or
+the sole configured owner), deduplicates the notice durably by digest, and stores
+no notice plaintext. When no unambiguous authenticated owner route exists, no
+recipient is guessed: the failure remains in the web console and role logs. The
+remote recovery action is `/restart`; repeated failures should be inspected with
+`ours-fleet logs <Role>` or the web console.
+
 Operators manage it, and an active agent turn emits bounded updates, through the
 role's authenticated Unix control socket:
 

package/dist/briefing.d.ts

@@ -12,6 +12,8 @@ export interface BriefingOpts {
      * knowledge must not claim one.
      */
     identityGuarantee?: 'verified' | 'created' | 'unverified';
+    /** Temporary spawn whose newly-created identity should share the session lifecycle. */
+    temporaryIdentity?: boolean;
 }
 /** Render a role's briefing.md: narrative (or curated body) + mechanical boot steps. */
 export declare function generateBriefing(role: ResolvedRole, v: BriefingVocab, opts: BriefingOpts): string;

package/dist/briefing.js

@@ -1,12 +1,24 @@
 import { userInfo } from 'node:os';
 import { oversightTaxonomyLines } from './session/control.js';
+function temporaryIdentityFallback(id, v) {
+    return [
+        `     First inspect the available/deferred ours MCP tools for **${v.temporaryCreateTool}**.`,
+        `     If exposed, call **${v.temporaryCreateTool}** with name "${id}". It binds`,
+        '     automatically and the ours connector owns its cleanup when this session lifecycle ends.',
+        `     If that tool is absent (an older server), fall back to **${v.createTool}** with`,
+        `     name "${id}" so startup remains compatible. If either creation call reports a`,
+        '     collision or any other error, STOP and report it; do not force-bind, retry under a',
+        '     different name, remove an identity, or delete identity state.',
+    ];
+}
 /** Render a role's briefing.md: narrative (or curated body) + mechanical boot steps. */
 export function generateBriefing(role, v, opts) {
     const L = [];
     const id = role.identity;
     const hostUser = userInfo().username;
     L.push(`# ${role.name} — Role Briefing`, '');
-    L.push(`You are **${role.name}** (ours identity: **${id}**), a persistent agent on this`);
+    const lifetime = opts.temporaryIdentity ? 'temporary' : 'persistent';
+    L.push(`You are **${role.name}** (ours identity: **${id}**), a ${lifetime} agent on this`);
     L.push(`host, running as the \`${hostUser}\` user.`);
     if (opts.briefingBody) {
         L.push('', opts.briefingBody.trim());
@@ -27,7 +39,24 @@ export function generateBriefing(role, v, opts) {
     // "predefined" identity that nobody checked is how an agent ends up improvising
     // its own infrastructure on first boot.
     const guarantee = opts.identityGuarantee ?? 'unverified';
-    if (guarantee === 'unverified') {
+    if (opts.temporaryIdentity) {
+        L.push(`2. BIND the exact ours identity assigned to this role: call **${v.bindTool}** with`);
+        L.push(`   name "${id}" without force (search the deferred tool registry first if needed).`);
+        L.push('   If another live session owns it, STOP and report the collision; do not evict it.');
+        L.push('   - If binding succeeds, it is a pre-existing identity: preserve it as user-owned.');
+        L.push('     Never close, remove, replace, or otherwise convert it to a temporary identity.');
+        if (guarantee === 'unverified') {
+            L.push('   - This identity was NOT verified when your role was created. If and only if binding');
+            L.push('     reports that no such identity exists:');
+        }
+        else {
+            L.push(`   - It was ${guarantee === 'created' ? 'created' : 'verified to exist'} when your role`);
+            L.push('     was created. If it unexpectedly reports that no such identity exists, report the');
+            L.push('     discrepancy, then use this compatibility path:');
+        }
+        L.push(...temporaryIdentityFallback(id, v));
+    }
+    else if (guarantee === 'unverified') {
         L.push(`2. BIND your ours identity: call the **${v.bindTool}** tool with`);
         L.push(`   name "${id}" force=true (search the deferred tool registry first if needed).`);
         L.push(`   - This identity was NOT verified when your role was created, so it may not exist.`);
@@ -137,7 +166,17 @@ export function generateBriefing(role, v, opts) {
     L.push('on messages, timers, or prompts — and follow it for recurring or scheduled work. It may');
     L.push('change between wakes without a restart; treat the file, not your memory of it, as current.');
     L.push('', '## On restart (you run under a supervised launcher)');
-    L.push(`On restart, WITHOUT asking: re-bind (**${v.bindTool}** name "${id}" force=true), then`);
+    if (opts.temporaryIdentity) {
+        L.push(`On restart, WITHOUT asking: try to re-bind (**${v.bindTool}** name "${id}", no force).`);
+        L.push('If it no longer exists, that is expected when the previous session-owned temporary');
+        L.push('identity was cleaned up. Re-run the same capability check from step 2: use');
+        L.push(`**${v.temporaryCreateTool}** with name "${id}" when exposed, otherwise fall back to`);
+        L.push(`**${v.createTool}** for an older server. On collision or any other creation error, STOP`);
+        L.push('and report it without deleting or force-adopting anything. Then');
+    }
+    else {
+        L.push(`On restart, WITHOUT asking: re-bind (**${v.bindTool}** name "${id}" force=true), then`);
+    }
     L.push(`${wakeNote} Then continue from your WORKLOG.`);
     L.push('Do not blindly re-run whatever may have crashed you.');
     L.push('', '## House rules');

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. A role selects\na harness independently from its session backend:\n\n- harness: `claude-code` or `codex`\n- session: `tmux` (default) or `acp`\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]\n```\n\nDefault configuration is `~/fleet.yaml` plus sorted `~/fleet.d/*.yaml` role\ndrop-ins. An explicit `-c FILE` replaces `~/fleet.yaml`; fleet.d still adds\nroles. Validate with `config` and `doctor` before starting or restarting.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init\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 send Name --key Enter        # tmux only\nours-fleet rm Name\nours-fleet watchdog-report <name> [run-id] [--list] [--json]\nours-fleet watchdog-run <name>\n```\n\n`peek`, `attach`, and text `send` work with tmux and ACP. ACP attachment\nalso accepts `/permit <permission-id> <option-id>`, `/interrupt`, and\n`/detach`. Raw `--key` input is tmux-only.\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 \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and legacy `--monitor` (consent for the native Codex monitor,\nnot the `monitor.mode` wake-owner selector). Run `ours-fleet help spawn` for\nexact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      mode: fleet                        # fleet supervisor | native harness monitor\n      interrupt: false                    # true cancels active work before every configured wake\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\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    harness: claude-code            # default: defaults.harness\n    model: claude-fable-5           # default: same resolution rule roles use (resolveRoleModel)\n    session: acp                    # default: defaults.session\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    isolation:                      # optional; omitted means no OS sandbox, like an ordinary role\n      backend: bubblewrap           # when present, the ordinary role isolation schema applies\n      network: broker\n      fs: { read: [/opt/watch-data] }\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`), not in `~/fleet.d/*.yaml` drop-ins.\nWatchdogs are not isolated by default. An explicit watchdog `isolation:` block\nuses the same policy schema as a role and is applied unchanged; declare every\nextra filesystem access required by a custom prompt there.\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\nRole values override defaults. `${name}` substitutes entries from `vars`.\nOther role fields include `max_tokens`, `autocompact_pct`, and `isolation`.\nUse README.md for the complete isolation policy and resource-cap schema.\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|allow|deny`: whether actions may request or receive approval\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what ACP does when no console can answer a request\n\nThe backend translates this common intent. Harness-native settings in\n`harness_options` take precedence where supplied. Do not choose\n`allow`/`unrestricted`, Codex `never`/`danger-full-access`, or Claude\n`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: `approval: allow` maps to Claude's `bypassPermissions`,\nwhich genuinely permits 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` is elevated: `ask` stays on Claude's default\nmode and `deny` maps to `plan`. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\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`, and\n`mem_palace_midsession_autosave`.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `sandbox`\n(read-only, workspace-write, danger-full-access), `approval` or\n`permission_mode` (untrusted, on-request, never), `profile`, `search`,\n`config`, `add_dirs`, and `monitor`.\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.\nThe maintained Claude adapter requires Node 22; tmux and Codex ACP continue to\nwork on the ours-fleet core minimum of Node 20.\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`; tmux uses verified console injection.\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. The policy is content-blind because the supervisor cannot\ninspect encrypted message bodies. Message bodies are released only when the\nrole calls the 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\nAn ACP role may declare a separate, existing ours identity which fleet \u2014 never\nthe agent \u2014 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  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    allowed_mime: [application/pdf, text/plain, image/png, audio/ogg]\n```\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.\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, fleet injects a request-specific outbox path into the owner\nprompt. The agent copies completed artifacts there; fleet sends every regular\nfile from the channel identity with the same source wire ID and removes the\ntemporary outbox only after successful delivery. The agent never chooses an owner\nrecipient or calls ours `send_file` for an owner-channel response.\nOwner messages whose trimmed text starts with `/` are deterministic\nsupervisor commands and never enter the model: `/help` (alias `/commands`),\n`/status`, `/interrupt`, `/clear`, `/compact`, `/model <model-id>`,\n`/restart`, `/force-restart`, `/ls`, `/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\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, over-size, or disallowed-MIME 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,\ntheir content signature must match the declared MIME, and symlinks or non-regular\npaths 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\nVoice prompts include a bounded transcript only when ours-mcp reports success.\nFailure or unavailability is explicit and preserves the private audio path as the\nfallback. Run `ours-mcp voice-status --json` to inspect the host configuration.\nA mode-0600 crash journal contains only authenticated CID and wire routing data;\nit never stores captions, filenames, paths, transcript text, or bytes. Journaled\npost-retrieval files resume selectively through `save_file`; corrupt state\ndisables attachment admission rather than weakening provenance 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\n`session: acp`: tmux has no structured, turn-correlated final answer, and pane\nscraping cannot provide the same reliable reply guarantee.\n\n### Live contact and owner administration\n\nThe supervisor which is already running the ACP 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\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, tmux session, 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\nAn optional `worklog: { max_kb, keep_tail_kb, max_archives }` policy rotates a\nstable snapshot at fleet-owned lifecycle points. Concurrent changes defer\nrotation. Archives remain beside WORKLOG.md with the same sensitive-state\nboundary; retention deletes only recognized fleet archive names.\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. A role selects\na harness independently from its session backend:\n\n- harness: `claude-code` or `codex`\n- session: `tmux` (default) or `acp`\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]\n```\n\nDefault configuration is `~/fleet.yaml` plus sorted `~/fleet.d/*.yaml` role\ndrop-ins. An explicit `-c FILE` replaces `~/fleet.yaml`; fleet.d still adds\nroles. Validate with `config` and `doctor` before starting or restarting.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init\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 send Name --key Enter        # tmux only\nours-fleet rm Name\nours-fleet watchdog-report <name> [run-id] [--list] [--json]\nours-fleet watchdog-run <name>\n```\n\n`peek`, `attach`, and text `send` work with tmux and ACP. ACP attachment\nalso accepts `/permit <permission-id> <option-id>`, `/interrupt`, and\n`/detach`. Raw `--key` input is tmux-only.\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 \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nTemporary-role identity bootstrap is capability-based. The generated briefing\nfirst tries to bind the exact assigned identity and preserves it when it already\nexists. If missing, it uses ours MCP `create_temporary_identity` when that tool\nis exposed, tying a newly-created identity to the connector session lifecycle;\nolder servers fall back to `create_identity`. Collisions and creation errors\nstop safely without force-adopting or deleting identity state. Permanent roles\nretain normal `create_identity` behavior.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and legacy `--monitor` (consent for the native Codex monitor,\nnot the `monitor.mode` wake-owner selector). Run `ours-fleet help spawn` for\nexact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      mode: fleet                        # fleet supervisor | native harness monitor\n      interrupt: false                    # true cancels active work before every configured wake\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\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    harness: claude-code            # default: defaults.harness\n    model: claude-fable-5           # default: same resolution rule roles use (resolveRoleModel)\n    session: acp                    # default: defaults.session\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    isolation:                      # optional; omitted means no OS sandbox, like an ordinary role\n      backend: bubblewrap           # when present, the ordinary role isolation schema applies\n      network: broker\n      fs: { read: [/opt/watch-data] }\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`), not in `~/fleet.d/*.yaml` drop-ins.\nWatchdogs are not isolated by default. An explicit watchdog `isolation:` block\nuses the same policy schema as a role and is applied unchanged; declare every\nextra filesystem access required by a custom prompt there.\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\nRole values override defaults. `${name}` substitutes entries from `vars`.\nOther role fields include `max_tokens`, `autocompact_pct`, and `isolation`.\nUse README.md for the complete isolation policy and resource-cap schema.\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|allow|deny`: whether actions may request or receive approval\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what ACP does when no console can answer a request\n\nThe backend translates this common intent. Harness-native settings in\n`harness_options` take precedence where supplied. Do not choose\n`allow`/`unrestricted`, Codex `never`/`danger-full-access`, or Claude\n`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: `approval: allow` maps to Claude's `bypassPermissions`,\nwhich genuinely permits 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` is elevated: `ask` stays on Claude's default\nmode and `deny` maps to `plan`. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\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`, and\n`mem_palace_midsession_autosave`.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `sandbox`\n(read-only, workspace-write, danger-full-access), `approval` or\n`permission_mode` (untrusted, on-request, never), `profile`, `search`,\n`config`, `add_dirs`, and `monitor`.\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.\nThe maintained Claude adapter requires Node 22; tmux and Codex ACP continue to\nwork on the ours-fleet core minimum of Node 20.\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`; tmux uses verified console injection.\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. The policy is content-blind because the supervisor cannot\ninspect encrypted message bodies. Message bodies are released only when the\nrole calls the 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\nAn ACP role may declare a separate, existing ours identity which fleet \u2014 never\nthe agent \u2014 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  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    allowed_mime: [application/pdf, text/plain, image/png, audio/ogg]\n```\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.\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, fleet injects a request-specific outbox path into the owner\nprompt. The agent copies completed artifacts there; fleet sends every regular\nfile from the channel identity with the same source wire ID and removes the\ntemporary outbox only after successful delivery. The agent never chooses an owner\nrecipient or calls ours `send_file` for an owner-channel response.\nOwner messages whose trimmed text starts with `/` are deterministic\nsupervisor commands and never enter the model: `/help` (alias `/commands`),\n`/status`, `/interrupt`, `/clear`, `/compact`, `/model <model-id>`,\n`/restart`, `/force-restart`, `/ls`, `/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\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, over-size, or disallowed-MIME 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,\ntheir content signature must match the declared MIME, and symlinks or non-regular\npaths 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\nVoice prompts include a bounded transcript only when ours-mcp reports success.\nFailure or unavailability is explicit and preserves the private audio path as the\nfallback. Run `ours-mcp voice-status --json` to inspect the host configuration.\nA mode-0600 crash journal contains only authenticated CID and wire routing data;\nit never stores captions, filenames, paths, transcript text, or bytes. Journaled\npost-retrieval files resume selectively through `save_file`; corrupt state\ndisables attachment admission rather than weakening provenance 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\n`session: acp`: tmux has no structured, turn-correlated final answer, and pane\nscraping cannot provide the same reliable reply guarantee.\n\n### Live contact and owner administration\n\nThe supervisor which is already running the ACP 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, tmux session, 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\nAn optional `worklog: { max_kb, keep_tail_kb, max_archives }` policy rotates a\nstable snapshot at fleet-owned lifecycle points. Concurrent changes defer\nrotation. Archives remain beside WORKLOG.md with the same sensitive-state\nboundary; retention deletes only recognized fleet archive names.\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 (7.1).
  *

package/dist/docs.js

@@ -115,6 +115,14 @@ Permanent spawn writes \`~/fleet.d/Name.yaml\` and starts a supervised role.
 \`--temp\` writes ephemeral state, starts a detached supervisor, and removes the
 role after exit/reboot. Both lifetimes support \`--session acp\`.
 
+Temporary-role identity bootstrap is capability-based. The generated briefing
+first tries to bind the exact assigned identity and preserves it when it already
+exists. If missing, it uses ours MCP \`create_temporary_identity\` when that tool
+is exposed, tying a newly-created identity to the connector session lifecycle;
+older servers fall back to \`create_identity\`. Collisions and creation errors
+stop safely without force-adopting or deleting identity state. Permanent roles
+retain normal \`create_identity\` behavior.
+
 Codex-specific spawn flags: \`--sandbox\`, \`--permission-mode\`, \`--launcher\`,
 \`--profile\`, \`--search\`, repeatable \`--codex-config key=value\`, repeatable
 \`--add-dir\`, and legacy \`--monitor\` (consent for the native Codex monitor,
@@ -439,6 +447,21 @@ The supervisor which is already running the ACP role remains the sole binder of
 through the role's token-authenticated, mode-0600 Unix control socket for contact
 inspection and setup; it never starts another ours client and never force-binds:
 
+Rapid supervised restart is serialized by a role-scoped single-binder lease.
+The predecessor closes its authenticated control socket and MCP proxy before
+releasing ownership. The replacement waits at most five seconds and retries the
+daemon bind only when PID/start-marker metadata proves the holder was the same
+role and owner-channel identity. Foreign, live, corrupt, or otherwise
+unverifiable ownership remains fail-closed; fleet never uses \`force=true\`.
+
+If that matching predecessor misses the bound, its still-authenticated control
+route may send one fixed, digest-deduplicated recovery notice through the latest
+authenticated owner conversation (or the sole configured owner). Notice
+plaintext is never persisted. With no safe deterministic route fleet guesses no
+recipient and leaves the actionable failure in the web console and role logs.
+The remote recovery action is \`/restart\`; inspect repeated failures with
+\`ours-fleet logs <Role>\` or the web console.
+
 \`\`\`sh
 ours-fleet owner-channel contact list <Role>
 ours-fleet owner-channel contact invite <Role> [--name <label>]

package/dist/harness/claude-code.js

@@ -259,6 +259,7 @@ export function makeClaudeCodeAdapter(exec = realExec) {
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',
+            temporaryCreateTool: 'create_temporary_identity',
             setBioTool: 'set_bio',
             setPersonaTool: 'set_persona',
             currentIdentityTool: 'current_identity',

package/dist/harness/codex.js

@@ -288,6 +288,7 @@ export function makeCodexAdapter(exec = realExec) {
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',
+            temporaryCreateTool: 'create_temporary_identity',
             setBioTool: 'set_bio',
             setPersonaTool: 'set_persona',
             currentIdentityTool: 'current_identity',

package/dist/harness/types.d.ts

@@ -60,6 +60,8 @@ export type PermissionTranslation = {
 export interface BriefingVocab {
     bindTool: string;
     createTool: string;
+    /** Session-scoped identity creation, capability-detected by temporary roles. */
+    temporaryCreateTool: string;
     setBioTool: string;
     setPersonaTool: string;
     currentIdentityTool: string;

package/dist/ops.js

@@ -38,6 +38,7 @@ export function applyRole(role, opts = {}) {
         stateDir: dir, worklogPath: join(dir, 'WORKLOG.md'),
         routinesPath: join(dir, 'ROUTINES.md'), briefingBody,
         identityGuarantee: opts.identityGuarantee,
+        temporaryIdentity: opts.temp === true,
     }));
     if (opts.fresh)
         for (const f of ['.booted', '.session-id', '.exit-status'])

package/dist/owner-channel/binder.d.ts

@@ -0,0 +1,24 @@
+export declare const OWNER_BIND_HANDOFF_TIMEOUT_MS = 5000;
+export interface OwnerBinderDeps {
+    now?(): number;
+    sleep?(ms: number): Promise<void>;
+    alive?(pid: number): boolean;
+    processMarker?(pid: number): string | undefined;
+    /** Test seam for synchronizing contenders after stale-owner validation. */
+    beforeReclaim?(): Promise<void>;
+}
+export interface OwnerBinderLease {
+    /** True only when a prior binder for this exact role and identity was observed. */
+    inherited: boolean;
+    release(): void;
+}
+export declare class OwnerBinderConflictError extends Error {
+}
+export declare class OwnerBinderHandoffTimeoutError extends Error {
+}
+/**
+ * Serialize the one supervisor-owned binder for a role. A live matching holder
+ * is an overlapping predecessor and gets a bounded handoff window. A holder
+ * for any other role/identity, or unverifiable metadata, remains fail-closed.
+ */
+export declare function acquireOwnerBinderLease(stateDir: string, role: string, identity: string, deps?: OwnerBinderDeps, timeoutMs?: number): Promise<OwnerBinderLease>;

package/dist/owner-channel/binder.js

@@ -0,0 +1,224 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replaceFileAtomically } from '../atomic-file.js';
+export const OWNER_BIND_HANDOFF_TIMEOUT_MS = 5_000;
+const OWNER_BIND_POLL_MS = 50;
+const LOCK_DIR = '.owner-channel-binder.lock';
+const RECLAIM_DIR = '.owner-channel-binder.reclaim.lock';
+const LAST_OWNER_FILE = '.owner-channel-binder.json';
+export class OwnerBinderConflictError extends Error {
+}
+export class OwnerBinderHandoffTimeoutError extends Error {
+}
+const defaultAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Linux PID-reuse fence. Other platforms return undefined and stay conservative. */
+const defaultProcessMarker = (pid) => {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const end = stat.lastIndexOf(')');
+        return stat.slice(end + 2).split(/\s+/)[19];
+    }
+    catch {
+        return undefined;
+    }
+};
+function parseOwner(path) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new OwnerBinderConflictError('owner-channel binder ownership cannot be verified safely');
+    }
+    const owner = value;
+    if (owner.version !== 1 || typeof owner.role !== 'string' || typeof owner.identity !== 'string'
+        || !Number.isSafeInteger(owner.pid) || Number(owner.pid) < 2
+        || typeof owner.instance !== 'string' || !owner.instance
+        || !Number.isFinite(owner.acquiredAt))
+        throw new OwnerBinderConflictError('owner-channel binder ownership cannot be verified safely');
+    return owner;
+}
+function sameOwner(a, b) {
+    return a.instance === b.instance && a.pid === b.pid && a.role === b.role
+        && a.identity === b.identity;
+}
+/**
+ * Serialize the one supervisor-owned binder for a role. A live matching holder
+ * is an overlapping predecessor and gets a bounded handoff window. A holder
+ * for any other role/identity, or unverifiable metadata, remains fail-closed.
+ */
+export async function acquireOwnerBinderLease(stateDir, role, identity, deps = {}, timeoutMs = OWNER_BIND_HANDOFF_TIMEOUT_MS) {
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const alive = deps.alive ?? defaultAlive;
+    const processMarker = deps.processMarker ?? defaultProcessMarker;
+    const lockDir = join(stateDir, LOCK_DIR);
+    const reclaimDir = join(stateDir, RECLAIM_DIR);
+    const ownerPath = join(lockDir, 'owner.json');
+    const releasedPath = join(stateDir, LAST_OWNER_FILE);
+    const startedAt = now();
+    let inherited = false;
+    const ours = {
+        version: 1, role, identity, pid: process.pid,
+        ...(processMarker(process.pid) ? { marker: processMarker(process.pid) } : {}),
+        instance: randomUUID(), acquiredAt: startedAt,
+    };
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    for (;;) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+            writeFileSync(ownerPath, JSON.stringify(ours) + '\n', { mode: 0o600 });
+            // A reclaimer may have installed its gate after our mkdir. It will
+            // re-check the canonical owner before claiming, while we withdraw our
+            // own raced acquisition before returning.
+            if (existsSync(reclaimDir)) {
+                const check = parseOwner(ownerPath);
+                if (!sameOwner(check, ours))
+                    throw new OwnerBinderConflictError('owner-channel binder ownership changed during acquisition');
+                rmSync(lockDir, { recursive: true, force: true });
+                if (now() - startedAt >= timeoutMs)
+                    throw new OwnerBinderHandoffTimeoutError(`owner-channel binder reclaim did not complete within ${timeoutMs}ms`);
+                await sleep(Math.min(OWNER_BIND_POLL_MS, Math.max(1, timeoutMs - (now() - startedAt))));
+                continue;
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let current;
+            try {
+                current = parseOwner(ownerPath);
+            }
+            catch (readError) {
+                // The winning process may be between atomic mkdir and its tiny metadata write.
+                if (now() - startedAt < OWNER_BIND_POLL_MS * 2) {
+                    await sleep(OWNER_BIND_POLL_MS);
+                    continue;
+                }
+                throw readError;
+            }
+            if (current.role !== role || current.identity !== identity)
+                throw new OwnerBinderConflictError(`owner-channel identity '${identity}' is reserved by foreign binder `
+                    + `'${current.role}' for '${current.identity}'`);
+            inherited = true;
+            const currentMarker = processMarker(current.pid);
+            const stale = !alive(current.pid)
+                || Boolean(current.marker && currentMarker && current.marker !== currentMarker);
+            if (stale) {
+                await deps.beforeReclaim?.();
+                try {
+                    mkdirSync(reclaimDir, { mode: 0o700 });
+                }
+                catch (gateError) {
+                    if (gateError.code === 'EEXIST') {
+                        await sleep(OWNER_BIND_POLL_MS);
+                        continue;
+                    }
+                    throw gateError;
+                }
+                const tombstone = `${lockDir}.reclaim-${ours.instance}`;
+                let acquiredFromClaim = false;
+                try {
+                    const check = parseOwner(ownerPath);
+                    if (!sameOwner(current, check))
+                        continue;
+                    try {
+                        renameSync(lockDir, tombstone);
+                    }
+                    catch (claimError) {
+                        if (claimError.code === 'ENOENT')
+                            continue;
+                        throw claimError;
+                    }
+                    let claimed;
+                    try {
+                        claimed = parseOwner(join(tombstone, 'owner.json'));
+                    }
+                    catch (claimError) {
+                        // Preserve an unverifiable claim. Restore it only if nobody has
+                        // already acquired the canonical path; otherwise fail closed.
+                        try {
+                            renameSync(tombstone, lockDir);
+                        }
+                        catch { /* keep the claim quarantined */ }
+                        throw claimError;
+                    }
+                    if (!sameOwner(current, claimed)) {
+                        // Never delete a replacement: put it back when possible, otherwise
+                        // retain the unique tombstone as the fail-closed claimed record.
+                        try {
+                            renameSync(tombstone, lockDir);
+                        }
+                        catch { /* keep the claim quarantined */ }
+                        throw new OwnerBinderConflictError('owner-channel binder changed while stale ownership was being claimed');
+                    }
+                    rmSync(tombstone, { recursive: true, force: true });
+                    // Keep the gate until our replacement is durable. Any acquisition
+                    // that raced the rename observes the gate and withdraws itself.
+                    for (;;) {
+                        try {
+                            mkdirSync(lockDir, { mode: 0o700 });
+                            writeFileSync(ownerPath, JSON.stringify(ours) + '\n', { mode: 0o600 });
+                            acquiredFromClaim = true;
+                            break;
+                        }
+                        catch (replacementError) {
+                            if (replacementError.code !== 'EEXIST')
+                                throw replacementError;
+                            if (now() - startedAt >= timeoutMs)
+                                throw new OwnerBinderHandoffTimeoutError(`could not complete stale owner-channel binder claim within ${timeoutMs}ms`);
+                            await sleep(1);
+                        }
+                    }
+                }
+                finally {
+                    rmSync(reclaimDir, { recursive: true, force: true });
+                }
+                if (acquiredFromClaim)
+                    break;
+                continue;
+            }
+            if (now() - startedAt >= timeoutMs)
+                throw new OwnerBinderHandoffTimeoutError(`previous '${role}' supervisor still owns owner-channel identity '${identity}' `
+                    + `after ${timeoutMs}ms bounded handoff`);
+            await sleep(Math.min(OWNER_BIND_POLL_MS, Math.max(1, timeoutMs - (now() - startedAt))));
+        }
+    }
+    try {
+        const released = JSON.parse(readFileSync(releasedPath, 'utf8'));
+        if (released.version === 1 && released.role === role && released.identity === identity
+            && Number.isFinite(released.releasedAt)
+            && now() - Number(released.releasedAt) <= timeoutMs * 2)
+            inherited = true;
+    }
+    catch { /* absence/corruption cannot grant recovery authority */ }
+    let released = false;
+    return {
+        inherited,
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                const current = parseOwner(ownerPath);
+                if (!sameOwner(current, ours))
+                    return;
+                replaceFileAtomically(releasedPath, JSON.stringify({
+                    ...ours, releasedAt: now(),
+                }) + '\n', 0o600);
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch { /* never remove ownership which cannot be proven to be ours */ }
+        },
+    };
+}

package/dist/owner-channel/channel.d.ts

@@ -6,6 +6,7 @@ import { type OursToolClient } from './mcp.js';
 import { type OwnerUpdatePhase } from './notices.js';
 import { type OwnerEntry } from './state.js';
 import { type OwnerTaskPhase } from './tasks.js';
+import { type OwnerBinderDeps, type OwnerBinderLease } from './binder.js';
 export interface OwnerChannelOptions {
     role: string;
     /** Harness id of the role (e.g. 'claude-code', 'codex'); gates which slash commands may be forwarded. */
@@ -23,6 +24,10 @@ export interface OwnerChannelOptions {
     fleet?: OwnerFleetOps;
     /** Forwarded to fleet CLI invocations spawned for owner commands. */
     configPath?: string;
+    /** Deterministic clock/process seams for binder handoff tests. */
+    binderDeps?: OwnerBinderDeps;
+    /** Pre-acquired by the runner so the predecessor control socket remains reachable while waiting. */
+    binderLease?: OwnerBinderLease;
 }
 export interface OwnerChannelHandle {
     start(): Promise<void>;
@@ -60,6 +65,8 @@ export type OwnerChannelManagementRequest = {
     taskId: string;
     phase: OwnerTaskPhase;
     message: string;
+} | {
+    action: 'startup_failure';
 };
 export type OwnerChannelManagementResult = {
     action: 'contact_list';
@@ -95,6 +102,9 @@ export type OwnerChannelManagementResult = {
     phase: OwnerTaskPhase;
     sequence: number;
     state: 'open' | 'closed';
+} | {
+    action: 'startup_failure';
+    status: 'delivered' | 'duplicate';
 };
 export type { OwnerUpdatePhase } from './notices.js';
 export interface OwnerContact {
@@ -137,6 +147,8 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     private readonly activeRequests;
     private managementTail;
     private ready;
+    private binder?;
+    private binderOwnedInternally;
     private readonly fleetOps;
     constructor(options: OwnerChannelOptions);
     start(): Promise<void>;

package/dist/owner-channel/channel.js

@@ -11,6 +11,7 @@ import { ownerNotices } from './notices.js';
 import { DuplicateSendError, OwnerAuthorizationState, OwnerChannelState, OwnerConversationState, } from './state.js';
 import { OwnerTaskState, ownerTaskAuditId, ownerTaskDigest, } from './tasks.js';
 import { AttachmentRecoveryState, admitAttachments, cleanupAttachmentRoot, parseIncomingAttachments, parseRetrievedAttachments, prepareAttachmentDirectory, recoveredAttachment, removeRequestDirectory, safeField, validateAttachmentSelection, } from './attachments.js';
+import { acquireOwnerBinderLease, OWNER_BIND_HANDOFF_TIMEOUT_MS, } from './binder.js';
 const OWNER_UPDATE_MIN_INTERVAL_MS = 5_000;
 const OWNER_UPDATE_MAX_COUNT = 20;
 const OWNER_UPDATE_MAX_CHARS = 280;
@@ -51,6 +52,8 @@ export class OwnerChannel {
     activeRequests = new Map();
     managementTail = Promise.resolve();
     ready = false;
+    binder;
+    binderOwnedInternally = false;
     fleetOps;
     constructor(options) {
         this.options = options;
@@ -79,8 +82,36 @@ export class OwnerChannel {
     }
     async start() {
         this.stopping = false;
-        await this.client.start();
-        await this.client.callTool('choose_identity', { name: this.options.config.identity });
+        this.binderOwnedInternally = !this.options.binderLease;
+        this.binder = this.options.binderLease ?? await acquireOwnerBinderLease(this.options.stateDir, this.options.role, this.options.config.identity, this.options.binderDeps);
+        try {
+            await this.client.start();
+            const now = this.options.binderDeps?.now ?? (() => Date.now());
+            const sleep = this.options.binderDeps?.sleep
+                ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+            const bindStartedAt = now();
+            for (;;) {
+                try {
+                    await this.client.callTool('choose_identity', { name: this.options.config.identity });
+                    break;
+                }
+                catch (error) {
+                    const message = error?.message ?? String(error);
+                    const liveConflict = /currently bound to another live session/i.test(message);
+                    if (!this.binder.inherited || !liveConflict
+                        || now() - bindStartedAt >= OWNER_BIND_HANDOFF_TIMEOUT_MS)
+                        throw error;
+                    await sleep(Math.min(50, Math.max(1, OWNER_BIND_HANDOFF_TIMEOUT_MS - (now() - bindStartedAt))));
+                }
+            }
+        }
+        catch (error) {
+            await this.client.close().catch(closeError => this.logError('startup client close failed', closeError));
+            if (this.binderOwnedInternally)
+                this.binder.release();
+            this.binder = undefined;
+            throw error;
+        }
         if (this.authorizationIntegrity().ok && this.tasks.integrity().ok)
             this.tasks.cleanup(Date.now(), this.effectiveOwners());
         if (this.attachmentRecovery.integrity()) {
@@ -112,7 +143,14 @@ export class OwnerChannel {
         if (watch && watch.exitCode === null)
             watch.kill('SIGTERM');
         await this.managementTail;
-        await this.client.close();
+        try {
+            await this.client.close();
+        }
+        finally {
+            if (this.binderOwnedInternally)
+                this.binder?.release();
+            this.binder = undefined;
+        }
     }
     manage(request) {
         const run = this.managementTail.then(() => this.manageNow(request));
@@ -208,6 +246,18 @@ export class OwnerChannel {
                 if (this.options.config.agent)
                     throw new Error('direct task reports are disabled; the managed agent must message its owner-channel identity');
                 return this.sendOwnerTaskReport(request);
+            case 'startup_failure': {
+                const message = ownerNotices.startupHandoffFailed(this.options.role, this.options.config.identity);
+                try {
+                    await this.sendProactiveMessage(message);
+                }
+                catch (error) {
+                    if (error instanceof DuplicateSendError)
+                        return { action: request.action, status: 'duplicate' };
+                    throw error;
+                }
+                return { action: request.action, status: 'delivered' };
+            }
             default:
                 throw new Error('unknown owner-channel management action');
         }

package/dist/owner-channel/mcp.js

@@ -70,6 +70,16 @@ export class OursMcpClient {
         this.child = undefined;
         if (!child || child.exitCode !== null)
             return;
+        // EOF lets the proxy close its HTTP MCP transport and release the daemon
+        // lease explicitly. SIGTERM used to leave that release racing the next
+        // supervised start, which is the owner-channel collision this path guards.
+        child.stdin.end();
+        const exited = await new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), 1_000);
+            child.once('exit', () => { clearTimeout(timer); resolve(true); });
+        });
+        if (exited || child.exitCode !== null)
+            return;
         child.kill('SIGTERM');
         await new Promise(resolve => {
             const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 5_000);

package/dist/owner-channel/notices.d.ts

@@ -14,6 +14,7 @@ export declare const ownerNotices: {
     commandFailed: (command: string) => string;
     commandUnsupported: (command: string, harness: string) => string;
     restarting: (role: string, command: string, mode: "keep" | "fresh") => string;
+    startupHandoffFailed: (role: string, identity: string) => string;
     attachmentRejected: (reason: string) => string;
     attachmentFailed: () => string;
     deliveryFailed: (role: string) => string;

package/dist/owner-channel/notices.js

@@ -39,6 +39,9 @@ export const ownerNotices = {
     restarting: (role, command, mode) => `ℹ️ ${command} accepted — restarting ${role} ${mode === 'fresh'
         ? 'FRESH (context wiped)' : '(context resumes)'}. `
         + 'The channel goes quiet during the restart and resumes when the agent is back.',
+    startupHandoffFailed: (role, identity) => `⚠️ ${role} owner channel could not take over '${identity}' from its previous supervisor. `
+        + `Recovery: send /restart to retry the supervised handoff; if this repeats, inspect the web `
+        + `console or run ours-fleet logs ${role}.`,
     attachmentRejected: (reason) => `⚠️ Attachment rejected: ${reason}.`,
     attachmentFailed: () => '⚠️ Could not securely retrieve or admit this attachment request.',
     deliveryFailed: (role) => `⚠️ Could not deliver this request to ${role}.`,

package/dist/runner.d.ts

@@ -5,6 +5,7 @@ import { type MonitorHandle, type MonitorOpts, type FetchLike } from './monitor.
 import { type Exec } from './exec.js';
 import type { ExitRecord } from './session/types.js';
 import { type OwnerChannelHandle, type OwnerChannelOptions } from './owner-channel/channel.js';
+import { type OwnerBinderLease } from './owner-channel/binder.js';
 export interface RunnerDeps {
     tmux: Tmux;
     exec: Exec;
@@ -19,6 +20,10 @@ export interface RunnerDeps {
     createMonitor(opts: MonitorOpts): MonitorHandle;
     /** Construct trusted owner ingress (injectable for lifecycle tests). */
     createOwnerChannel(opts: OwnerChannelOptions): OwnerChannelHandle;
+    /** Acquire the cross-process owner-channel binder lease before replacing the control socket. */
+    acquireOwnerBinder(stateDir: string, role: string, identity: string): Promise<OwnerBinderLease>;
+    /** Ask the still-authenticated predecessor to emit the fixed recovery notice. */
+    reportOwnerStartupFailure(stateDir: string): Promise<'delivered' | 'duplicate'>;
     /** Lets a test (or a shutdown path) end the supervised restart loop. */
     shouldStop?(): boolean;
 }

package/dist/runner.js

@@ -13,12 +13,13 @@ import { selectIsolationBackend } from './isolation/registry.js';
 import { resourceArgs, cpuControllerDelegated } from './isolation/resources.js';
 import { resolveLaunchRuntime } from './isolation/runtime.js';
 import { AcpSession } from './session/acp.js';
-import { RoleControlServer } from './session/control.js';
+import { controlRequest, RoleControlServer } from './session/control.js';
 import { TmuxSession } from './session/tmux.js';
 import { classifyShellStatus } from './session/types.js';
 import { effectiveModelForRole, modelRecoveryHeld, reconcileModelRecovery, recordModelFailure, classifyFailureText, } from './model-recovery.js';
 import { rotateWorklog } from './worklog.js';
 import { OwnerChannel } from './owner-channel/channel.js';
+import { acquireOwnerBinderLease, OwnerBinderHandoffTimeoutError, } from './owner-channel/binder.js';
 import { RoleTurnArbiter } from './session/arbiter.js';
 import { ScheduledLoopManager, } from './loops/manager.js';
 const defaultDeps = () => ({
@@ -38,6 +39,19 @@ const defaultDeps = () => ({
     fetch: (url, init) => globalThis.fetch(url, init),
     createMonitor: opts => createMonitor(opts),
     createOwnerChannel: opts => new OwnerChannel(opts),
+    acquireOwnerBinder: (stateDir, role, identity) => acquireOwnerBinderLease(stateDir, role, identity),
+    reportOwnerStartupFailure: async (stateDir) => {
+        const response = await controlRequest(stateDir, {
+            command: 'owner_channel_manage', ownerChannel: { action: 'startup_failure' },
+        }, 2_000);
+        if (!response.ok)
+            throw new Error(response.error ?? 'prior owner channel refused startup notice');
+        const result = response.result;
+        if (result?.action !== 'startup_failure'
+            || (result.status !== 'delivered' && result.status !== 'duplicate'))
+            throw new Error('prior owner channel returned an invalid startup notice result');
+        return result.status;
+    },
 });
 const MONITOR_OWNER_FILE = '.monitor-owner';
 /**
@@ -420,6 +434,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     let monitorLoop;
     let acpStartupComplete = false;
     let ownerChannel;
+    let ownerBinder;
     let loopManager;
     let arbiter;
     let reloadLoopConfig;
@@ -455,8 +470,37 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             if (evidence)
                 resolvedMonitorDeps.onFailureEvidence?.(evidence);
         });
+        if (role.owner_channel) {
+            try {
+                ownerBinder = await deps.acquireOwnerBinder(dir, name, role.owner_channel.identity);
+            }
+            catch (error) {
+                if (error instanceof OwnerBinderHandoffTimeoutError) {
+                    try {
+                        const status = await deps.reportOwnerStartupFailure(dir);
+                        deps.log(`[${name}] owner channel startup recovery notice ${status} by authenticated predecessor`);
+                    }
+                    catch (notifyError) {
+                        deps.log(`[${name}] owner channel startup recovery notice unavailable: `
+                            + `${notifyError?.message ?? String(notifyError)}`);
+                    }
+                }
+                await acpSession.close();
+                unsubscribeRecovery?.();
+                throw new Error(`[${name}] owner channel failed to start: `
+                    + `${error?.message ?? String(error)}`);
+            }
+        }
         control = new RoleControlServer(dir, arbiter, deps.log);
-        await control.start();
+        try {
+            await control.start();
+        }
+        catch (error) {
+            ownerBinder?.release();
+            await acpSession.close();
+            unsubscribeRecovery?.();
+            throw error;
+        }
         resolvedMonitorDeps.delivery = {
             // A wake is only delivered when its turn TERMINATES successfully. A
             // refusal or a cancellation reached the agent and was not acted on, so
@@ -496,6 +540,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         if (!started.succeeded) {
             monitor?.stop();
             await control.close();
+            ownerBinder?.release();
             await acpSession.close();
             unsubscribeRecovery?.();
             if (modelRecovery) {
@@ -526,6 +571,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 stateDir: dir,
                 env: role.env,
                 log: deps.log,
+                ...(ownerBinder ? { binderLease: ownerBinder } : {}),
                 ...(configPath ? { configPath } : {}),
             });
             try {
@@ -535,14 +581,17 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 monitor?.stop();
                 if (monitorLoop)
                     await monitorLoop;
+                await ownerChannel.close().catch(() => undefined);
                 await control.close();
+                ownerBinder?.release();
                 await acpSession.close();
                 unsubscribeRecovery?.();
                 throw new Error(`[${name}] owner channel failed to start: `
                     + `${error?.message ?? String(error)}`);
             }
-            control.setOwnerChannel(ownerChannel);
         }
+        if (ownerChannel)
+            control.setOwnerChannel(ownerChannel);
         reloadLoopConfig = async () => {
             const nextRole = findRole(loadConfig(configPath), name);
             const definitions = nextRole.loops ?? [];
@@ -628,17 +677,21 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         await loopManager.stop();
     }
     control?.setConfigReloader(undefined);
-    if (ownerChannel) {
-        control?.setOwnerChannel(undefined);
-        await ownerChannel.close();
+    // Close the authenticated control route before releasing the binder lease;
+    // otherwise the predecessor can unlink the replacement's new socket.
+    if (control) {
+        control.setOwnerChannel(undefined);
+        await control.close();
+        control = undefined;
     }
+    if (ownerChannel)
+        await ownerChannel.close();
+    ownerBinder?.release();
     if (monitor) {
         monitor.stop();
         await monitorLoop;
     }
     unsubscribeRecovery?.();
-    if (control)
-        await control.close();
     if (acpSession)
         await acpSession.close();
     const elapsed = (deps.now() - start) / 1000;

package/package.json

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