@ours.network/fleet 0.9.4 → 0.9.7

package/dist/permissions.js

@@ -0,0 +1,97 @@
+import { getAdapter } from './harness/registry.js';
+/**
+ * The capability floor every unattended role must clear. These are not
+ * nice-to-haves: an agent that cannot read its briefing, append its worklog,
+ * bind its identity, arm its monitor, edit its workspace, or run the status
+ * commands its briefing prescribes cannot carry out the job it was spawned for
+ * — and, being unattended, will report no error while failing to.
+ */
+export const UNATTENDED_FLOOR = [
+    'read-state', 'write-state', 'messaging', 'monitor', 'workspace-edit', 'status-commands',
+];
+/** Which floor capabilities a set of granted capabilities fails to cover. */
+export function checkUnattendedFloor(granted) {
+    const missing = UNATTENDED_FLOOR.filter(c => !granted.includes(c));
+    return { meets: missing.length === 0, missing };
+}
+/**
+ * Find native settings that contradict the neutral block. Only fires when the
+ * operator wrote BOTH — a role that states its intent once, neutrally or
+ * natively, has nothing to contradict and stays quiet. `harness_options` wins
+ * at launch, which is precisely why a silent disagreement is dangerous: the
+ * neutral block reads like the source of truth and is not.
+ */
+function findConflicts(role, fromNeutral, fromNative) {
+    if (!role.permissionsDeclared)
+        return [];
+    const conflicts = [];
+    for (const [key, nativeValue] of Object.entries(fromNative)) {
+        const neutralValue = fromNeutral[key];
+        if (neutralValue === undefined || String(neutralValue) === String(nativeValue))
+            continue;
+        conflicts.push({
+            key,
+            fromNeutral: String(neutralValue),
+            fromNative: String(nativeValue),
+            warning: `role '${role.name}': harness_options.${key}=${String(nativeValue)} contradicts the `
+                + `permissions block, which translates to ${key}=${String(neutralValue)} — `
+                + `harness_options.${key}=${String(nativeValue)} wins`,
+        });
+    }
+    return conflicts;
+}
+/** Resolve one role's permissions through its adapter. Never throws. */
+export function analyzeRolePermissions(role) {
+    const base = { role: role.name, harness: role.harness, permissions: role.permissions };
+    let adapter;
+    try {
+        adapter = getAdapter(role.harness);
+    }
+    catch (e) {
+        return { ...base, supported: false, warnings: [`role '${role.name}': ${e.message}`] };
+    }
+    const translation = adapter.translatePermissions(role.permissions);
+    if (!translation.supported) {
+        return {
+            ...base, supported: false,
+            warnings: [`role '${role.name}': harness '${role.harness}' cannot express neutral ` +
+                    `permissions — ${translation.reason}`],
+        };
+    }
+    const conflicts = findConflicts(role, translation.native, adapter.nativePermissionOverrides(role.harness_options));
+    const floor = checkUnattendedFloor(translation.capabilities);
+    const floorSeverity = role.permissions.unattended === 'deny' ? 'fail' : 'warn';
+    return {
+        ...base,
+        supported: true,
+        native: translation.native,
+        exact: translation.exact,
+        capabilities: translation.capabilities,
+        floor,
+        floorSeverity,
+        conflicts,
+        floorWarning: floor.meets ? undefined : (`role '${role.name}': resolved ${role.harness} permissions do not meet the unattended ` +
+            `capability floor — missing ${floor.missing.join(', ')} ` +
+            `(${formatNative(translation.native)}; unattended=${role.permissions.unattended} means these ` +
+            `requests will ${role.permissions.unattended === 'deny' ? 'be denied silently' : 'block the turn'})`),
+        warnings: translation.warnings.map(w => `role '${role.name}': ${w}`),
+    };
+}
+/** Every line a command should show for a role: translation, conflicts, floor. */
+export function allWarnings(a) {
+    return [
+        ...a.warnings,
+        ...(a.conflicts ?? []).map(c => c.warning),
+        ...(a.floorWarning ? [a.floorWarning] : []),
+    ];
+}
+/** Resolve every role's permissions, in config order. */
+export function analyzeFleetPermissions(roles) {
+    return roles.map(analyzeRolePermissions);
+}
+/** Render an analysis's native settings compactly, for one-line reporting. */
+export function formatNative(native) {
+    if (!native || !Object.keys(native).length)
+        return '(none)';
+    return Object.entries(native).map(([k, v]) => `${k}=${String(v)}`).join(' ');
+}

