@ours.network/fleet 0.9.4 → 0.9.7

package/dist/creation.d.ts

@@ -0,0 +1,179 @@
+import { type LockDeps } from './atomic-file.js';
+import { type FetchLike } from './monitor.js';
+export type ReservationKind = 'role' | 'identity';
+export interface Reservation {
+    kind: ReservationKind;
+    name: string;
+}
+export declare class CreationConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Artifacts a transaction created, newest last. Rollback walks this in reverse,
+ * and may only delete what THIS transaction made — an object that already
+ * existed is never touched.
+ */
+export interface JournalEntry {
+    stage: string;
+    undo(): void | Promise<void>;
+}
+export interface CreationDeps {
+    lock?: LockDeps;
+    log?(line: string): void;
+    /** Reserve the ours identity name. Injectable so tests need no daemon. */
+    identityRegistry?: IdentityRegistry;
+    /** Verify/create the ours identity. Injectable so tests need no daemon. */
+    identityProvisioner?: IdentityProvisioner;
+}
+/**
+ * The contract the ours daemon must satisfy for identity names to be reserved
+ * atomically across ALL of its clients, not just across fleet processes.
+ *
+ * `check-then-create` is not atomic across processes, which is the whole point:
+ * two spawns can both observe a free identity name and both create it. The
+ * daemon is the only component that sees every client, so only the daemon can
+ * make the reservation authoritative.
+ */
+export interface IdentityRegistry {
+    /** Claim `name`. Returns false if it is already taken or reserved. */
+    reserve(name: string): Promise<boolean>;
+    /** Give the claim back (rollback). Must be safe to call on an unheld name. */
+    release(name: string): Promise<void>;
+}
+/**
+ * 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 declare const hostLocalIdentityRegistry: IdentityRegistry;
+export interface CreationTransaction {
+    /** Record an artifact this transaction created, with how to undo it. */
+    record(entry: JournalEntry): void;
+    /** Stages recorded so far, in order. */
+    readonly stages: string[];
+}
+/**
+ * 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 declare function withCreationTransaction<T>(names: {
+    role: string;
+    identity: string;
+}, body: (tx: CreationTransaction) => Promise<T>, deps?: CreationDeps): Promise<T>;
+/** Forget reservations left behind by a process that died mid-transaction. */
+export declare function clearStaleReservations(olderThanMs?: number, now?: number): number;
+/**
+ * Identity provisioning (7.3). The fleet must know — before the harness starts
+ * — whether the role's identity exists, and create it when it does not.
+ *
+ * `exists()` is answerable today: the daemon's authenticated `/identities`
+ * endpoint is already used by doctor. `create()` is NOT: `ours-mcp` exposes only
+ * `create-root`, and role identities are minted through the MCP `create_identity`
+ * tool inside an agent session. So creation is a seam, injected by whoever can
+ * satisfy it, and its absence is reported rather than papered over.
+ */
+export interface IdentityProvisioner {
+    /** Does this identity exist? `unknown` when the daemon could not be asked. */
+    exists(name: string): Promise<boolean | 'unknown'>;
+    /** Create it, publishing bio/persona through the same path. Absent = cannot. */
+    create?(name: string, profile: {
+        bio?: string;
+        persona?: string;
+    }): Promise<void>;
+    /**
+     * Undo a `create` during rollback. Only ever called for an identity THIS
+     * transaction created; absent means "cannot", and the orphan is reported.
+     */
+    remove?(name: string): Promise<void>;
+}
+export type IdentityGuarantee = {
+    state: 'verified';
+    detail: string;
+} | {
+    state: 'created';
+    detail: string;
+} | {
+    state: 'unverified';
+    detail: string;
+};
+/**
+ * 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 declare function ensureIdentity(name: string, profile: {
+    bio?: string;
+    persona?: string;
+}, provisioner: IdentityProvisioner | undefined, log?: (line: string) => void): Promise<IdentityGuarantee>;
+/**
+ * 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 declare function daemonIdentityProvisioner(env?: NodeJS.ProcessEnv, fetchImpl?: FetchLike): IdentityProvisioner;
+/** 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 interface ProvenanceEntry {
+    value: unknown;
+    source: ProvenanceSource;
+}
+export interface CreationProvenance {
+    version: 1;
+    /** The command that created the role, without its arguments. */
+    command: string;
+    fleetVersion: string;
+    createdAt: string;
+    lifetime: 'permanent' | 'temporary';
+    role: string;
+    /** Effective settings, each tagged with where its value came from. */
+    settings: Record<string, ProvenanceEntry>;
+}
+export declare 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 declare function buildProvenance(o: {
+    role: string;
+    lifetime: 'permanent' | 'temporary';
+    fleetVersion: string;
+    now?: Date;
+    settings: Record<string, ProvenanceEntry>;
+}): CreationProvenance;
+/** Write the provenance record atomically, before the role is started. */
+export declare function writeProvenance(stateDir: string, p: CreationProvenance): void;
+/** One concise line per non-built-in setting, for the post-creation summary. */
+export declare function formatProvenance(p: CreationProvenance): string[];
+/** Classify one setting: an explicit CLI value, a fleet default, or built-in. */
+export declare function provenanceOf(cliValue: unknown, fleetDefault: unknown, builtIn?: unknown): ProvenanceEntry;

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

@@ -0,0 +1,34 @@
+/**
+ * Stable, AI-friendly CLI and configuration reference.
+ *
+ * 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\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\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";
+/**
+ * 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:"];
+};