@ours.network/fleet 0.15.1 → 0.15.3

package/README.md

@@ -130,6 +130,16 @@ ours-fleet spawn Coder --harness codex --model gpt-5.4 \
 # wake owner separately in fleet.yaml with monitor.mode: fleet|native.
 ```
 
+Inside a managed ACP role, `ours-fleet spawn` is transparently routed through
+that role's live supervisor. `ours-fleet spawn --role DeveloperX --temp` is the
+minimal form: omitted harness, session, cwd, coordinator, neutral permissions,
+fleet monitor policy, and same-harness model inherit from the caller. Explicit
+flags win; changing harness without a model lets the selected harness/fleet
+defaults choose one. After creation succeeds, fleet can deterministically notify
+the caller's owner channel with the caller and spawned-role details. This is an
+honest-actor convenience and attribution path, not a security boundary; tmux,
+host shells, and deliberately bypassed absolute binaries retain direct behavior.
+
 ## Local web console
 
 The interactive console is packaged with `@ours.network/fleet` and binds to
@@ -267,7 +277,7 @@ ours-fleet up|down|restart|force-restart [-c FILE] [Name...]
 ours-fleet config [-c FILE]         validate + print merged plan
 ours-fleet ls | attach | peek | logs [-f] | status <Name>
 ours-fleet send <Name> "text" | --key <K>
-ours-fleet spawn [--temp] <Name> [--harness --session --mission --model --approval ...]
+ours-fleet spawn [--temp] [<Name> | --role <Name>] [--harness --session --mission --model --approval ...]
 ours-fleet loops validate|list|status
 ours-fleet loops reload <Role>
 ours-fleet loops run-now|disable|enable <Role> <Loop>
@@ -657,9 +667,14 @@ An owner request follows one ordered lifecycle on its authenticated source wire:
 3. The agent may send any non-final message to the channel identity through its
    ordinary ours MCP tool. CID authentication is the message gate; no task ID,
    request ID, phase, reply reference, or routing command is used.
-4. Fleet independently emits exactly one final ACP
-   response (or a sanitized terminal outcome). Successful turns send regular files
-   from the request outbox afterward, correlated to the same source wire.
+4. The agent may send a caption and one or more files to the channel identity.
+   A reply reference selects the authenticated owner of that exact source wire;
+   an uncorrelated group uses the latest authenticated owner (or the sole-owner
+   fallback). Fleet resolves that route once, admits every file before emitting
+   any part, then sends the caption and files to the same owner on the same route.
+5. Fleet independently emits exactly one final ACP response (or a sanitized
+   terminal outcome). Successful owner-request turns send regular files from the
+   request outbox afterward, correlated to the same source wire.
 
 Fleet chooses the stored latest authenticated owner for every managed-agent
 message; the model supplies only text and the channel contact. Relay audit logs
@@ -667,6 +682,16 @@ contain hashed wire prefixes and sizes, never bodies. A durable pre-send marker
 prevents blind replay after an ambiguous transport outcome. `/interrupt` remains
 an owner-only supervisor command and does not change the outbound relay contract.
 
+Managed-agent caption/file groups have one admission and delivery boundary.
+Fleet authenticates every group member, fixes one owner route before retrieval,
+and validates all selected bytes before sending the caption or any file. A
+correlated source wire never falls back to a different owner. Missing routes stay
+queued without byte retrieval and produce at most one bounded correlated notice
+per running bridge. Policy or admission rejection consumes the entire group and
+sends one correlated NACK. Once outbound emission starts, any transport error is
+recorded as terminal uncertain delivery: the whole group is consumed and never
+blind-retried, because some parts may already have reached the owner.
+
 Background work must not keep an ACP turn open. The agent can finalize, return to
 idle, verify the later result on a future wake, and send the result to the same
 channel identity with ordinary `send_message`. Fleet applies the same CID gate and
@@ -770,9 +795,13 @@ Request files are removed after final delivery and stale directories are removed
 after `retention_ms`. A bounded mode-0600 recovery journal stores only owner CID
 and wire routing metadata—never filenames, paths, captions, transcripts, or file
 bytes. If ours-mcp already marked a selected file processed when fleet restarts,
-fleet resumes only that journaled wire with `save_file`; recovered voice is
-explicitly marked transcript-unavailable. Corrupt recovery state disables
-attachment admission. The host must run an ours-mcp version whose
+fleet resumes only that journaled wire with `save_file`; a deferred managed-agent
+caption is replayed with its journaled processed files before the group is
+admitted or relayed. Conversation route state migrates from v1 to a bounded v2
+source-wire index so a correlated group keeps the authenticated owner selected by
+its original request even after later owner traffic. Recovered voice is explicitly
+marked transcript-unavailable. Corrupt recovery state disables attachment
+admission. The host must run an ours-mcp version whose
 `list_incoming_files`, selective `get_files`, and `save_file` schemas support
 these guarantees; `ours-mcp voice-status --json` reports whether transcription
 is currently configured.

package/dist/briefing.js

@@ -113,6 +113,17 @@ export function generateBriefing(role, v, opts) {
         L.push('System acceptance, queue, progress, interruption, failure, and final-delivery notices');
         L.push('on the owner channel are fleet-generated; do not imitate or resend them.');
     }
+    if (role.session === 'acp') {
+        L.push('', '### Managed fleet commands');
+        L.push('This ACP role has a supervisor-scoped ours-fleet proxy. Use the ordinary');
+        L.push('`ours-fleet spawn` command; the CLI routes it through your live supervisor, which');
+        L.push('records you as the caller and reports successful creation to your owner channel.');
+        L.push('A minimal call is `ours-fleet spawn --role DeveloperName --temp`.');
+        L.push('For omitted execution settings, the supervisor inherits your harness, session, model,');
+        L.push('working directory, neutral permissions, coordinator, and fleet monitor policy. Every');
+        L.push('explicit spawn option wins. An explicit different harness does not inherit your model.');
+        L.push('This proxy is attribution and convenience, not a security boundary for unisolated roles.');
+    }
     if (role.coordinator) {
         L.push(`7. ANNOUNCE yourself: call **${v.sendTool}** to contact "${role.coordinator}" with text:`);
         L.push(`   "${role.name} online — identity '${id}' bound, ready."`);

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { spawn as spawnChild } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
-import { join as joinPath } from 'node:path';
+import { join as joinPath, resolve as resolvePath } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
@@ -33,6 +33,7 @@ import { startWebConsole } from './web/runtime.js';
 import { requestWebControl } from './web/control.js';
 import { WebServiceManager } from './web/service.js';
 import { WebAccessStore, passwordAccess, validatePublicOrigin } from './web/access.js';
+import { FLEET_PROXY_CALLER_ENV, FLEET_PROXY_STATE_DIR_ENV, } from './fleet-proxy.js';
 import './harness/claude-code.js'; // registers the claude-code adapter
 import './harness/codex.js'; // registers the codex adapter
 // sudo/su shells lack XDG_RUNTIME_DIR, breaking every systemctl/journalctl
@@ -989,7 +990,8 @@ cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fl
         die(e);
     }
 });
-cOpt(program.command('spawn <name>').description('spawn a new agent (permanent by default)'))
+cOpt(program.command('spawn [name]').description('spawn a new agent (permanent by default)'))
+    .option('--role <name>', 'role name (alternative to the positional name)')
     .option('--temp', 'temporary: detached supervisor, auto-cleaned, gone on reboot')
     .option('--harness <id>', 'harness adapter (default: defaults.harness)')
     .option('--session <backend>', 'session backend: tmux|acp (default: defaults.session or tmux)')
@@ -1017,8 +1019,13 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
     .option('--json', 'with --dry-run, emit a stable secret-safe JSON result')
     .action(async (name, opts) => {
     try {
+        const roleName = String(name ?? opts.role ?? '');
+        if (!roleName)
+            throw new Error('role name is required (positional or --role)');
+        if (name && opts.role && name !== opts.role)
+            throw new Error(`positional role '${name}' conflicts with --role '${opts.role}'`);
         const o = {
-            name, temp: opts.temp, harness: opts.harness, session: opts.session, mission: opts.mission,
+            name: roleName, temp: opts.temp, harness: opts.harness, session: opts.session, mission: opts.mission,
             missionFile: opts.missionFile,
             identity: opts.identity, cwd: opts.cwd, coordinator: opts.coordinator,
             model: opts.model,
@@ -1049,13 +1056,38 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
             }
             return;
         }
+        const proxyStateDir = process.env[FLEET_PROXY_STATE_DIR_ENV];
+        if (proxyStateDir) {
+            // Paths entered in the agent shell belong to that shell's cwd, not the
+            // supervisor process. Normalize before crossing the control boundary.
+            for (const key of ['missionFile', 'bioFile', 'personaFile', 'isolationFile']) {
+                if (o[key])
+                    o[key] = resolvePath(o[key]);
+            }
+            const response = await controlRequest(proxyStateDir, { command: 'fleet_spawn', spawn: o }, 10 * 60_000);
+            if (!response.ok)
+                throw new SessionControlError(response.kind ?? 'backend', response.error ?? 'managed spawn failed');
+            const result = response.result;
+            const expectedCaller = process.env[FLEET_PROXY_CALLER_ENV];
+            if (expectedCaller && result.caller !== expectedCaller)
+                throw new Error(`fleet proxy caller mismatch: expected '${expectedCaller}', got '${result.caller}'`);
+            console.log(`spawned ${result.lifetime} agent '${result.role}' through `
+                + `${result.caller}'s fleet proxy (state: ${result.statePath})`);
+            console.log(`  ${result.harness}/${result.session}`
+                + `${result.model ? ` model=${result.model}` : ''}; `
+                + `monitor=${result.monitor.mode} interrupt=${result.monitor.interrupt}`);
+            if (result.inherited.length)
+                console.log(`  inherited omitted defaults from ${result.caller}: ${result.inherited.join(', ')}`);
+            console.log(`→ watch it: ours-fleet peek ${result.role}   |   attach: ours-fleet attach ${result.role}`);
+            return;
+        }
         if (o.temp) {
             const dir = await spawnTemp(o, binPath);
-            console.log(`spawned temp agent '${name}' (state: ${dir}; gone on exit/reboot)`);
+            console.log(`spawned temp agent '${roleName}' (state: ${dir}; gone on exit/reboot)`);
         }
         else {
             const file = await spawnPermanent(o, deps());
-            console.log(`spawned '${name}' (config: ${file})`);
+            console.log(`spawned '${roleName}' (config: ${file})`);
         }
         // The same provenance that was persisted, so what the operator reads now
         // and what a reviewer reads later cannot disagree (6.6).