package/dist/runner.d.ts

@@ -3,6 +3,7 @@ import type { Launch } from './harness/types.js';
 import { Tmux } from './tmux.js';
 import { type MonitorHandle, type MonitorOpts, type FetchLike } from './monitor.js';
 import { type Exec } from './exec.js';
+import type { ExitRecord } from './session/types.js';
 export interface RunnerDeps {
     tmux: Tmux;
     exec: Exec;
@@ -15,6 +16,8 @@ export interface RunnerDeps {
     fetch: FetchLike;
     /** Construct the supervisor mail monitor (injectable so tests stub it out). */
     createMonitor(opts: MonitorOpts): MonitorHandle;
+    /** Lets a test (or a shutdown path) end the supervised restart loop. */
+    shouldStop?(): boolean;
 }
 /**
  * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
@@ -24,6 +27,41 @@ export interface RunnerDeps {
  * still sees the real exit code.
  */
 export declare function buildPaneCommand(launch: Launch, roleEnv: Record<string, string> | undefined, exitStatusPath: string, paneArgv?: string[]): string;
+/**
+ * Read the pane's `.exit-status`. Three shapes are accepted: the structured
+ * record written above, a bare number left by a pre-upgrade pane (so an
+ * in-place upgrade does not misread a real exit), and anything else — which is
+ * `unknown`, never an invented failure. A missing file returns null so the
+ * caller can distinguish "no record" from "a record saying unknown".
+ */
+export declare function readExitRecord(path: string): ExitRecord | null;
+export declare const RESTART_LEDGER_FILE = ".restart-ledger.json";
+/** Consecutive immediate failures tolerated before the agent is held down. */
+export declare const RESTART_FAIL_THRESHOLD = 5;
+export interface RestartLedger {
+    version: 1;
+    consecutiveImmediateFailures: number;
+    lastReason: string;
+    nextDelayMs: number;
+    /** Whether this failure sequence has already thrown away resume state. */
+    resumeDiscarded: boolean;
+    circuit: 'closed' | 'open';
+    updatedAt: string;
+    /** When the circuit opened, for the held-down status line. */
+    openedAt?: string;
+}
+/** Bounded exponential backoff for the nth consecutive immediate failure. */
+export declare function backoffFor(consecutiveFailures: number): number;
+/** Read a role's restart ledger; a missing or corrupt one starts clean. */
+export declare function readRestartLedger(dir: string): RestartLedger;
+export declare function writeRestartLedger(dir: string, ledger: RestartLedger): void;
+/**
+ * Close the circuit and forget the failure streak. Called by an explicit
+ * operator `up`/`restart`, which is the only thing that may release a held-down
+ * role — a held-down runner polls this file, so a role can be released without
+ * bouncing its unit.
+ */
+export declare function resetRestartLedger(dir: string): void;
 /** Filename spawnTemp writes into a temp agent dir to carry the fleet start-stagger. */
 export declare const START_STAGGER_FILE = ".start-stagger-ms";
 /**
@@ -37,10 +75,35 @@ export declare const START_STAGGER_FILE = ".start-stagger-ms";
 export declare function reserveLaunchSlot(root: string, staggerMs: number, deps: Pick<RunnerDeps, 'now' | 'sleep' | 'log'>): Promise<number>;
 /** Read a temp role's config snapshot written by spawnTemp. */
 export declare function loadTempRole(name: string): ResolvedRole;
-/** One supervised session lifecycle. The supervisor re-invokes us after we return. */
+/** What one child session did, so the supervising loop can decide what follows. */
+export interface AttemptResult {
+    elapsedSecs: number;
+    exit: ExitRecord;
+    /** Whether this attempt threw away resume state to start fresh. */
+    rotated: boolean;
+    mode: 'fresh' | 'resume';
+}
+/** One session lifecycle. `runSupervised` (or a one-shot caller) drives it. */
 export declare function runOnce(name: string, opts?: {
     temp?: boolean;
     configPath?: string;
-}, partialDeps?: Partial<RunnerDeps>): Promise<void>;
+    allowResumeRotation?: boolean;
+}, partialDeps?: Partial<RunnerDeps>): Promise<AttemptResult>;
+/**
+ * The persistent supervisor for one permanent role: run child sessions in a
+ * loop, count consecutive immediate failures across them, back off between
+ * attempts, and after `RESTART_FAIL_THRESHOLD` hold the agent down while
+ * staying alive — so the service manager has nothing to restart and cannot
+ * resume the two-second loop behind our back.
+ *
+ * `attempt` is injectable so the policy can be tested against a fake clock and
+ * fake child instead of real sessions.
+ */
+export declare function runSupervised(name: string, opts?: {
+    configPath?: string;
+}, partialDeps?: Partial<RunnerDeps>, attempt?: (n: string, o: {
+    configPath?: string;
+    allowResumeRotation?: boolean;
+}, d: Partial<RunnerDeps>) => Promise<AttemptResult>): Promise<RestartLedger>;
 /** Temp-agent entrypoint: run one session, then remove the temp dir. */
 export declare function runTemp(name: string, deps?: Partial<RunnerDeps>): Promise<void>;

