@ours.network/fleet 0.10.0-nightly.3 → 0.10.0

package/dist/creation.js

@@ -0,0 +1,254 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically, withFileLock } from './atomic-file.js';
+import { stateRoot } from './paths.js';
+import { resolveEndpoint } from './monitor.js';
+/**
+ * One creation transaction: role name and ours identity reserved together,
+ * every artifact journalled, and everything undone in reverse on failure.
+ *
+ * The problem this replaces is a check followed by a create. `assertNameFree()`
+ * read the config and the agent dirs, returned, and only then did the caller
+ * start writing — so two concurrent spawns of the same name both passed the
+ * check, both wrote, and the second silently overwrote the first's fleet.d file
+ * while inheriting its half-built state. Nothing was atomic and nothing was
+ * undone.
+ */
+/** Where host-wide creation state lives. One directory, so it is easy to inspect. */
+const creationRoot = () => join(stateRoot(), 'creation');
+const creationLock = () => join(creationRoot(), '.lock');
+const reservationsDir = () => join(creationRoot(), 'reservations');
+/** A reservation is one file; its existence IS the claim. */
+const reservationPath = (kind, name) => join(reservationsDir(), `${kind}-${encodeURIComponent(name)}`);
+export class CreationConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CreationConflictError';
+    }
+}
+/**
+ * Host-local identity reservation: atomic across every ours-fleet process on
+ * this host, because it is taken under the same host-wide creation lock as the
+ * role name.
+ *
+ * It is NOT atomic against other clients of the same ours daemon — another tool
+ * creating the identity between our reservation and our creation would still
+ * win. Closing that needs a reserve/commit/release operation in the daemon
+ * itself; see the release notes.
+ */
+export const hostLocalIdentityRegistry = {
+    async reserve(name) {
+        const p = reservationPath('identity', name);
+        if (existsSync(p))
+            return false;
+        mkdirSync(reservationsDir(), { recursive: true });
+        writeFileSync(p, `${process.pid} ${new Date().toISOString()}\n`);
+        return true;
+    },
+    async release(name) {
+        rmSync(reservationPath('identity', name), { force: true });
+    },
+};
+/** Is this role name already reserved by an in-flight transaction? */
+const roleReserved = (name) => existsSync(reservationPath('role', name));
+/**
+ * Run `body` inside a creation transaction.
+ *
+ * Under one host-wide lock: both names are reserved, then `body` builds the
+ * role. If anything throws, every recorded stage is undone in reverse order and
+ * both reservations are released, so the names can be reused immediately. On
+ * success the reservations are released too — the role's own config and state
+ * are the durable record from then on.
+ *
+ * Rollback errors are collected and reported, never allowed to hide the failure
+ * that caused the rollback.
+ */
+export async function withCreationTransaction(names, body, deps = {}) {
+    const log = deps.log ?? (() => { });
+    const registry = deps.identityRegistry ?? hostLocalIdentityRegistry;
+    mkdirSync(creationRoot(), { recursive: true });
+    const journal = [];
+    const tx = {
+        record: entry => { journal.push(entry); },
+        get stages() { return journal.map(e => e.stage); },
+    };
+    // Both names, one boundary. Reserving the role and then the identity without
+    // a shared lock would let two spawns each win one.
+    const held = await withFileLock(creationLock(), async () => {
+        if (roleReserved(names.role))
+            throw new CreationConflictError(`role '${names.role}' is being created by another process right now`);
+        if (!await registry.reserve(names.identity))
+            throw new CreationConflictError(`ours identity '${names.identity}' is already taken or being created right now`);
+        mkdirSync(reservationsDir(), { recursive: true });
+        writeFileSync(reservationPath('role', names.role), `${process.pid} ${new Date().toISOString()}\n`);
+        return true;
+    }, deps.lock);
+    if (!held)
+        throw new CreationConflictError('could not take the creation lock');
+    const releaseAll = async () => {
+        rmSync(reservationPath('role', names.role), { force: true });
+        await registry.release(names.identity).catch(() => undefined);
+    };
+    try {
+        const result = await body(tx);
+        await releaseAll();
+        return result;
+    }
+    catch (error) {
+        const rollbackFailures = [];
+        for (const entry of [...journal].reverse()) {
+            try {
+                await entry.undo();
+            }
+            catch (e) {
+                rollbackFailures.push(`${entry.stage}: ${e.message}`);
+            }
+        }
+        await releaseAll();
+        const original = error instanceof Error ? error : new Error(String(error));
+        if (rollbackFailures.length) {
+            log(`creation rollback incomplete: ${rollbackFailures.join('; ')}`);
+            original.message += ` (rollback also failed: ${rollbackFailures.join('; ')})`;
+        }
+        throw original;
+    }
+}
+/** Forget reservations left behind by a process that died mid-transaction. */
+export function clearStaleReservations(olderThanMs = 60_000, now = Date.now()) {
+    const dir = reservationsDir();
+    if (!existsSync(dir))
+        return 0;
+    let cleared = 0;
+    for (const f of readdirSyncSafe(dir)) {
+        const p = join(dir, f);
+        try {
+            const stamp = Date.parse(readFileSync(p, 'utf8').trim().split(/\s+/)[1] ?? '');
+            if (Number.isFinite(stamp) && now - stamp > olderThanMs) {
+                rmSync(p, { force: true });
+                cleared++;
+            }
+        }
+        catch { /* unreadable: leave it for a human */ }
+    }
+    return cleared;
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Establish the identity before the role's service is enabled.
+ *
+ * Returns what was actually GUARANTEED, so the generated briefing can say
+ * something true instead of asserting a "predefined" identity nobody checked —
+ * the failure a real agent hit on its first boot, having been told to bind an
+ * identity that did not exist.
+ */
+export async function ensureIdentity(name, profile, provisioner, log = () => { }) {
+    if (!provisioner)
+        return { state: 'unverified', detail: 'no identity provisioner is configured' };
+    let present;
+    try {
+        present = await provisioner.exists(name);
+    }
+    catch (e) {
+        present = 'unknown';
+        log(`identity '${name}': could not be verified (${e.message})`);
+    }
+    if (present === true)
+        return { state: 'verified', detail: 'the ours daemon reports it exists' };
+    if (present === 'unknown')
+        return { state: 'unverified', detail: 'the ours daemon could not be asked' };
+    if (!provisioner.create) {
+        // Loud, and named. The briefing will tell the agent to mint it — which is
+        // what actually happens today — but nobody is told it was "predefined".
+        log(`identity '${name}' does not exist and this host cannot create one automatically — `
+            + `the role will be told to mint it on first boot. Create it in advance to avoid that.`);
+        return { state: 'unverified', detail: 'it does not exist and cannot be created here' };
+    }
+    await provisioner.create(name, profile);
+    return { state: 'created', detail: 'created during spawn, with its bio and persona published' };
+}
+/**
+ * Ask the running ours daemon whether an identity exists, over the same
+ * authenticated endpoint doctor already probes. Answers `unknown` rather than
+ * guessing when the daemon cannot be reached — an unreachable daemon is not
+ * evidence that the identity is missing.
+ *
+ * It deliberately has no `create()`: role identities are minted through the MCP
+ * `create_identity` tool, and inventing a daemon endpoint we cannot test is the
+ * failure mode this release exists to stop.
+ */
+export function daemonIdentityProvisioner(env = process.env, fetchImpl = (u, i) => globalThis.fetch(u, i)) {
+    return {
+        async exists(name) {
+            const ep = resolveEndpoint(env);
+            const resp = await fetchImpl(`${ep.origin}/identities`, { headers: ep.headers });
+            if (!resp.ok)
+                return 'unknown';
+            const body = await resp.json();
+            if (!Array.isArray(body.identities))
+                return 'unknown';
+            return body.identities.some(i => (typeof i === 'string' ? i : i?.name) === name);
+        },
+    };
+}
+/** Atomically write a role's fleet.d file, journalling it for rollback. */
+export function writeRoleFile(tx, file, contents) {
+    const existed = existsSync(file);
+    replaceFileAtomically(file, contents, 0o644);
+    tx.record({
+        stage: `fleet.d file ${file}`,
+        // Only remove what THIS transaction created; never delete a file the
+        // operator already had.
+        undo: () => { if (!existed)
+            rmSync(file, { force: true }); },
+    });
+}
+export const CREATION_PROVENANCE_FILE = 'creation.json';
+/**
+ * Record HOW a role was created, so nobody has to remember.
+ *
+ * Six months on, "why does this role have `approval: allow`?" is unanswerable:
+ * the resolved config shows the value but not whether an operator typed it, a
+ * fleet default supplied it, or it fell through to a built-in. Those have very
+ * different implications for whether it is safe to change.
+ *
+ * Deliberately excluded: `env`, `bio`, `persona`, and `harness_options`. The
+ * first two can carry credentials, and this file exists to be read — it must
+ * never become a place secrets accumulate.
+ */
+export function buildProvenance(o) {
+    return {
+        version: 1,
+        command: 'ours-fleet spawn',
+        fleetVersion: o.fleetVersion,
+        createdAt: (o.now ?? new Date()).toISOString(),
+        lifetime: o.lifetime,
+        role: o.role,
+        settings: o.settings,
+    };
+}
+/** Write the provenance record atomically, before the role is started. */
+export function writeProvenance(stateDir, p) {
+    replaceFileAtomically(join(stateDir, CREATION_PROVENANCE_FILE), JSON.stringify(p, null, 2) + '\n', 0o600);
+}
+/** 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' };
+    return Object.entries(p.settings)
+        .filter(([, e]) => e.value !== undefined)
+        .map(([k, e]) => `    ${k.padEnd(12)} ${String(e.value)}  (${mark[e.source]})`);
+}
+/** Classify one setting: an explicit CLI value, a fleet default, or built-in. */
+export function provenanceOf(cliValue, fleetDefault, builtIn) {
+    if (cliValue !== undefined && cliValue !== null && cliValue !== '')
+        return { value: cliValue, source: 'cli' };
+    if (fleetDefault !== undefined && fleetDefault !== null)
+        return { value: fleetDefault, source: 'fleet-default' };
+    return { value: builtIn, source: 'built-in' };
+}

package/dist/docs.d.ts

@@ -4,4 +4,31 @@
  * 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\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## Spawn\n\n```sh\nours-fleet spawn [--temp] Name \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and `--monitor`. Run `ours-fleet help spawn` for exact 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    enabled: true\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      enabled: true\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 }\n```\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\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\nThe supervisor monitor is enabled by default. It consumes body-free daemon\nevents and advances its durable cursor only after delivery is accepted. ACP uses\na structured `session/prompt`; tmux uses verified console injection. Message\nbodies are released only when the role calls the ours `get_messages` tool.\n\nSet `monitor.enabled: false` only to retain legacy in-session monitoring.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\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\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## Spawn\n\n```sh\nours-fleet spawn [--temp] Name \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and legacy `--monitor` (consent for the native Codex monitor,\nnot the `monitor.mode` wake-owner selector). Run `ours-fleet help spawn` for\nexact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      mode: fleet                        # fleet supervisor | native harness monitor\n      interrupt: false                    # true cancels active work before every configured wake\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\n```\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\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";
+/**
+ * What every shipped spawn-skill variant must say, and must not say (7.1).
+ *
+ * The skills are separate markdown files in two published plugins, written for
+ * two different harnesses, so they cannot literally be one file. This is the
+ * source of truth they are all written from, and a test holds each variant to
+ * it — including the CLI reference above, so a skill and \`ours-fleet docs\`
+ * cannot name different permission settings.
+ *
+ * \`forbidden\` is the more important half. The old skills prescribed
+ * \`--approval ask --filesystem workspace --unattended deny\` as a blanket
+ * default while also telling the agent to stop at a failed doctor check — and
+ * that combination is exactly what \`doctor\` FAILS, because \`ask\` grants an
+ * unattended role nothing but \`read-state\` and \`deny\` makes the shortfall
+ * fatal. Following the skill produced a role the CLI then refused.
+ */
+export declare const SPAWN_SKILL_CONTRACT: {
+    /** Substrings every variant must contain (whitespace-normalised). */
+    readonly required: readonly ["ours-fleet docs", "ours-fleet doctor", "dontAsk", "bypassPermissions", "unattended capability floor", "unattended floor:", "--approval allow", "--unattended wait", "--isolation-file"];
+    /**
+     * Substrings no variant may contain. Deliberately short: the real guard is
+     * the acceptance test, which runs every spawn command a variant prints
+     * through the same analysis `doctor` uses and fails if doctor would fail it.
+     * This list only pins the specific claim that was wrong.
+     */
+    readonly forbidden: readonly ["--approval ask --filesystem workspace --unattended deny", "[TODO:"];
+};

package/dist/docs.js

@@ -64,7 +64,9 @@ role after exit/reboot. Both lifetimes support \`--session acp\`.
 
 Codex-specific spawn flags: \`--sandbox\`, \`--permission-mode\`, \`--launcher\`,
 \`--profile\`, \`--search\`, repeatable \`--codex-config key=value\`, repeatable
-\`--add-dir\`, and \`--monitor\`. Run \`ours-fleet help spawn\` for exact values.
+\`--add-dir\`, and legacy \`--monitor\` (consent for the native Codex monitor,
+not the \`monitor.mode\` wake-owner selector). Run \`ours-fleet help spawn\` for
+exact values.
 
 ## fleet.yaml
 
@@ -81,7 +83,7 @@ defaults:
     filesystem: workspace
     unattended: deny
   monitor:
-    enabled: true
+    mode: fleet                          # fleet (default) | native
 roles:
   Coordinator:
     harness: codex
@@ -100,7 +102,8 @@ roles:
       tmux:
         boot_grace_ms: 10000
     monitor:
-      enabled: true
+      mode: fleet                        # fleet supervisor | native harness monitor
+      interrupt: false                    # true cancels active work before every configured wake
       wake_sources: [message_received, file_received, local_contact_request, pending_message]
       batch_ms: 2000
       inject: notification
@@ -141,6 +144,89 @@ The backend translates this common intent. Harness-native settings in
 \`allow\`/\`unrestricted\`, Codex \`never\`/\`danger-full-access\`, or Claude
 \`bypassPermissions\` without explicit authorization.
 
+### Creation-time isolation
+
+\`ours-fleet spawn --isolation-file <path>\` supplies a role's sandbox policy at
+creation, so the FIRST launch is already confined — a role that only gains
+\`isolation:\` on a later \`up\` ran unsandboxed until then.
+
+The file holds exactly the \`isolation:\` mapping documented above and nothing
+else — the same schema, validated by the same code, so a policy written here
+cannot mean something different from the identical block in fleet.yaml:
+
+\`\`\`yaml
+network: deny
+fs:
+  read: [/opt/reference]
+resources:
+  mem: 2G
+\`\`\`
+
+Invalid files are rejected before anything is created: no config, no state
+directory, no identity reservation. Works for both permanent and \`--temp\` roles.
+
+### Never-prompt failure
+
+The failure this section exists to prevent leaves no error message anywhere.
+
+An unattended role has no console. When the harness needs a permission decision
+there is nobody to ask, so the request is refused INSIDE the harness — no
+prompt, no error, no log line. The agent simply does less than its briefing told
+it to, reports success, and nothing distinguishes that from having done the
+work. Two settings produce it:
+
+1. a permission mode that suppresses the prompt without granting the action
+   (Claude \`dontAsk\`, which is why neutral \`allow\` maps to
+   \`bypassPermissions\` instead); and
+2. \`unattended: deny\`, which refuses every request that reaches it.
+
+**Automatic decisions are now recorded.** Every permission request decided
+without a human emits a completed event into
+\`~/.ours-fleet/agents/<Name>/.session-events.jsonl\` carrying the decision,
+whether policy or a person made it, the policy that produced it
+(\`permissions.unattended=deny\` vs \`permissions.approval=deny\`/\`=allow\`),
+the reason, and the option selected. \`ours-fleet peek\` and \`attach\` render
+them. Automatic denial asks for a one-shot rejection, never a standing one, so a
+single unattended refusal cannot disable a tool for the rest of the session.
+
+A role that can auto-deny logs one line at startup saying so.
+
+To detect an under-permissioned role BEFORE it runs, use the capability floor
+below: \`ours-fleet doctor\` fails such a role rather than letting it discover
+the problem silently at work.
+
+### The unattended capability floor
+
+An unattended role has no console, so a permission request cannot be answered —
+it is refused, silently, inside the harness. The agent then does less than it
+was told to and reports no error. To make that visible before launch,
+\`ours-fleet config\` and \`ours-fleet doctor\` resolve each role's neutral
+permissions through its harness and check the result against a fixed floor:
+
+- \`read-state\` — read its briefing, ROUTINES.md, and WORKLOG.md
+- \`write-state\` — append its WORKLOG and its own state files
+- \`messaging\` — bind its identity, send and receive ours mail
+- \`monitor\` — arm and observe its mail monitor
+- \`workspace-edit\` — edit and test files in its working directory
+- \`status-commands\` — run the inspection commands its briefing prescribes
+
+\`doctor\` reports this per role as \`unattended floor: <Role>\`. A role with
+\`unattended: deny\` that cannot meet the floor FAILS doctor, because it will
+deny those requests with nobody to see it; with \`unattended: wait\` it warns,
+because a human can still attach and answer.
+
+Security meaning: \`approval: allow\` maps to Claude's \`bypassPermissions\`,
+which genuinely permits the actions the role was authorized to take —
+\`dontAsk\` only suppresses the prompt while still refusing the action. Nothing
+other than an explicit \`allow\` is elevated: \`ask\` stays on Claude's default
+mode and \`deny\` maps to \`plan\`. \`allow\` is therefore a real grant and
+requires explicit authorization; per-role \`isolation:\` remains the outer
+boundary that a permission mode cannot cross.
+
+See also: \`spawn --approval/--filesystem/--unattended\` set this intent at
+creation, and \`ours-fleet config\` prints each role's neutral settings, their
+native translation, and any warning — the same text \`doctor\` reports.
+
 Claude \`harness_options\`: \`permission_mode\` (default, acceptEdits, plan,
 dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`, and
 \`mem_palace_midsession_autosave\`.
@@ -166,12 +252,73 @@ ours-fleet falls back to a compatible globally installed \`codex-acp\` or
 
 ## Reliable mail wake
 
-The supervisor monitor is enabled by default. It consumes body-free daemon
-events and advances its durable cursor only after delivery is accepted. ACP uses
-a structured \`session/prompt\`; tmux uses verified console injection. Message
-bodies are released only when the role calls the ours \`get_messages\` tool.
+\`monitor.mode\` selects exactly one wake owner:
 
-Set \`monitor.enabled: false\` only to retain legacy in-session monitoring.
+- \`fleet\` (default): the ours-fleet supervisor consumes body-free daemon
+  events and advances its durable cursor only after delivery is accepted. ACP
+  uses live steering when supported and falls back to structured
+  \`session/prompt\`; tmux uses verified console injection.
+- \`native\`: ours-fleet starts no supervisor monitor; the generated briefing
+  instructs Claude Code or Codex to arm its harness-native wake mechanism.
+
+Set \`monitor.interrupt: true\` in fleet mode to cancel active work before every
+configured wake. The policy is content-blind because the supervisor cannot
+inspect encrypted message bodies. Message bodies are released only when the
+role calls the ours \`get_messages\` tool.
+
+Legacy \`monitor.enabled: true|false\` remains accepted as an alias for
+\`mode: fleet|native\`; use \`mode\` in new configuration. Codex's separate
+\`harness_options.monitor: true\` is native-monitor consent, not monitor-owner
+selection.
 Inspect \`ours-fleet status Name\`, \`peek Name\`, role logs, and
 \`~/.ours-fleet/agents/Name/.monitor-status\` when diagnosing delivery.
 `;
+/**
+ * What every shipped spawn-skill variant must say, and must not say (7.1).
+ *
+ * The skills are separate markdown files in two published plugins, written for
+ * two different harnesses, so they cannot literally be one file. This is the
+ * source of truth they are all written from, and a test holds each variant to
+ * it — including the CLI reference above, so a skill and \`ours-fleet docs\`
+ * cannot name different permission settings.
+ *
+ * \`forbidden\` is the more important half. The old skills prescribed
+ * \`--approval ask --filesystem workspace --unattended deny\` as a blanket
+ * default while also telling the agent to stop at a failed doctor check — and
+ * that combination is exactly what \`doctor\` FAILS, because \`ask\` grants an
+ * unattended role nothing but \`read-state\` and \`deny\` makes the shortfall
+ * fatal. Following the skill produced a role the CLI then refused.
+ */
+export const SPAWN_SKILL_CONTRACT = {
+    /** Substrings every variant must contain (whitespace-normalised). */
+    required: [
+        // The installed reference is authoritative and must actually be read.
+        'ours-fleet docs',
+        'ours-fleet doctor',
+        // Trap 1: a mode that suppresses the prompt without granting the action.
+        'dontAsk',
+        'bypassPermissions',
+        // Trap 2: the floor, and the command that reports it before launch.
+        'unattended capability floor',
+        'unattended floor:',
+        // The only intent that clears the floor, and the honest alternative.
+        '--approval allow',
+        '--unattended wait',
+        // Creation-time isolation (6.3) — the one new operator input this release adds.
+        '--isolation-file',
+    ],
+    /**
+     * Substrings no variant may contain. Deliberately short: the real guard is
+     * the acceptance test, which runs every spawn command a variant prints
+     * through the same analysis `doctor` uses and fails if doctor would fail it.
+     * This list only pins the specific claim that was wrong.
+     */
+    forbidden: [
+        // The contradictory blanket default both variants used to prescribe.
+        // `ask` grants an unattended role only `read-state`, and `deny` makes the
+        // shortfall a doctor FAILURE — so the skill told you to build a role the
+        // CLI then refused, in the same breath as telling you to trust doctor.
+        '--approval ask --filesystem workspace --unattended deny',
+        '[TODO:',
+    ],
+};

package/dist/doctor.js

@@ -1,10 +1,11 @@
 import { userInfo } from 'node:os';
 import { readFileSync } from 'node:fs';
 import { realExec } from './exec.js';
-import { loadConfig } from './config.js';
-import { getAdapter } from './harness/registry.js';
+import { isolationContextFor, loadConfig } from './config.js';
+import { getAdapter, productionAdapters } from './harness/registry.js';
+import { analyzeFleetPermissions, formatNative } from './permissions.js';
 import { resolveBundledAcpAgent } from './harness/acp-agent.js';
-import { agentDir, home, deriveXdgRuntimeDir } from './paths.js';
+import { deriveXdgRuntimeDir } from './paths.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { makeBubblewrapBackend } from './isolation/bubblewrap.js';
 import { authResolutionHint, resolveEndpoint, } from './monitor.js';
@@ -24,7 +25,7 @@ function cgroupDelegationDetail() {
 /** Resolve and deduplicate the effective daemon profiles used by monitored roles. */
 function resolveMonitorProfiles(roles) {
     const profiles = [];
-    for (const role of roles.filter(r => r.monitor?.enabled)) {
+    for (const role of roles.filter(r => r.monitor?.mode === 'fleet')) {
         const endpoint = resolveEndpoint({ ...process.env, ...(role.env ?? {}) });
         const token = endpoint.headers['x-ours-api-token'];
         const existing = profiles.find(p => p.endpoint.origin === endpoint.origin
@@ -44,7 +45,17 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         name: 'node', ok: major >= 20,
         detail: major >= 20 ? `v${process.versions.node}` : `v${process.versions.node} — need >= 20`,
     });
-    const roles = loadConfigSafe(opts.configPath);
+    // The configuration is a checked prerequisite in its own right. A config the
+    // `config` command rejects must fail here too, with the same cause — while the
+    // host checks below still run, because they are what the operator needs next.
+    const loaded = loadConfigResult(opts.configPath);
+    const roles = loaded.ok ? loaded.roles : [];
+    checks.push(loaded.ok
+        ? { name: 'config', ok: true, detail: loaded.files.join(' + ') || '(none — no fleet.yaml or fleet.d)' }
+        : { name: 'config', ok: false, detail: loaded.error });
+    checks.push(loaded.ok
+        ? { name: 'roles', ok: true, detail: `${roles.length} configured` }
+        : { name: 'roles', ok: false, detail: 'unknown — the configuration did not load' });
     if (roles.length === 0 || roles.some(role => (role.session ?? 'tmux') === 'tmux')) {
         const tmux = await exec('tmux', ['-V']);
         checks.push({
@@ -84,6 +95,45 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 : `no XDG_RUNTIME_DIR and /run/user/<uid> missing — systemctl --user cannot reach the user manager; enable linger: sudo loginctl enable-linger ${user}`,
         });
     }
+    // Per-role permission translation (2.3). Rendered from the same analysis the
+    // `config` command prints, so the two commands cannot disagree.
+    for (const analysis of analyzeFleetPermissions(roles)) {
+        if (!analysis.supported) {
+            checks.push({
+                name: `permissions: ${analysis.role}`, ok: false,
+                detail: analysis.warnings.join('; '),
+            });
+            continue;
+        }
+        const p = analysis.permissions;
+        const summary = `approval=${p.approval} filesystem=${p.filesystem} unattended=${p.unattended}`
+            + ` -> ${formatNative(analysis.native)}`;
+        checks.push({
+            name: `permissions: ${analysis.role}`, ok: true,
+            detail: analysis.warnings.length
+                ? `${summary} — ${analysis.warnings.join('; ')}`
+                : `${summary} (exact)`,
+        });
+        // A role that states its permission intent twice, in two disagreeing places
+        // (2.4). Quiet when there is a single source of intent.
+        for (const conflict of analysis.conflicts ?? [])
+            checks.push({
+                name: `permission conflict: ${analysis.role}`, ok: true, detail: conflict.warning,
+            });
+        // The floor is checked BEFORE start (2.1): an under-permissioned unattended
+        // role never reports its own failure, because the denial happens inside the
+        // harness with nobody attached to see it.
+        const floor = analysis.floor;
+        checks.push({
+            name: `unattended floor: ${analysis.role}`,
+            ok: floor.meets || analysis.floorSeverity !== 'fail',
+            detail: floor.meets
+                ? `grants ${analysis.capabilities.join(', ')}`
+                : `MISSING ${floor.missing.join(', ')} — with unattended=${p.unattended} these requests will `
+                    + `${p.unattended === 'deny' ? 'be denied silently' : 'block the turn'}; `
+                    + `grants only ${analysis.capabilities.join(', ') || '(nothing)'}`,
+        });
+    }
     // Isolation reporting (AC-9). Backend availability is advisory — isolation is
     // opt-in per role (OQ-1), so a missing bwrap must not fail doctor for fleets that
     // don't use it. Only a role that DECLARES isolation and cannot get it under
@@ -98,13 +148,15 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     if (platform === 'linux')
         checks.push({ name: 'isolation: cgroup delegation', ok: true, detail: cgroupDelegationDetail() });
     for (const r of roles.filter(r => r.isolation)) {
-        const stateDir = agentDir(r.name);
-        const policy = resolveIsolation(r.isolation, {
-            stateDir, runCwd: r.cwd ?? stateDir, home: home(), harness: r.harness,
-            additionalWriteDirs: r.harness === 'codex'
-                ? (r.harness_options?.add_dirs ?? [])
-                : [],
-        });
+        // A refused mount is a launch-blocking policy error (5.2), not a warning.
+        let policy;
+        try {
+            policy = resolveIsolation(r.isolation, isolationContextFor(r));
+        }
+        catch (e) {
+            checks.push({ name: `isolation: ${r.name}`, ok: false, detail: e.message });
+            continue;
+        }
         const caps = [
             policy.resources.mem && `mem=${policy.resources.mem}`,
             policy.resources.cpu && `cpu=${policy.resources.cpu}`,
@@ -160,9 +212,14 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         }
         checks.push({ name: checkName, ok, detail });
     }
+    // A broken config resolves no roles and therefore no harnesses. Without a
+    // fallback the AI CLI prerequisites would simply vanish from the report at
+    // exactly the moment the operator is trying to work out what is wrong.
     const harnesses = opts.harness
         ? [opts.harness]
-        : [...new Set(roles.map(r => r.harness))];
+        : loaded.ok
+            ? [...new Set(roles.map(r => r.harness))]
+            : productionAdapters();
     for (const h of harnesses) {
         try {
             const rep = await getAdapter(h).checkPrereqs();
@@ -215,11 +272,12 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     }
     return { ok: checks.every(c => c.ok), checks };
 }
-function loadConfigSafe(configPath) {
+function loadConfigResult(configPath) {
     try {
-        return loadConfig(configPath).roles;
+        const cfg = loadConfig(configPath);
+        return { ok: true, roles: cfg.roles, files: cfg.files };
     }
-    catch {
-        return [];
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
     }
 }