@@ -1065,7 +1097,7 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
             for (const line of formatProvenance(lastProvenance))
                 console.log(line);
         }
-        console.log(`→ watch it: ours-fleet peek ${name}   |   attach: ours-fleet attach ${name}`);
+        console.log(`→ watch it: ours-fleet peek ${roleName}   |   attach: ours-fleet attach ${roleName}`);
     }
     catch (e) {
         die(e);

package/dist/creation.d.ts

@@ -141,7 +141,7 @@ export declare function daemonIdentityProvisioner(env?: NodeJS.ProcessEnv, fetch
 /** Atomically write a role's fleet.d file, journalling it for rollback. */
 export declare function writeRoleFile(tx: CreationTransaction, file: string, contents: string): void;
 /** Where a setting's effective value came from. */
-export type ProvenanceSource = 'cli' | 'fleet-default' | 'built-in';
+export type ProvenanceSource = 'cli' | 'fleet-default' | 'caller-role' | 'built-in';
 export interface ProvenanceEntry {
     value: unknown;
     source: ProvenanceSource;
@@ -155,8 +155,10 @@ export interface CreationProvenance {
     lifetime: 'permanent' | 'temporary';
     role: string;
     /** Additive correlation for non-CLI creation surfaces; never contains request data. */
-    surface?: 'cli' | 'web';
+    surface?: 'cli' | 'web' | 'agent';
     creationActionId?: string;
+    /** Managed role which requested creation through its supervisor proxy. */
+    callerRole?: string;
     /** Effective settings, each tagged with where its value came from. */
     settings: Record<string, ProvenanceEntry>;
 }
@@ -179,8 +181,9 @@ export declare function buildProvenance(o: {
     fleetVersion: string;
     now?: Date;
     settings: Record<string, ProvenanceEntry>;
-    surface?: 'cli' | 'web';
+    surface?: 'cli' | 'web' | 'agent';
     creationActionId?: string;
+    callerRole?: string;
 }): CreationProvenance;
 /** Write the provenance record atomically, before the role is started. */
 export declare function writeProvenance(stateDir: string, p: CreationProvenance): void;

package/dist/creation.js

@@ -247,6 +247,7 @@ export function buildProvenance(o) {
         role: o.role,
         surface: o.surface ?? 'cli',
         creationActionId: o.creationActionId,
+        callerRole: o.callerRole,
         settings: o.settings,
     };
 }
@@ -256,7 +257,10 @@ export function writeProvenance(stateDir, p) {
 }
 /** One concise line per non-built-in setting, for the post-creation summary. */
 export function formatProvenance(p) {
-    const mark = { cli: 'explicit', 'fleet-default': 'fleet default', 'built-in': 'built-in' };
+    const mark = {
+        cli: 'explicit', 'fleet-default': 'fleet default', 'caller-role': 'caller role',
+        'built-in': 'built-in',
+    };
     return Object.entries(p.settings)
         .filter(([, e]) => e.value !== undefined)
         .map(([k, e]) => `    ${k.padEnd(12)} ${String(e.value)}  (${mark[e.source]})`);

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\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";
+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 | --role 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\nInside a managed ACP role, the same CLI automatically routes a real `spawn`\nthrough that role's authenticated supervisor control socket. `--role Name` is\naccepted as an alternative to the positional name, so a minimal delegated call\nis `ours-fleet spawn --role DeveloperX --temp`. The supervisor records the\ncalling role, performs creation, and only after success sends a structured\nspawn notice through the caller's owner channel when one is configured.\n\nOmitted harness, session, working directory, coordinator, neutral permissions,\nfleet monitor policy, and (when the harness is unchanged) model inherit from the\ncalling role. Explicit options always win. Selecting a different harness without\n`--model` leaves model selection to that harness/fleet defaults rather than\ncopying an incompatible caller model. This automatic proxy is a convenience and\nattribution mechanism, not an isolation boundary: an unrestricted role can still\ninvoke another binary path directly. Tmux roles and host/operator shells keep the\nordinary direct CLI 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;\nits files may also be relayed through this channel. A reply reference selects the\nowner of that authenticated source wire instead of the latest conversation.\nEvery other CID is rejected and warned about without reflecting its body. Fleet sends\naccepted/queued/progress/interrupted/failure notices and routes the ACP turn's\nfinal assistant text back to the authenticated sender with its source wire ID.\nFor file replies, 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. For proactive or in-turn agent\nattachments, the agent calls ours `send_file` to the channel identity and may\npair it with a reply-linked caption; fleet, not the agent, chooses the owner.\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`. A deferred agent\ncaption is replayed with its processed files before the group is admitted. Fleet\nresolves one authenticated owner route before retrieving bytes, admits every file\nbefore emitting the caption or any file, and sends every part to that same route.\nUnknown correlated routes remain queued without retrieval and receive one bounded\ncorrelated notice. Admission rejection consumes the whole group with one NACK;\nonce emission starts, a transport error becomes terminal uncertain delivery and\nthe group is never blind-retried. Bounded v2 source-wire routing state is migrated\nfrom v1 on read. Corrupt state disables attachment admission rather than weakening\nprovenance checks.\n\nThe channel identity must be unique and must not be a role identity. The bridge\npersists bounded wire IDs only, never message/reply plaintext, and requeues input\nbefore starting its turn for at-least-once crash recovery. It currently requires\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

@@ -101,7 +101,7 @@ harness's own default.
 ## Spawn
 
 \`\`\`sh
-ours-fleet spawn [--temp] Name \\
+ours-fleet spawn [--temp] [Name | --role Name] \\
   --harness codex|claude-code --session tmux|acp \\
   --mission "one line" --cwd /absolute/path --identity Identity \\
   --coordinator Coordinator --model MODEL \\
@@ -123,6 +123,22 @@ 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.
 
+Inside a managed ACP role, the same CLI automatically routes a real \`spawn\`
+through that role's authenticated supervisor control socket. \`--role Name\` is
+accepted as an alternative to the positional name, so a minimal delegated call
+is \`ours-fleet spawn --role DeveloperX --temp\`. The supervisor records the
+calling role, performs creation, and only after success sends a structured
+spawn notice through the caller's owner channel when one is configured.
+
+Omitted harness, session, working directory, coordinator, neutral permissions,
+fleet monitor policy, and (when the harness is unchanged) model inherit from the
+calling role. Explicit options always win. Selecting a different harness without
+\`--model\` leaves model selection to that harness/fleet defaults rather than
+copying an incompatible caller model. This automatic proxy is a convenience and
+attribution mechanism, not an isolation boundary: an unrestricted role can still
+invoke another binary path directly. Tmux roles and host/operator shells keep the
+ordinary direct CLI 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,
@@ -396,15 +412,18 @@ This does not replace the role identity. Normal identity mail remains untrusted
 peer input: the agent reads it through \`get_messages\` and replies through
 \`send_message\`. Mail arriving on the dedicated channel from a CID in \`owners\`
 is injected as a direct \`[fleet-owner]\` prompt. Mail from the exact \`agent\`
-CID is forwarded as a new message to the latest authenticated owner conversation.
+CID is forwarded as a new message to the latest authenticated owner conversation;
+its files may also be relayed through this channel. A reply reference selects the
+owner of that authenticated source wire instead of the latest conversation.
 Every other CID is rejected and warned about without reflecting its body. Fleet sends
 accepted/queued/progress/interrupted/failure notices and routes the ACP turn's
 final assistant text back to the authenticated sender with its source wire ID.
 For file replies, fleet injects a request-specific outbox path into the owner
 prompt. The agent copies completed artifacts there; fleet sends every regular
 file from the channel identity with the same source wire ID and removes the
-temporary outbox only after successful delivery. The agent never chooses an owner
-recipient or calls ours \`send_file\` for an owner-channel response.
+temporary outbox only after successful delivery. For proactive or in-turn agent
+attachments, the agent calls ours \`send_file\` to the channel identity and may
+pair it with a reply-linked caption; fleet, not the agent, chooses the owner.
 Owner messages whose trimmed text starts with \`/\` are deterministic
 supervisor commands and never enter the model: \`/help\` (alias \`/commands\`),
 \`/status\`, \`/interrupt\`, \`/clear\`, \`/compact\`, \`/model <model-id>\`,
@@ -431,8 +450,16 @@ Failure or unavailability is explicit and preserves the private audio path as th
 fallback. Run \`ours-mcp voice-status --json\` to inspect the host configuration.
 A mode-0600 crash journal contains only authenticated CID and wire routing data;
 it never stores captions, filenames, paths, transcript text, or bytes. Journaled
-post-retrieval files resume selectively through \`save_file\`; corrupt state
-disables attachment admission rather than weakening provenance checks.
+post-retrieval files resume selectively through \`save_file\`. A deferred agent
+caption is replayed with its processed files before the group is admitted. Fleet
+resolves one authenticated owner route before retrieving bytes, admits every file
+before emitting the caption or any file, and sends every part to that same route.
+Unknown correlated routes remain queued without retrieval and receive one bounded
+correlated notice. Admission rejection consumes the whole group with one NACK;
+once emission starts, a transport error becomes terminal uncertain delivery and
+the group is never blind-retried. Bounded v2 source-wire routing state is migrated
+from v1 on read. Corrupt state disables attachment admission rather than weakening
+provenance checks.
 
 The channel identity must be unique and must not be a role identity. The bridge
 persists bounded wire IDs only, never message/reply plaintext, and requeues input

package/dist/fleet-proxy.d.ts

@@ -0,0 +1,25 @@
+import type { MonitorConfig, ResolvedRole } from './config.js';
+import type { SpawnOpts } from './spawn.js';
+/** Present only inside a managed role process. The CLI treats it as a routing hint, not authority. */
+export declare const FLEET_PROXY_STATE_DIR_ENV = "OURS_FLEET_PROXY_STATE_DIR";
+export declare const FLEET_PROXY_CALLER_ENV = "OURS_FLEET_PROXY_CALLER";
+export interface ManagedFleetSpawnResult {
+    caller: string;
+    role: string;
+    lifetime: 'permanent' | 'temporary';
+    statePath: string;
+    harness: string;
+    session: 'tmux' | 'acp';
+    model?: string;
+    monitor: Pick<MonitorConfig, 'mode' | 'interrupt'>;
+    inherited: string[];
+    creationActionId: string;
+}
+/**
+ * Fill only omitted spawn settings from the live caller. Explicit agent choices
+ * always win. This is convenience attribution, not an authorization boundary.
+ */
+export declare function inheritCallerSpawnDefaults(caller: ResolvedRole, requested: SpawnOpts, configPath: string | undefined): {
+    options: SpawnOpts;
+    inherited: string[];
+};

package/dist/fleet-proxy.js

@@ -0,0 +1,36 @@
+/** Present only inside a managed role process. The CLI treats it as a routing hint, not authority. */
+export const FLEET_PROXY_STATE_DIR_ENV = 'OURS_FLEET_PROXY_STATE_DIR';
+export const FLEET_PROXY_CALLER_ENV = 'OURS_FLEET_PROXY_CALLER';
+/**
+ * Fill only omitted spawn settings from the live caller. Explicit agent choices
+ * always win. This is convenience attribution, not an authorization boundary.
+ */
+export function inheritCallerSpawnDefaults(caller, requested, configPath) {
+    const options = { ...requested };
+    const inherited = [];
+    const take = (key, value) => {
+        if (options[key] !== undefined || value === undefined)
+            return;
+        options[key] = value;
+        inherited.push(String(key));
+    };
+    const sameHarness = requested.harness === undefined || requested.harness === caller.harness;
+    take('harness', caller.harness);
+    take('session', caller.session);
+    take('cwd', caller.cwd);
+    take('coordinator', caller.name);
+    take('approval', caller.permissions.approval);
+    take('filesystem', caller.permissions.filesystem);
+    take('unattended', caller.permissions.unattended);
+    take('monitorConfig', structuredClone(caller.monitor));
+    // A model name and native harness options are not portable across harnesses.
+    // When the caller explicitly switches harness, let that harness/fleet defaults
+    // select its model instead of copying (for example) a Codex model into Claude.
+    if (sameHarness)
+        take('model', caller.model);
+    options.configPath = configPath;
+    options.surface = 'agent';
+    options.callerRole = caller.name;
+    options.inheritedFromCaller = [...inherited];
+    return { options, inherited };
+}

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

@@ -2,6 +2,7 @@ import { type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { type OwnerChannelConfig } from '../config.js';
 import type { SessionHandle } from '../session/types.js';
 import { type OwnerFleetOps } from './commands.js';
+import type { ManagedFleetSpawnResult } from '../fleet-proxy.js';
 import { type OursToolClient } from './mcp.js';
 import { type OwnerUpdatePhase } from './notices.js';
 import { type OwnerEntry } from './state.js';
@@ -34,6 +35,8 @@ export interface OwnerChannelHandle {
     drain(): Promise<void>;
     close(): Promise<void>;
     manage(request: OwnerChannelManagementRequest): Promise<OwnerChannelManagementResult>;
+    /** Fleet-owned deterministic lifecycle notice; absent on legacy test doubles. */
+    notifyFleetSpawn?(event: ManagedFleetSpawnResult): Promise<void>;
 }
 export type OwnerChannelManagementRequest = {
     action: 'contact_list';
@@ -155,6 +158,7 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     drain(): Promise<void>;
     close(): Promise<void>;
     manage(request: OwnerChannelManagementRequest): Promise<OwnerChannelManagementResult>;
+    notifyFleetSpawn(event: ManagedFleetSpawnResult): Promise<void>;
     private manageNow;
     private contacts;
     private contact;
@@ -195,6 +199,15 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     private isAgentSender;
     private isEffectiveOwner;
     private relayManagedAgentMessage;
+    /**
+     * Caption and files are admitted as one relay transaction. The authenticated
+     * route and optional source wire are fixed before bytes are retrieved, and no
+     * outbound part is emitted until every file passes admission. A transport
+     * failure after emission starts is durably uncertain and never blind-retried;
+     * the managed agent receives one bounded NACK for the whole transaction.
+     */
+    private handleManagedAgentAttachmentGroup;
+    private managedAttachmentReplyWire;
     /**
      * One bounded NACK per wire: an unroutable or refused relay must be visible
      * to the authenticated agent, while its deferred replays stay quiet. NACK

package/dist/owner-channel/channel.js

@@ -157,6 +157,20 @@ export class OwnerChannel {
         this.managementTail = run.then(() => undefined, () => undefined);
         return run;
     }
+    notifyFleetSpawn(event) {
+        const run = this.managementTail.then(async () => {
+            if (!this.ready || this.stopping)
+                throw new Error('owner-channel MCP client is unavailable');
+            const model = event.model ? `, model ${event.model}` : '';
+            const monitor = `${event.monitor.mode} monitor${event.monitor.interrupt ? ' with interruption' : ''}`;
+            const inherited = event.inherited.length
+                ? ` Supervisor inherited omitted defaults: ${event.inherited.join(', ')}.` : '';
+            await this.sendProactiveMessage(`🧑‍💻 ${event.caller} spawned ${event.lifetime} agent ${event.role} `
+                + `(${event.harness}/${event.session}${model}; ${monitor}).${inherited}`, `fleet-spawn\0${event.creationActionId}`, 0);
+        });
+        this.managementTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
     async manageNow(request) {
         if (!this.ready || this.stopping)
             throw new Error('owner-channel MCP client is unavailable');
@@ -337,13 +351,15 @@ export class OwnerChannel {
         await send;
         return { action: request.action, requestId: request.requestId, sequence };
     }
-    async sendProactiveMessage(messageValue) {
+    async sendProactiveMessage(messageValue, digestValue = messageValue, minIntervalMs) {
         if (!this.authorizationIntegrity().ok)
             throw new Error('owner authorization state is corrupt; proactive messages are disabled');
         const message = this.safeProactiveMessage(messageValue);
         const route = this.conversations.route(this.effectiveOwners());
-        const digest = createHash('sha256').update(message).digest('hex');
-        const sending = this.conversations.beginSend(route.contact, digest);
+        const digest = createHash('sha256').update(digestValue).digest('hex');
+        const sending = minIntervalMs === undefined
+            ? this.conversations.beginSend(route.contact, digest)
+            : this.conversations.beginSend(route.contact, digest, Date.now(), minIntervalMs);
         try {
             if (!this.isEffectiveOwner(route.contact))
                 throw new Error('selected proactive owner is no longer authorized');
@@ -542,7 +558,18 @@ export class OwnerChannel {
             if (exact.some(file => file.senderId !== recovery.contact))
                 continue;
             exact.forEach(file => used.add(file.wireId));
-            groups.push({ files: exact, recovery });
+            const caption = recovery.originWireId === recovery.fileWireIds[0]
+                ? undefined : messageByWire.get(recovery.originWireId);
+            if (caption && this.sender(caption).id !== recovery.contact)
+                continue;
+            // A managed-agent caption is deferred before retrieval. If recovery sees
+            // the processed file before that body is replayed, keep the file reserved
+            // by the journal until both halves are present again.
+            if (!caption && !recovery.fileWireIds.includes(recovery.originWireId))
+                continue;
+            if (caption)
+                consumed.add(caption);
+            groups.push({ files: exact, recovery, ...(caption ? { caption } : {}) });
         }
         for (const file of files) {
             if (used.has(file.wireId))
@@ -578,6 +605,9 @@ export class OwnerChannel {
         if (handledWireIds.some(wire => this.inFlight.has(wire)))
             return false;
         const sender = { id: group.files[0].senderId, name: group.files[0].senderName };
+        if (group.files.every(file => this.isAgentSender(file.senderId))
+            && (!group.caption || this.isAgentSender(this.sender(group.caption).id)))
+            return this.handleManagedAgentAttachmentGroup(group, handledWireIds, sender.id);
         if (group.files.some(file => file.senderId !== sender.id)
             || !this.isEffectiveOwner(sender.id)) {
             this.options.log(`[${this.options.role}] owner channel ignored unauthorized attachment sender ${sender.id}`);
@@ -590,6 +620,14 @@ export class OwnerChannel {
                 catch { }
             return true;
         }
+        // Owner files are requests too: retain their authenticated source wire so
+        // a later managed-agent attachment reply cannot drift to a newer owner.
+        try {
+            this.conversations.recordInbound(sender.id, originWireId);
+        }
+        catch (error) {
+            this.logError('owner attachment route update failed', error);
+        }
         const rejection = !this.attachmentRecovery.integrity()
             ? 'attachment recovery state is unavailable'
             : validateAttachmentSelection(group.files, this.attachmentConfig);
@@ -936,6 +974,149 @@ export class OwnerChannel {
             + `wire=${createHash('sha256').update(wireId).digest('hex').slice(0, 12)} `
             + `basis=${route.basis} chars=${Array.from(text).length} bytes=${Buffer.byteLength(text)}`);
     }
+    /**
+     * Caption and files are admitted as one relay transaction. The authenticated
+     * route and optional source wire are fixed before bytes are retrieved, and no
+     * outbound part is emitted until every file passes admission. A transport
+     * failure after emission starts is durably uncertain and never blind-retried;
+     * the managed agent receives one bounded NACK for the whole transaction.
+     */
+    async handleManagedAgentAttachmentGroup(group, handledWireIds, agent) {
+        const captionWire = group.caption ? this.wireId(group.caption) : undefined;
+        const nackWire = captionWire ?? group.files[0].wireId;
+        const nackMessage = group.caption ?? { wire_id: nackWire };
+        let requestDir;
+        let recovery;
+        try {
+            if (!this.authorizationIntegrity().ok)
+                throw new Error('owner authorization state is corrupt; managed-agent relay is disabled');
+            const caption = group.caption ? this.safeRelayMessage(group.caption.text) : undefined;
+            const replyTo = this.managedAttachmentReplyWire(group, captionWire);
+            let route;
+            try {
+                route = replyTo
+                    ? this.conversations.routeForWire(replyTo, this.effectiveOwners())
+                    : this.conversations.route(this.effectiveOwners());
+            }
+            catch (error) {
+                throw new RelayUnroutableError(this.errorText(error));
+            }
+            if (!this.isEffectiveOwner(route.contact))
+                throw new Error('selected attachment relay owner is no longer authorized');
+            const contact = await this.routableContact(route);
+            const rejection = !this.attachmentRecovery.integrity()
+                ? 'attachment recovery state is unavailable'
+                : validateAttachmentSelection(group.files, this.attachmentConfig);
+            if (rejection)
+                throw new Error(rejection);
+            const transactionId = this.requestId(`managed-agent-attachment:${handledWireIds.slice().sort().join(':')}`);
+            recovery = group.recovery ?? {
+                id: transactionId, contact: agent, originWireId: captionWire ?? group.files[0].wireId,
+                fileWireIds: group.files.map(file => file.wireId), createdAt: Date.now(),
+            };
+            if (!group.recovery)
+                this.attachmentRecovery.add(recovery);
+            requestDir = await prepareAttachmentDirectory(this.attachmentRoot, transactionId);
+            const unread = group.files.filter(file => file.status === 'unread');
+            const processed = group.files.filter(file => file.status !== 'unread');
+            const retrieved = unread.length
+                ? parseRetrievedAttachments(await this.client.callTool('get_files', {
+                    wire_ids: unread.map(file => file.wireId),
+                }), unread)
+                : [];
+            for (const file of processed) {
+                if (!group.recovery)
+                    throw new Error('unexpected processed attachment without recovery route');
+                const recoveryPath = join(requestDir, `.recovered-${file.wireId}-${randomUUID()}`);
+                await this.client.callTool('save_file', { wire_id: file.wireId, dest_path: recoveryPath });
+                retrieved.push(await recoveredAttachment(file, recoveryPath));
+            }
+            const order = new Map(group.files.map((file, index) => [file.wireId, index]));
+            retrieved.sort((a, b) => order.get(a.wireId) - order.get(b.wireId));
+            const admitted = await admitAttachments(retrieved, requestDir, this.attachmentConfig);
+            const digest = createHash('sha256').update(`managed-agent-attachment\0${handledWireIds.slice().sort().join('\0')}`).digest('hex');
+            const sending = this.conversations.beginSend(route.contact, digest, Date.now(), 0, 'all');
+            try {
+                if (caption)
+                    await this.send(contact, caption, replyTo);
+                for (const file of admitted) {
+                    await this.client.callTool('send_file', {
+                        contact, path: file.path, filename: file.filename,
+                        ...(replyTo ? { reply_to_wire_id: replyTo } : {}),
+                    });
+                }
+            }
+            catch {
+                try {
+                    this.conversations.finishSend(sending.id, 'uncertain');
+                }
+                catch (error) {
+                    this.logError('managed-agent attachment uncertainty persist failed', error);
+                }
+                throw new Error('caption/file relay delivery outcome is uncertain; it was not retried');
+            }
+            this.conversations.finishSend(sending.id, 'delivered');
+            for (const wire of handledWireIds)
+                this.state.remember(wire);
+            this.attachmentRecovery.remove(recovery.id);
+            this.options.log(`[${this.options.role}] managed-agent attachment transaction relayed `
+                + `wires=${handledWireIds.length} basis=${route.basis} files=${admitted.length} `
+                + `bytes=${admitted.reduce((total, file) => total + file.size, 0)}`);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof DuplicateSendError) {
+                this.options.log(`[${this.options.role}] managed-agent attachment replay consumed`);
+                for (const wire of handledWireIds)
+                    this.state.remember(wire);
+                if (recovery)
+                    try {
+                        this.attachmentRecovery.remove(recovery.id);
+                    }
+                    catch { }
+                return true;
+            }
+            if (error instanceof RelayUnroutableError) {
+                this.options.log(`[${this.options.role}] managed-agent attachment has no owner route; `
+                    + `transaction stays queued: ${this.errorText(error)}`);
+                await this.nackManagedAgent(agent, nackMessage, nackWire, ownerNotices.relayQueued());
+                return false;
+            }
+            this.logError('managed-agent caption/file relay refused', error);
+            await this.nackManagedAgent(agent, nackMessage, nackWire, ownerNotices.relayRefused(this.errorText(error)));
+            // Rejection/admission failure and uncertain transport are terminal and
+            // visible. Consuming every correlated wire prevents a later partial replay.
+            for (const wire of handledWireIds)
+                this.state.remember(wire);
+            if (recovery)
+                try {
+                    this.attachmentRecovery.remove(recovery.id);
+                }
+                catch { }
+            return true;
+        }
+        finally {
+            if (requestDir)
+                await removeRequestDirectory(requestDir).catch(error => {
+                    this.logError('managed-agent attachment cleanup failed', error);
+                });
+        }
+    }
+    managedAttachmentReplyWire(group, captionWire) {
+        const captionReply = group.caption?.reply_to?.wire_id;
+        const candidates = new Set();
+        if (captionReply)
+            candidates.add(captionReply);
+        for (const file of group.files) {
+            const wire = file.replyTo?.wire_id;
+            if (!wire || wire === captionWire)
+                continue;
+            candidates.add(wire);
+        }
+        if (candidates.size > 1)
+            throw new Error('managed-agent caption/file group has conflicting owner reply wires');
+        return candidates.values().next().value;
+    }
     /**
      * One bounded NACK per wire: an unroutable or refused relay must be visible
      * to the authenticated agent, while its deferred replays stay quiet. NACK

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

@@ -11,7 +11,7 @@ export declare class OwnerChannelState {
     has(wireId: string): boolean;
     remember(wireId: string): void;
 }
-export type OwnerConversationRouteBasis = 'last-inbound' | 'sole-owner';
+export type OwnerConversationRouteBasis = 'last-inbound' | 'sole-owner' | 'source-wire';
 interface OwnerProactiveSend {
     id: string;
     contact: string;
@@ -28,6 +28,7 @@ interface OwnerProactiveSend {
 export declare class OwnerConversationState {
     private readonly path;
     private conversations;
+    private routes;
     private sends;
     private corruptReason?;
     constructor(path: string);
@@ -41,12 +42,17 @@ export declare class OwnerConversationState {
         contact: string;
         basis: OwnerConversationRouteBasis;
     };
+    routeForWire(wireId: string, effective: Set<string>): {
+        contact: string;
+        basis: OwnerConversationRouteBasis;
+    };
     beginSend(contact: string, digest: string, now?: number, minIntervalMs?: number, dedupe?: 'contact' | 'all'): OwnerProactiveSend;
     finishSend(id: string, status: 'delivered' | 'uncertain'): void;
     private mutate;
     private persist;
     private assertHealthy;
     private validConversation;
+    private validRoute;
     private validSend;
 }
 export type OwnerSource = 'baseline' | 'dynamic';

package/dist/owner-channel/state.js

@@ -42,6 +42,7 @@ export class OwnerChannelState {
     }
 }
 const CONVERSATION_LIMIT = 64;
+const WIRE_ROUTE_LIMIT = 512;
 const PROACTIVE_SEND_LIMIT = 256;
 const PROACTIVE_MIN_INTERVAL_MS = 30_000;
 const HEX_64_LOWER = /^[a-f0-9]{64}$/;
@@ -55,6 +56,7 @@ const CID = /^[A-Fa-f0-9]{64}$/;
 export class OwnerConversationState {
     path;
     conversations = [];
+    routes = [];
     sends = [];
     corruptReason;
     constructor(path) {
@@ -63,18 +65,29 @@ export class OwnerConversationState {
             return;
         try {
             const raw = JSON.parse(readFileSync(path, 'utf8'));
-            if (raw.version !== 1 || !Array.isArray(raw.conversations) || !Array.isArray(raw.sends)
+            const legacy = raw.version === 1;
+            const routes = legacy
+                ? (raw.conversations ?? []).map(record => ({
+                    contact: record.contact, wireId: record.lastInboundWireId, at: record.lastInboundAt,
+                }))
+                : raw.routes;
+            if (![1, 2].includes(raw.version ?? 0)
+                || !Array.isArray(raw.conversations) || !Array.isArray(routes) || !Array.isArray(raw.sends)
                 || raw.conversations.length > CONVERSATION_LIMIT
+                || routes.length > WIRE_ROUTE_LIMIT
                 || raw.sends.length > PROACTIVE_SEND_LIMIT
                 || !raw.conversations.every(record => this.validConversation(record))
+                || !routes.every(route => this.validRoute(route))
                 || !raw.sends.every(send => this.validSend(send)))
                 throw new Error('invalid or unbounded conversation state');
             if (new Set(raw.conversations.map(record => record.contact)).size !== raw.conversations.length
+                || new Set(routes.map(route => route.wireId)).size !== routes.length
                 || new Set(raw.sends.map(send => send.id)).size !== raw.sends.length)
                 throw new Error('duplicate conversation state entry');
             this.conversations = raw.conversations.map(record => ({ ...record }));
+            this.routes = routes.map(route => ({ ...route }));
             this.sends = raw.sends.map(send => ({ ...send }));
-            let recovered = false;
+            let recovered = legacy;
             for (const send of this.sends) {
                 if (send.status === 'sending') {
                     send.status = 'uncertain';
@@ -88,6 +101,7 @@ export class OwnerConversationState {
         catch {
             this.corruptReason = 'invalid persisted owner conversation state';
             this.conversations = [];
+            this.routes = [];
             this.sends = [];
             try {
                 chmodSync(path, 0o600);
@@ -118,6 +132,9 @@ export class OwnerConversationState {
                     throw new Error(`owner conversations are limited to ${CONVERSATION_LIMIT}`);
                 this.conversations.push({ contact, lastInboundAt: acceptedAt, lastInboundWireId: wireId });
             }
+            this.routes = this.routes.filter(route => route.wireId !== wireId);
+            this.routes.push({ contact, wireId, at: acceptedAt });
+            this.routes = this.routes.slice(-WIRE_ROUTE_LIMIT);
         });
     }
     remove(contact) {
@@ -127,6 +144,7 @@ export class OwnerConversationState {
             return;
         this.mutate(() => {
             this.conversations = this.conversations.filter(record => canonicalCid(record.contact) !== canonical);
+            this.routes = this.routes.filter(route => canonicalCid(route.contact) !== canonical);
         });
     }
     route(effective) {
@@ -146,6 +164,14 @@ export class OwnerConversationState {
             return { contact: [...effective][0], basis: 'sole-owner' };
         throw new Error('no authenticated owner conversation route is available yet');
     }
+    routeForWire(wireId, effective) {
+        this.assertHealthy();
+        const route = [...this.routes].reverse().find(item => item.wireId === wireId);
+        const allowed = new Set([...effective].map(canonicalCid));
+        if (!route || !allowed.has(canonicalCid(route.contact)))
+            throw new Error('no authenticated owner route matches the source wire');
+        return { contact: route.contact, basis: 'source-wire' };
+    }
     beginSend(contact, digest, now = Date.now(), minIntervalMs = PROACTIVE_MIN_INTERVAL_MS, dedupe = 'contact') {
         this.assertHealthy();
         if (!CID.test(contact) || !HEX_64_LOWER.test(digest))
@@ -177,7 +203,9 @@ export class OwnerConversationState {
         this.mutate(() => { send.status = status; });
     }
     mutate(change) {
-        const snapshot = JSON.stringify({ conversations: this.conversations, sends: this.sends });
+        const snapshot = JSON.stringify({
+            conversations: this.conversations, routes: this.routes, sends: this.sends,
+        });
         change();
         try {
             this.persist();
@@ -185,13 +213,14 @@ export class OwnerConversationState {
         catch (error) {
             const old = JSON.parse(snapshot);
             this.conversations = old.conversations;
+            this.routes = old.routes;
             this.sends = old.sends;
             throw error;
         }
     }
     persist() {
         replaceFileAtomically(this.path, JSON.stringify({
-            version: 1, conversations: this.conversations, sends: this.sends,
+            version: 2, conversations: this.conversations, routes: this.routes, sends: this.sends,
         }) + '\n', 0o600);
         chmodSync(this.path, 0o600);
     }
@@ -207,6 +236,14 @@ export class OwnerConversationState {
             && record.lastInboundAt >= 0 && typeof record.lastInboundWireId === 'string'
             && record.lastInboundWireId.length > 0 && record.lastInboundWireId.length <= 1_024;
     }
+    validRoute(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        const route = value;
+        return CID.test(route.contact) && typeof route.wireId === 'string'
+            && route.wireId.length > 0 && route.wireId.length <= 1_024
+            && Number.isSafeInteger(route.at) && route.at >= 0;
+    }
     validSend(value) {
         if (!value || typeof value !== 'object')
             return false;

package/dist/runner.d.ts

@@ -27,6 +27,8 @@ export interface RunnerDeps {
     /** Lets a test (or a shutdown path) end the supervised restart loop. */
     shouldStop?(): boolean;
 }
+/** Environment injected only into the managed harness process. */
+export declare function managedFleetProxyEnv(role: ResolvedRole, stateDir: string): Record<string, string>;
 /**
  * Record who owns wake delivery for this run. Returning true means a fleet
  * monitor is taking ownership back from a native harness and must start at the

package/dist/runner.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { parse } from 'yaml';
@@ -22,6 +22,7 @@ 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';
+import { FLEET_PROXY_CALLER_ENV, FLEET_PROXY_STATE_DIR_ENV, inheritCallerSpawnDefaults, } from './fleet-proxy.js';
 const defaultDeps = () => ({
     tmux: new Tmux(),
     exec: realExec,
@@ -54,6 +55,60 @@ const defaultDeps = () => ({
     },
 });
 const MONITOR_OWNER_FILE = '.monitor-owner';
+/** Environment injected only into the managed harness process. */
+export function managedFleetProxyEnv(role, stateDir) {
+    return {
+        ...(role.env ?? {}),
+        [FLEET_PROXY_STATE_DIR_ENV]: stateDir,
+        [FLEET_PROXY_CALLER_ENV]: role.name,
+    };
+}
+/**
+ * Execute a typed proxy request in the caller's supervisor. Dynamic imports
+ * avoid a runner↔spawn initialization cycle (spawn imports runner constants).
+ */
+async function executeManagedSpawn(caller, configPath, requested, log) {
+    const { options, inherited } = inheritCallerSpawnDefaults(caller, requested, configPath);
+    const creationActionId = randomUUID();
+    options.creationActionId = creationActionId;
+    const spawnModule = await import('./spawn.js');
+    const preview = spawnModule.spawnDryRun(options).resolvedRole;
+    const runtimeBinPath = (() => {
+        try {
+            return realpathSync(process.argv[1]);
+        }
+        catch {
+            return process.argv[1];
+        }
+    })();
+    let statePath;
+    if (options.temp) {
+        statePath = await spawnModule.spawnTemp(options, runtimeBinPath);
+    }
+    else {
+        const { pickBackend } = await import('./supervisor/index.js');
+        const { WatchdogServiceManager } = await import('./watchdog/service.js');
+        statePath = await spawnModule.spawnPermanent(options, {
+            backend: pickBackend(), binPath: runtimeBinPath, log,
+            watchdogService: new WatchdogServiceManager(),
+        });
+    }
+    const result = {
+        caller: caller.name,
+        role: options.name,
+        lifetime: options.temp ? 'temporary' : 'permanent',
+        statePath,
+        harness: preview.harness,
+        session: preview.session,
+        ...(preview.model ? { model: preview.model } : {}),
+        monitor: { mode: preview.monitor.mode, interrupt: preview.monitor.interrupt },
+        inherited,
+        creationActionId,
+    };
+    log(`[${caller.name}] managed fleet proxy spawned ${result.lifetime} role ${result.role} `
+        + `harness=${result.harness} session=${result.session}`);
+    return result;
+}
 /**
  * Record who owns wake delivery for this run. Returning true means a fleet
  * monitor is taking ownership back from a native harness and must start at the
@@ -435,6 +490,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     let acpStartupComplete = false;
     let ownerChannel;
     let ownerBinder;
+    const pendingFleetSpawnNotices = [];
     let loopManager;
     let arbiter;
     let reloadLoopConfig;
@@ -453,7 +509,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             name,
             argv: wrappedArgv,
             cwd: runCwd,
-            env: { ...launch.env, ...(role.env ?? {}) },
+            env: { ...launch.env, ...managedFleetProxyEnv(role, dir) },
             stateDir: dir,
             mode,
             permissions: perms,
@@ -501,6 +557,23 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             unsubscribeRecovery?.();
             throw error;
         }
+        control.setFleetSpawner(async (requested) => {
+            const event = await executeManagedSpawn(role, configPath, requested, deps.log);
+            if (!role.owner_channel)
+                return event;
+            if (ownerChannel?.notifyFleetSpawn) {
+                try {
+                    await ownerChannel.notifyFleetSpawn(event);
+                }
+                catch (error) {
+                    deps.log(`[${name}] spawned-agent owner notice failed: `
+                        + `${error?.message ?? String(error)}`);
+                }
+            }
+            else
+                pendingFleetSpawnNotices.push(event);
+            return event;
+        });
         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
@@ -589,6 +662,15 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 throw new Error(`[${name}] owner channel failed to start: `
                     + `${error?.message ?? String(error)}`);
             }
+            for (const event of pendingFleetSpawnNotices.splice(0)) {
+                try {
+                    await ownerChannel.notifyFleetSpawn?.(event);
+                }
+                catch (error) {
+                    deps.log(`[${name}] deferred spawned-agent owner notice failed: `
+                        + `${error?.message ?? String(error)}`);
+                }
+            }
         }
         if (ownerChannel)
             control.setOwnerChannel(ownerChannel);

package/dist/session/control.d.ts

@@ -2,11 +2,13 @@ import { type Socket } from 'node:net';
 import type { ControlFailureKind, SessionHandle } from './types.js';
 import type { OwnerChannelHandle, OwnerChannelManagementRequest } from '../owner-channel/channel.js';
 import type { ScheduledLoopManagerHandle } from '../loops/manager.js';
+import type { SpawnOpts } from '../spawn.js';
+import type { ManagedFleetSpawnResult } from '../fleet-proxy.js';
 export interface ControlRequest {
     version: 1 | 2;
     id: string;
     token: string;
-    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config';
+    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config' | 'fleet_spawn';
     text?: string;
     permissionId?: string;
     optionId?: string;
@@ -15,6 +17,7 @@ export interface ControlRequest {
     controller?: boolean;
     ownerChannel?: OwnerChannelManagementRequest;
     loop?: string;
+    spawn?: SpawnOpts;
 }
 export interface ControlResponse {
     version: 1;
@@ -78,6 +81,7 @@ export declare class RoleControlServer {
     private ownerChannel?;
     private loopManager?;
     private reloadConfig?;
+    private fleetSpawner?;
     constructor(stateDir: string, session: SessionHandle, log: (line: string) => void);
     start(): Promise<void>;
     close(): Promise<void>;
@@ -85,6 +89,7 @@ export declare class RoleControlServer {
     setOwnerChannel(ownerChannel: OwnerChannelHandle | undefined): void;
     setLoopManager(loopManager: ScheduledLoopManagerHandle | undefined): void;
     setConfigReloader(reloadConfig: (() => Promise<unknown>) | undefined): void;
+    setFleetSpawner(fleetSpawner: ((options: SpawnOpts) => Promise<ManagedFleetSpawnResult>) | undefined): void;
     private accept;
     private handle;
     private write;

package/dist/session/control.js

@@ -98,6 +98,7 @@ export class RoleControlServer {
     ownerChannel;
     loopManager;
     reloadConfig;
+    fleetSpawner;
     constructor(stateDir, session, log) {
         this.session = session;
         this.log = log;
@@ -140,6 +141,9 @@ export class RoleControlServer {
     setConfigReloader(reloadConfig) {
         this.reloadConfig = reloadConfig;
     }
+    setFleetSpawner(fleetSpawner) {
+        this.fleetSpawner = fleetSpawner;
+    }
     accept(socket) {
         this.sockets.add(socket);
         socket.setEncoding('utf8');
@@ -271,6 +275,15 @@ export class RoleControlServer {
                     });
                     return;
                 }
+                case 'fleet_spawn': {
+                    if (request.version !== 2 || !request.spawn || typeof request.spawn.name !== 'string')
+                        throw new SessionControlError('rejected', 'version 2 and typed spawn options are required');
+                    if (!this.fleetSpawner)
+                        throw new SessionControlError('rejected', 'managed fleet spawning is unavailable for this role');
+                    const result = await this.fleetSpawner(request.spawn);
+                    this.write(socket, { version: 1, id: request.id, ok: true, result });
+                    return;
+                }
                 case 'owner_channel_manage': {
                     if (!request.ownerChannel || typeof request.ownerChannel.action !== 'string')
                         throw new SessionControlError('rejected', 'owner-channel management action is required');

package/dist/spawn.d.ts

@@ -40,8 +40,12 @@ export interface SpawnOpts {
     bio?: string;
     persona?: string;
     /** Internal, non-sensitive provenance correlation for typed presentation layers. */
-    surface?: 'cli' | 'web';
+    surface?: 'cli' | 'web' | 'agent';
     creationActionId?: string;
+    /** Set only by a live role supervisor after a role-scoped proxy request. */
+    callerRole?: string;
+    /** Internal provenance labels for values filled by the caller's supervisor. */
+    inheritedFromCaller?: string[];
     /**
      * Path to a file holding exactly the existing `isolation:` mapping — the same
      * schema fleet.yaml uses, not a second policy language. The ONE new operator

package/dist/spawn.js

@@ -238,29 +238,31 @@ export function spawnDryRun(o) {
  */
 function provenanceSettings(o, defaults) {
     const perms = (defaults.permissions ?? {});
+    const callerDefaults = new Set(o.inheritedFromCaller ?? []);
+    const tagged = (key, entry) => callerDefaults.has(key) ? { ...entry, source: 'caller-role' } : entry;
     const explicitModel = typeof o.model === 'string' ? o.model.trim() : undefined;
     const inheritedModel = resolveRoleModel(undefined, o.harness, defaults);
     return {
-        harness: provenanceOf(o.harness, defaults.harness, 'claude-code'),
-        session: provenanceOf(o.session, defaults.session, 'tmux'),
+        harness: tagged('harness', provenanceOf(o.harness, defaults.harness, 'claude-code')),
+        session: tagged('session', provenanceOf(o.session, defaults.session, 'tmux')),
         identity: o.identity
             ? { value: o.identity, source: 'cli' }
             : { value: o.name, source: 'built-in' }, // defaults to the role name
-        cwd: provenanceOf(o.cwd, undefined, undefined),
-        model: o.model === null
+        cwd: tagged('cwd', provenanceOf(o.cwd, undefined, undefined)),
+        model: tagged('model', o.model === null
             ? { value: undefined, source: 'cli' }
             : explicitModel
                 ? { value: explicitModel, source: 'cli' }
-                : { value: inheritedModel, source: inheritedModel ? 'fleet-default' : 'built-in' },
-        coordinator: provenanceOf(o.coordinator, undefined, undefined),
+                : { value: inheritedModel, source: inheritedModel ? 'fleet-default' : 'built-in' }),
+        coordinator: tagged('coordinator', provenanceOf(o.coordinator, undefined, undefined)),
         permission_mode: provenanceOf(o.permissionMode, undefined, undefined),
-        approval: provenanceOf(o.approval, perms.approval, 'ask'),
-        filesystem: provenanceOf(o.filesystem, perms.filesystem, 'workspace'),
-        unattended: provenanceOf(o.unattended, perms.unattended, 'deny'),
+        approval: tagged('approval', provenanceOf(o.approval, perms.approval, 'ask')),
+        filesystem: tagged('filesystem', provenanceOf(o.filesystem, perms.filesystem, 'workspace')),
+        unattended: tagged('unattended', provenanceOf(o.unattended, perms.unattended, 'deny')),
         isolation: o.isolationFile
             ? { value: 'declared via --isolation-file', source: 'cli' }
             : { value: defaults.isolation ? 'from fleet defaults' : undefined, source: defaults.isolation ? 'fleet-default' : 'built-in' },
-        monitor: provenanceOf(o.monitorConfig, defaults.monitor, { mode: 'fleet' }),
+        monitor: tagged('monitorConfig', provenanceOf(o.monitorConfig, defaults.monitor, { mode: 'fleet' })),
     };
 }
 /** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
@@ -324,7 +326,7 @@ export async function spawnPermanent(o, deps, creation = {}) {
         const provenance = buildProvenance({
             role: o.name, lifetime: 'permanent', fleetVersion: VERSION,
             settings: provenanceSettings(o, cfg.defaults),
-            surface: o.surface, creationActionId: o.creationActionId,
+            surface: o.surface, creationActionId: o.creationActionId, callerRole: o.callerRole,
         });
         mkdirSync(agentDir(o.name), { recursive: true });
         writeProvenance(agentDir(o.name), provenance);
@@ -414,7 +416,7 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
     const provenance = buildProvenance({
         role: o.name, lifetime: 'temporary', fleetVersion: VERSION,
         settings: provenanceSettings(o, cfg.defaults),
-        surface: o.surface, creationActionId: o.creationActionId,
+        surface: o.surface, creationActionId: o.creationActionId, callerRole: o.callerRole,
     });
     writeProvenance(dir, provenance);
     lastProvenance = provenance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "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",