package/dist/runner.js

@@ -2,8 +2,8 @@ import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { parse } from 'yaml';
-import { agentDir, home, stateRoot } from './paths.js';
-import { loadConfig, findRole } from './config.js';
+import { agentDir, stateRoot } from './paths.js';
+import { loadConfig, findRole, isolationContextFor, resolvePermissions, } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { Tmux } from './tmux.js';
 import { createMonitor } from './monitor.js';
@@ -11,6 +11,10 @@ import { realExec, shq } from './exec.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { selectIsolationBackend } from './isolation/registry.js';
 import { resourceArgs, cpuControllerDelegated } from './isolation/resources.js';
+import { AcpSession } from './session/acp.js';
+import { RoleControlServer } from './session/control.js';
+import { TmuxSession } from './session/tmux.js';
+import { classifyShellStatus } from './session/types.js';
 const defaultDeps = () => ({
     tmux: new Tmux(),
     exec: realExec,
@@ -39,7 +43,12 @@ export function buildPaneCommand(launch, roleEnv, exitStatusPath, paneArgv = lau
     const env = { PATH: process.env.PATH ?? '', ...launch.env, ...(roleEnv ?? {}) };
     const envPfx = 'env ' + Object.entries(env).map(([k, v]) => `${k}=${shq(v)}`).join(' ');
     const cmd = paneArgv.map(shq).join(' ');
-    return `${envPfx} ${cmd}; echo $? > ${shq(exitStatusPath)}`;
+    // Write a structured record, not a bare number: the wait status alone cannot
+    // say whether the file is missing because the program never exited or because
+    // nothing ever wrote it. `printf` is POSIX; no shell branching is needed
+    // because classification happens in one place, in TypeScript.
+    const record = `'{"version":1,"backend":"tmux","status":'"$__ofs"'}'`;
+    return `${envPfx} ${cmd}; __ofs=$?; printf %s ${record} > ${shq(exitStatusPath)}`;
 }
 /** Adapt runner deps and the role's daemon-profile overrides for the monitor. */
 function monitorDeps(deps, roleEnv) {
@@ -56,6 +65,89 @@ function monitorDeps(deps, roleEnv) {
         timers: { set: (fn, ms) => setTimeout(fn, ms), clear: t => clearTimeout(t) },
     };
 }
+/**
+ * Read the pane's `.exit-status`. Three shapes are accepted: the structured
+ * record written above, a bare number left by a pre-upgrade pane (so an
+ * in-place upgrade does not misread a real exit), and anything else — which is
+ * `unknown`, never an invented failure. A missing file returns null so the
+ * caller can distinguish "no record" from "a record saying unknown".
+ */
+export function readExitRecord(path) {
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf8').trim();
+    if (!raw)
+        return { version: 1, class: 'unknown', detail: 'the pane left an empty exit record' };
+    if (/^-?\d+$/.test(raw))
+        return classifyShellStatus(Number(raw)); // legacy `echo $?`
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.status === 'number')
+            return classifyShellStatus(parsed.status);
+    }
+    catch { /* fall through to unknown */ }
+    return { version: 1, class: 'unknown', detail: `unreadable exit record: ${raw.slice(0, 120)}` };
+}
+// ─── Restart-loop containment (3.2) ──────────────────────────────────────────
+//
+// The child-session restart loop used to BE the service manager: systemd's
+// `Restart=always RestartSec=2` and launchd's `KeepAlive`. Neither can count,
+// so a program that dies instantly was relaunched every two seconds forever,
+// and each relaunch was a fresh process with no memory of the previous one.
+// The count now lives with the role, in its state directory, so it survives the
+// runner being restarted and is consistent across both service managers.
+export const RESTART_LEDGER_FILE = '.restart-ledger.json';
+/** Consecutive immediate failures tolerated before the agent is held down. */
+export const RESTART_FAIL_THRESHOLD = 5;
+const RESTART_BACKOFF_BASE_MS = 2_000;
+const RESTART_BACKOFF_MAX_MS = 60_000;
+/** How often a held-down runner re-reads its ledger, so `up` can release it. */
+const HELD_DOWN_POLL_MS = 5_000;
+const emptyLedger = () => ({
+    version: 1,
+    consecutiveImmediateFailures: 0,
+    lastReason: '',
+    nextDelayMs: 0,
+    resumeDiscarded: false,
+    circuit: 'closed',
+    updatedAt: new Date(0).toISOString(),
+});
+/** Bounded exponential backoff for the nth consecutive immediate failure. */
+export function backoffFor(consecutiveFailures) {
+    if (consecutiveFailures <= 0)
+        return 0;
+    return Math.min(RESTART_BACKOFF_BASE_MS * 2 ** (consecutiveFailures - 1), RESTART_BACKOFF_MAX_MS);
+}
+/** Read a role's restart ledger; a missing or corrupt one starts clean. */
+export function readRestartLedger(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, RESTART_LEDGER_FILE), 'utf8'));
+        if (raw.version !== 1)
+            return emptyLedger();
+        return { ...emptyLedger(), ...raw, version: 1 };
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+export function writeRestartLedger(dir, ledger) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, RESTART_LEDGER_FILE), JSON.stringify(ledger, null, 2) + '\n');
+    }
+    catch { /* diagnostics must never take the role down */ }
+}
+/**
+ * Close the circuit and forget the failure streak. Called by an explicit
+ * operator `up`/`restart`, which is the only thing that may release a held-down
+ * role — a held-down runner polls this file, so a role can be released without
+ * bouncing its unit.
+ */
+export function resetRestartLedger(dir) {
+    if (!existsSync(dir))
+        return;
+    writeRestartLedger(dir, { ...emptyLedger(), updatedAt: new Date().toISOString() });
+}
 /** Filename spawnTemp writes into a temp agent dir to carry the fleet start-stagger. */
 export const START_STAGGER_FILE = '.start-stagger-ms';
 /** Read the start-stagger a temp agent was spawned with (0 if none / unreadable). */
@@ -148,7 +240,7 @@ function resolveConfigPath(dir, explicit) {
         return undefined;
     return readFileSync(marker, 'utf8').trim() || undefined;
 }
-/** One supervised session lifecycle. The supervisor re-invokes us after we return. */
+/** One session lifecycle. `runSupervised` (or a one-shot caller) drives it. */
 export async function runOnce(name, opts = {}, partialDeps = {}) {
     const deps = { ...defaultDeps(), ...partialDeps };
     const temp = opts.temp === true;
@@ -182,17 +274,22 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         writeFileSync(bootedFile, '');
     const runCwd = role.cwd && existsSync(role.cwd) ? role.cwd : dir;
     const prep = await adapter.prepareSession(role, { stateDir: dir, runCwd });
-    const launch = adapter.buildLaunch(role, mode, { sessionId }, prep);
+    const sessionBackend = role.session ?? 'tmux';
+    const launch = sessionBackend === 'acp'
+        ? (() => {
+            if (!adapter.buildAcpLaunch)
+                throw new Error(`harness '${role.harness}' does not support the ACP session backend`);
+            return adapter.buildAcpLaunch(role, prep);
+        })()
+        : adapter.buildLaunch(role, mode, { sessionId }, prep);
     // Isolation is additive: only roles that declare `isolation:` are wrapped. The
     // env prefix + exit capture in buildPaneCommand stay host-side (see §5.3).
-    let paneArgv = launch.argv;
+    let wrappedArgv = launch.argv;
     if (role.isolation) {
-        const addDirs = role.harness === 'codex'
-            ? (role.harness_options?.add_dirs ?? [])
-            : [];
-        const ctx = {
-            stateDir: dir, runCwd, home: home(), harness: role.harness, additionalWriteDirs: addDirs,
-        };
+        // The SAME context config validation and doctor judged (5.2): a policy
+        // checked against a different mount set than the one that launches is not a
+        // check at all.
+        const ctx = { ...isolationContextFor(role), stateDir: dir, runCwd };
         const policy = resolveIsolation(role.isolation, ctx);
         const sel = await selectIsolationBackend(policy, deps.exec); // throws on strict + unavailable
         const degradedMarker = join(dir, '.isolation-degraded');
@@ -204,14 +301,14 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             deps.log(`[${name}] isolation: ${sel.backend.id} (net=${policy.network}) ${sel.detail}`);
             rmSync(degradedMarker, { force: true });
         }
-        paneArgv = sel.backend.wrap(launch.argv, policy, ctx);
+        wrappedArgv = sel.backend.wrap(launch.argv, policy, ctx);
         // Resource caps wrap the sandbox from OUTSIDE, at the pane's own cgroup scope
         // (§5.4). Applies even when the sandbox degraded to none.
         const { argv: rprefix, warnings } = resourceArgs(policy.resources, deps.cpuDelegated());
         for (const w of warnings)
             deps.log(`[${name}] WARNING ${w}`);
         if (rprefix.length)
-            paneArgv = [...rprefix, ...paneArgv];
+            wrappedArgv = [...rprefix, ...wrappedArgv];
     }
     // Start-stagger: space this launch at least start_stagger_ms after the previous
     // agent launch across the whole host, so a burst of boots (systemd starts every
@@ -232,47 +329,225 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     // (backlog before the tip is the SessionStart hook's job). Disabled roles keep
     // the legacy in-session watch. Temp snapshots predating `monitor:` are treated
     // as disabled (monitor may be undefined on an old role.yaml).
+    const resolvedMonitorDeps = monitorDeps(deps, role.env);
     const monitor = role.monitor?.enabled ? deps.createMonitor({
-        name, agentDir: dir, cfg: role.monitor,
-        deps: monitorDeps(deps, role.env),
+        name, identity: role.identity, agentDir: dir, cfg: role.monitor,
+        deps: resolvedMonitorDeps,
     }) : null;
     if (monitor)
         await monitor.prime();
     rmSync(exitFile, { force: true });
-    await deps.tmux.kill(name);
-    await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile, paneArgv));
-    let pid = null;
-    for (let i = 0; i < 40 && pid === null; i++) {
-        pid = await deps.tmux.panePid(name);
-        if (pid === null)
-            await deps.sleep(250);
+    let pid;
+    let sessionHandle;
+    let acpSession;
+    let control;
+    if (sessionBackend === 'acp') {
+        const perms = role.permissions ?? resolvePermissions(undefined, undefined);
+        // Say once, at startup, that this role will decide permission requests by
+        // itself. Without it the only trace of an auto-denied tool call is a turn
+        // that quietly did less than it was asked to.
+        if (perms.unattended === 'deny')
+            deps.log(`[${name}] permission policy: unattended=deny — with no console attached, ` +
+                `permission requests are automatically denied once each (reject_once) and the turn continues`);
+        acpSession = await AcpSession.start({
+            name,
+            argv: wrappedArgv,
+            cwd: runCwd,
+            env: { ...launch.env, ...(role.env ?? {}) },
+            stateDir: dir,
+            mode,
+            permissions: perms,
+            log: deps.log,
+        });
+        pid = acpSession.pid;
+        sessionHandle = acpSession;
+        control = new RoleControlServer(dir, acpSession, deps.log);
+        await control.start();
+        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
+            // the monitor must keep its cursor and try again.
+            submit: async (text) => {
+                const result = await acpSession.submitPrompt(text);
+                return { succeeded: result.succeeded, outcome: result.outcome, detail: result.detail };
+            },
+        };
+        const firstPrompt = mode === 'fresh'
+            ? `Read and follow ${join(dir, 'briefing.md')} now.`
+            : adapter.vocabulary.restartPrompt(role.identity, join(dir, 'WORKLOG.md'), role);
+        // Wait for the first turn's TERMINAL result. An agent that accepts the
+        // startup prompt and then refuses it has not started; logging the role as
+        // up would hide a role that never read its briefing.
+        const started = await acpSession.submitPrompt(firstPrompt);
+        if (!started.succeeded) {
+            monitor?.stop();
+            await control.close();
+            await acpSession.close();
+            throw new Error(`[${name}] ACP startup prompt ${started.outcome}` +
+                `${started.detail ? `: ${started.detail}` : ''}`);
+        }
     }
-    if (pid === null)
-        throw new Error(`[${name}] could not resolve tmux pane pid`);
-    deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} mode=${mode}`);
+    else {
+        await deps.tmux.kill(name);
+        await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile, wrappedArgv));
+        let panePid = null;
+        for (let i = 0; i < 40 && panePid === null; i++) {
+            panePid = await deps.tmux.panePid(name);
+            if (panePid === null)
+                await deps.sleep(250);
+        }
+        if (panePid === null)
+            throw new Error(`[${name}] could not resolve tmux pane pid`);
+        pid = panePid;
+        sessionHandle = new TmuxSession(name, pid, deps.tmux, deps.isAlive);
+    }
+    deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} session=${sessionBackend} mode=${mode}`);
     // The monitor loop lives exactly as long as the session: it starts once the
     // pane pid is known and is stopped when that pid dies (task dies with runner).
     const monitorLoop = monitor?.run(pid);
     const start = deps.now();
-    while (deps.isAlive(pid))
+    while (sessionHandle.isAlive())
         await deps.sleep(2000);
     if (monitor) {
         monitor.stop();
         await monitorLoop;
     }
+    if (control)
+        await control.close();
+    if (acpSession)
+        await acpSession.close();
     const elapsed = (deps.now() - start) / 1000;
-    const code = existsSync(exitFile) ? readFileSync(exitFile, 'utf8').trim() : 'crash';
+    // Establish what actually happened before deciding anything. Absence of a
+    // record is `unknown` — except when the console itself is gone, which is a
+    // different event with a different consequence.
+    const exitRecord = acpSession
+        ? acpSession.exitResult()
+            ?? { version: 1, class: 'unknown', detail: 'the ACP agent stopped without reporting an exit' }
+        : readExitRecord(exitFile)
+            ?? (await deps.tmux.has(name)
+                ? { version: 1, class: 'unknown', detail: 'the pane process ended without writing an exit record' }
+                : { version: 1, class: 'session-destroyed', detail: `the tmux session '${name}' no longer exists` });
+    writeFileSync(exitFile, JSON.stringify({
+        ...exitRecord, at: new Date(deps.now()).toISOString(), elapsedSecs: Number(elapsed.toFixed(1)),
+    }) + '\n');
+    let rotated = false;
     const rotate = (why) => {
         writeFileSync(sidFile, randomUUID() + '\n');
         rmSync(bootedFile, { force: true });
+        rotated = true;
         deps.log(`[${name}] ${why} -> rotated session-id; next start is FRESH`);
     };
-    if (code === '0' && adapter.exitPolicy.cleanExitIsFresh)
+    if (exitRecord.class === 'clean' && adapter.exitPolicy.cleanExitIsFresh)
         rotate(`clean exit (code 0)`);
-    else if (mode === 'resume' && elapsed < adapter.exitPolicy.fastFailSecs)
-        rotate(`resume failed fast (${elapsed.toFixed(0)}s, code ${code})`);
+    else if (exitRecord.class === 'session-destroyed')
+        // Someone tore the console down; the agent did not fail. Rotating here
+        // would discard a live conversation for an operator action.
+        deps.log(`[${name}] ${exitRecord.detail} (${elapsed.toFixed(0)}s) -> next start RESUMES context`);
+    else if (mode === 'resume' && elapsed < adapter.exitPolicy.fastFailSecs) {
+        // Self-heal a poisoned resume — but only once per failure sequence. Rotating
+        // on every attempt would discard the conversation again and again while the
+        // real cause (a broken command, a missing binary) went unaddressed.
+        if (opts.allowResumeRotation === false)
+            deps.log(`[${name}] resume failed fast again (${elapsed.toFixed(0)}s, ${exitRecord.detail}) ` +
+                `-> resume state was already discarded once; keeping it`);
+        else
+            rotate(`resume failed fast (${elapsed.toFixed(0)}s, ${exitRecord.detail})`);
+    }
     else
-        deps.log(`[${name}] exited (code ${code}, ${elapsed.toFixed(0)}s) -> next start RESUMES context`);
+        deps.log(`[${name}] ${exitRecord.detail} (${elapsed.toFixed(0)}s) -> next start RESUMES context`);
+    return { elapsedSecs: elapsed, exit: exitRecord, rotated, mode };
+}
+/**
+ * The persistent supervisor for one permanent role: run child sessions in a
+ * loop, count consecutive immediate failures across them, back off between
+ * attempts, and after `RESTART_FAIL_THRESHOLD` hold the agent down while
+ * staying alive — so the service manager has nothing to restart and cannot
+ * resume the two-second loop behind our back.
+ *
+ * `attempt` is injectable so the policy can be tested against a fake clock and
+ * fake child instead of real sessions.
+ */
+export async function runSupervised(name, opts = {}, partialDeps = {}, attempt = runOnce) {
+    const deps = { ...defaultDeps(), ...partialDeps };
+    const dir = agentDir(name);
+    mkdirSync(dir, { recursive: true });
+    const shouldStop = deps.shouldStop ?? (() => false);
+    const stamp = () => new Date(deps.now()).toISOString();
+    while (!shouldStop()) {
+        let ledger = readRestartLedger(dir);
+        if (ledger.circuit === 'open') {
+            // Held down. Stay alive — exiting would hand the role straight back to
+            // the service manager — and watch for an operator reset.
+            await deps.sleep(HELD_DOWN_POLL_MS);
+            continue;
+        }
+        let result;
+        try {
+            result = await attempt(name, { configPath: opts.configPath, allowResumeRotation: !ledger.resumeDiscarded }, deps);
+        }
+        catch (e) {
+            // A session that could not even start is an immediate failure like any
+            // other; it must count, or an unstartable role loops forever.
+            result = {
+                elapsedSecs: 0,
+                exit: { version: 1, class: 'unknown', detail: e instanceof Error ? e.message : String(e) },
+                rotated: false,
+                mode: 'fresh',
+            };
+        }
+        // Re-read: the attempt itself may have taken minutes, and an operator may
+        // have reset the ledger meanwhile.
+        ledger = readRestartLedger(dir);
+        const fastFailSecs = fastFailSecsFor(name, opts.configPath);
+        const immediate = result.elapsedSecs < fastFailSecs;
+        if (!immediate) {
+            // A session that ran for a while is not a restart loop, whatever ended it.
+            writeRestartLedger(dir, {
+                ...emptyLedger(),
+                lastReason: result.exit.detail,
+                updatedAt: stamp(),
+            });
+            continue;
+        }
+        const failures = ledger.consecutiveImmediateFailures + 1;
+        const reason = `${result.exit.detail} after ${result.elapsedSecs.toFixed(1)}s`;
+        const next = {
+            version: 1,
+            consecutiveImmediateFailures: failures,
+            lastReason: reason,
+            nextDelayMs: backoffFor(failures),
+            resumeDiscarded: ledger.resumeDiscarded || result.rotated,
+            circuit: failures >= RESTART_FAIL_THRESHOLD ? 'open' : 'closed',
+            updatedAt: stamp(),
+        };
+        if (next.circuit === 'open') {
+            next.openedAt = stamp();
+            next.nextDelayMs = 0;
+            writeRestartLedger(dir, next);
+            deps.log(`[${name}] HELD DOWN after ${failures} immediate failures at ${next.openedAt} — ` +
+                `${reason}; the agent will not be restarted until: ours-fleet restart ${name}`);
+            continue;
+        }
+        writeRestartLedger(dir, next);
+        deps.log(`[${name}] immediate failure ${failures}/${RESTART_FAIL_THRESHOLD} (${reason}) ` +
+            `-> backing off ${next.nextDelayMs}ms`);
+        await deps.sleep(next.nextDelayMs);
+    }
+    return readRestartLedger(dir);
+}
+/**
+ * How short an attempt has to be to count as immediate. The role's harness
+ * decides; an unreadable config falls back to the common 20s so a broken config
+ * cannot disable the breaker.
+ */
+function fastFailSecsFor(name, configPath) {
+    try {
+        const role = findRole(loadConfig(configPath), name);
+        return getAdapter(role.harness).exitPolicy.fastFailSecs;
+    }
+    catch {
+        return 20;
+    }
 }
 /** Temp-agent entrypoint: run one session, then remove the temp dir. */
 export async function runTemp(name, deps = {}) {