@ours.network/fleet 0.9.5 → 0.9.7

package/dist/monitor.js

@@ -260,6 +260,8 @@ export class Monitor {
     // ended in an API error with no completed turn in between.
     apiErrorStreak = 0;
     turnFailThreshold;
+    /** Active degradations, keyed by cause. Empty means armed. */
+    causes = new Map();
     constructor(o) {
         this.name = o.name;
         this.identity = o.identity ?? o.name;
@@ -278,23 +280,23 @@ export class Monitor {
         if (persisted !== null) {
             this.cursor = persisted;
             this.deliveredCursor = persisted;
-            this.setStatus('armed');
+            this.writeStatus();
             return;
         }
         try {
             const body = await this.doFetch('tip', LONGPOLL_TIMEOUT_MS);
             this.cursor = typeof body.cursor === 'number' ? body.cursor : 0;
             this.persistCursor();
-            this.setStatus('armed');
+            this.writeStatus();
         }
         catch (e) {
             if (e instanceof AuthError) {
                 this.fatal = true;
-                this.setStatus(`failed: ${e.message}`);
+                this.degrade('auth', e.message, 'failed');
             }
             else {
                 this.cursor = null;
-                this.setStatus(`degraded: prime failed (${msg(e)})`);
+                this.degrade('connectivity', `prime failed (${msg(e)})`);
             }
         }
     }
@@ -307,24 +309,26 @@ export class Monitor {
         const pending = [];
         while (!this.stopped) {
             if (!this.deps.isAlive(pid)) {
-                this.setStatus('degraded: session offline');
+                this.degrade('offline', 'session offline');
                 return;
             }
             let body;
             try {
                 body = await this.doFetch(String(this.cursor ?? 0), LONGPOLL_TIMEOUT_MS);
                 backoff = 0;
+                // A poll that worked proves the stream is healthy — and only that.
+                this.recover('connectivity');
             }
             catch (e) {
                 if (this.stopped)
                     return;
                 if (e instanceof AuthError) {
                     this.fatal = true;
-                    this.setStatus(`failed: ${e.message}`);
+                    this.degrade('auth', e.message, 'failed');
                     return;
                 }
                 backoff = Math.min(backoff + BACKOFF_STEP_MS, BACKOFF_MAX_MS);
-                this.setStatus(`degraded: stream hiccup (${msg(e)})`);
+                this.degrade('connectivity', `stream hiccup (${msg(e)})`);
                 await this.deps.sleep(backoff);
                 continue;
             }
@@ -350,7 +354,7 @@ export class Monitor {
                 accepted = await this.deliver(pid, pending);
             }
             catch (e) {
-                this.setStatus(`degraded: delivery failed (${msg(e)})`);
+                this.degrade('delivery', `delivery failed (${msg(e)})`);
             }
             if (accepted) {
                 pending.length = 0;
@@ -382,19 +386,23 @@ export class Monitor {
         const line = formatNotificationLine(batch);
         if (this.deps.delivery) {
             const result = await this.deps.delivery.submit(line);
-            if (!result.accepted) {
-                this.setStatus(`degraded: ACP prompt not accepted${result.detail ? ` (${result.detail})` : ''}`);
+            if (!result.succeeded) {
+                // Name the reason: "refused" and "cancelled" are the agent's answer,
+                // not a transport problem, and an operator has to be able to tell them
+                // apart from a dead socket.
+                this.degrade('delivery', `wake ${result.outcome}${result.detail ? ` (${result.detail})` : ''}`);
                 return false;
             }
+            this.recover('delivery', 'modal');
             this.recordTurn('completed');
             return true;
         }
         const state = await this.awaitInjectable(pid);
         if (state !== 'ready') {
             if (state === 'offline')
-                this.setStatus('degraded: offline during delivery');
+                this.degrade('offline', 'offline during delivery');
             else if (state === 'modal')
-                this.setStatus(`degraded: modal wedge — pane held a dialog for ` +
+                this.degrade('modal', `modal wedge — pane held a dialog for ` +
                     `${MODAL_GIVE_UP_MS / 1000}s, wake not injected`);
             return false;
         }
@@ -408,7 +416,7 @@ export class Monitor {
             await this.deps.sleep(POST_VERIFY_MS);
             const capture = await safeCapture(this.deps.tmux, this.name);
             if (!capture.ok) {
-                this.setStatus('degraded: capture failed during injection verification');
+                this.degrade('delivery', 'capture failed during injection verification');
                 return false;
             }
             if (!stillInComposer(capture.pane, line)) {
@@ -418,9 +426,10 @@ export class Monitor {
             await this.deps.tmux.sendKey(this.name, 'Enter');
         }
         if (!delivered) {
-            this.setStatus('degraded: injection unverified');
+            this.degrade('delivery', 'injection unverified');
             return false;
         }
+        this.recover('delivery', 'modal');
         // The wake landed and a turn started; observe how that turn terminates so a
         // refusal-wedge (every turn dies with `API Error:` while delivery stays green)
         // becomes visible in `.monitor-status` instead of masquerading as armed (#19).
@@ -442,7 +451,7 @@ export class Monitor {
                 return; // loop marks offline
             const capture = await safeCapture(this.deps.tmux, this.name);
             if (!capture.ok) {
-                this.setStatus('degraded: capture failed during turn observation');
+                this.degrade('delivery', 'capture failed during turn observation');
                 return;
             }
             if (looksApiError(capture.pane)) {
@@ -459,14 +468,17 @@ export class Monitor {
     }
     /** Update the consecutive-API-error streak and derive `.monitor-status` from it. */
     recordTurn(outcome) {
+        if (outcome === 'inconclusive')
+            return; // no evidence either way; leave the streak
         if (outcome === 'api-error')
             this.apiErrorStreak++;
-        else if (outcome === 'completed')
+        else
             this.apiErrorStreak = 0;
-        // 'inconclusive' leaves the streak (and therefore the status) unchanged.
-        this.setStatus(this.apiErrorStreak >= this.turnFailThreshold
-            ? 'degraded: turns failing (api error)'
-            : 'armed');
+        if (this.apiErrorStreak >= this.turnFailThreshold)
+            this.degrade('turns-failing', 'turns failing (api error)');
+        else if (outcome === 'completed')
+            // A turn that ran to the end is the ONLY thing that clears this.
+            this.recover('turns-failing');
     }
     /**
      * Reset the composer to empty before typing a wake. Without this, any
@@ -500,7 +512,7 @@ export class Monitor {
             }
             const capture = await safeCapture(this.deps.tmux, this.name);
             if (!capture.ok) {
-                this.setStatus('degraded: capture failed while checking session readiness');
+                this.degrade('delivery', 'capture failed while checking session readiness');
                 await this.deps.sleep(MODAL_RETRY_MS);
                 continue;
             }
@@ -592,15 +604,41 @@ export class Monitor {
             this.deps.log(`[${this.name}] monitor: failed to persist state: ${msg(e)}`);
         }
     }
-    setStatus(s) {
+    /** Record a degradation under its own cause and republish the status. */
+    degrade(cause, detail, level = 'degraded') {
+        const previous = this.causes.get(cause);
+        this.causes.set(cause, { level, detail, at: new Date(this.deps.now()).toISOString() });
+        this.writeStatus();
+        if (previous?.detail !== detail)
+            this.deps.log(`[${this.name}] monitor ${level}: ${cause} — ${detail}`);
+    }
+    /**
+     * Clear exactly the causes this recovery signal speaks to. Anything else
+     * stays: one successful poll must never be able to erase `turns failing`.
+     */
+    recover(...causes) {
+        let changed = false;
+        for (const cause of causes)
+            changed = this.causes.delete(cause) || changed;
+        if (changed)
+            this.deps.log(`[${this.name}] monitor recovered: ${causes.join(', ')}`);
+        this.writeStatus();
+    }
+    /**
+     * One line per active cause, each dated; `armed` when there are none. Every
+     * line carries an ISO timestamp so an operator can tell a live status from a
+     * stale one left behind by a monitor that stopped writing.
+     */
+    writeStatus() {
+        const lines = this.causes.size
+            ? [...this.causes.entries()].map(([cause, e]) => `${e.level}: ${cause} at ${e.at} — ${e.detail}`)
+            : [`armed at ${new Date(this.deps.now()).toISOString()}`];
         try {
-            writeFileSync(this.statusPath, `${s}\n`);
+            writeFileSync(this.statusPath, lines.join('\n') + '\n');
         }
         catch (e) {
             this.deps.log(`[${this.name}] monitor: failed to write status: ${msg(e)}`);
         }
-        if (!s.startsWith('armed'))
-            this.deps.log(`[${this.name}] monitor ${s}`);
     }
 }
 export function createMonitor(o) {

package/dist/ops.d.ts

@@ -1,18 +1,31 @@
 import type { FleetConfig, ResolvedRole } from './config.js';
-import type { SupervisorBackend } from './supervisor/types.js';
+import type { InstallOutcome as BackendInstallOutcome, SupervisorBackend } from './supervisor/types.js';
+/** An install outcome tagged with the role it belongs to. */
+export interface InstallOutcome extends BackendInstallOutcome {
+    role: string;
+}
 export interface OpsDeps {
     backend: SupervisorBackend;
     binPath: string;
     log(line: string): void;
+    /**
+     * Called the INSTANT a registration is created, before anything else can
+     * fail. A creation transaction that learns about registrations only from
+     * `up()`'s return value learns nothing when `up()` throws — and the service
+     * it just registered is then invisible to rollback (6.2). Optional: plain
+     * `ours-fleet up` has no transaction to tell.
+     */
+    onInstalled?(outcome: InstallOutcome): void;
 }
 /** Materialize a role's state dir from config: briefing + markers. Returns the dir. */
 export declare function applyRole(role: ResolvedRole, opts?: {
     fresh?: boolean;
     temp?: boolean;
     configPath?: string;
+    identityGuarantee?: 'verified' | 'created' | 'unverified';
 }): string;
 /** Create/start roles declaratively. Idempotent; active roles keep their context. */
-export declare function up(cfg: FleetConfig, names: string[], deps: OpsDeps, configPath?: string): Promise<void>;
+export declare function up(cfg: FleetConfig, names: string[], deps: OpsDeps, configPath?: string, identityGuarantee?: 'verified' | 'created' | 'unverified'): Promise<InstallOutcome[]>;
 export declare function down(cfg: FleetConfig, names: string[], deps: OpsDeps): Promise<void>;
 /** Re-sync from config + bounce. mode 'keep' resumes context; 'fresh' wipes it. */
 export declare function restartRoles(cfg: FleetConfig, names: string[], deps: OpsDeps, mode: 'keep' | 'fresh', configPath?: string): Promise<void>;

package/dist/ops.js

@@ -5,6 +5,7 @@ import { agentDir, fleetDDir } from './paths.js';
 import { findRole } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { generateBriefing } from './briefing.js';
+import { resetRestartLedger } from './runner.js';
 // Launch staggering now lives at the harness-launch point (the runner's start
 // gate, driven by `start_stagger_ms`), so it covers systemd host-boot too — not
 // just the `up`/`restart` command loop below. The old in-loop FLEET_START_STAGGER
@@ -36,6 +37,7 @@ export function applyRole(role, opts = {}) {
     writeFileSync(join(dir, 'briefing.md'), generateBriefing(role, adapter.vocabulary, {
         stateDir: dir, worklogPath: join(dir, 'WORKLOG.md'),
         routinesPath: join(dir, 'ROUTINES.md'), briefingBody,
+        identityGuarantee: opts.identityGuarantee,
     }));
     if (opts.fresh)
         for (const f of ['.booted', '.session-id', '.exit-status'])
@@ -46,32 +48,53 @@ function selectRoles(cfg, names) {
     return names.length ? names.map(n => findRole(cfg, n)) : cfg.roles;
 }
 /** Create/start roles declaratively. Idempotent; active roles keep their context. */
-export async function up(cfg, names, deps, configPath) {
+export async function up(cfg, names, deps, configPath, identityGuarantee) {
+    const outcomes = [];
     for (const role of selectRoles(cfg, names)) {
-        const dir = applyRole(role, { configPath });
-        // If the role isn't running, boot fresh so it reads the briefing we just wrote.
-        const status = await deps.backend.status(role.name).catch(() => '');
-        if (!/running|active \(/.test(status))
+        const dir = applyRole(role, { configPath, identityGuarantee });
+        // Only a *definite* stop boots fresh so the role reads the briefing we just
+        // wrote. A running, restarting, or unprobeable role keeps its context —
+        // guessing "stopped" from an unanswered probe silently discards a live
+        // conversation.
+        // An explicit operator `up` is the sanctioned way to release a held-down
+        // role: the still-alive runner polls this file and resumes (3.2).
+        resetRestartLedger(dir);
+        const live = await deps.backend.liveness(role.name)
+            .catch(e => ({ state: 'unknown', detail: e instanceof Error ? e.message : String(e) }));
+        if (live.state === 'stopped')
             rmSync(join(dir, '.booted'), { force: true });
-        await deps.backend.install(role.name, deps.binPath);
+        else if (live.state === 'unknown')
+            deps.log(`  ! ${role.name}: liveness unknown, keeping session context — ${live.detail}`);
+        // Report what each install actually did, so a creation transaction can undo
+        // only the registrations IT made (6.2). Announced immediately as well as
+        // returned: a later role in this same loop can throw, and the registrations
+        // already made must still be undoable.
+        const outcome = { ...await deps.backend.install(role.name, deps.binPath), role: role.name };
+        if (outcome.created)
+            deps.onInstalled?.(outcome);
+        outcomes.push(outcome);
         deps.log(`↑ up: ${role.name} (harness: ${role.harness}, identity: ${role.identity}${role.cwd ? `, cwd: ${role.cwd}` : ''})`);
     }
+    return outcomes;
 }
 export async function down(cfg, names, deps) {
     for (const role of selectRoles(cfg, names)) {
+        // Never swallow the backend's reason. "maybe not running" hid real stop
+        // failures — a wedged unit, an unreachable user bus — behind a guess.
         try {
             await deps.backend.stop(role.name);
             deps.log(`■ stopped ${role.name}`);
         }
-        catch {
-            deps.log(`  (could not stop ${role.name} — maybe not running)`);
+        catch (e) {
+            deps.log(`  ! could not stop ${role.name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
 }
 /** Re-sync from config + bounce. mode 'keep' resumes context; 'fresh' wipes it. */
 export async function restartRoles(cfg, names, deps, mode, configPath) {
     for (const role of selectRoles(cfg, names)) {
-        applyRole(role, { fresh: mode === 'fresh', configPath });
+        const dir = applyRole(role, { fresh: mode === 'fresh', configPath });
+        resetRestartLedger(dir); // explicit restart closes the circuit
         await deps.backend.restart(role.name);
         deps.log(mode === 'fresh'
             ? `↻ ${role.name} — force-restarted (FRESH — context cleared, briefing reloaded)`

package/dist/permissions.d.ts

@@ -0,0 +1,70 @@
+import type { CommonPermissions, ResolvedRole } from './config.js';
+import type { UnattendedCapability } from './harness/types.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 declare const UNATTENDED_FLOOR: readonly UnattendedCapability[];
+export interface FloorResult {
+    meets: boolean;
+    missing: UnattendedCapability[];
+}
+/** Which floor capabilities a set of granted capabilities fails to cover. */
+export declare function checkUnattendedFloor(granted: readonly UnattendedCapability[]): FloorResult;
+/**
+ * One role's neutral permissions, resolved through its harness adapter.
+ *
+ * Both `ours-fleet config` and `ours-fleet doctor` render this same object, so
+ * the two commands cannot disagree about what a configuration actually means.
+ * Before this existed, `translatePermissions()` was implemented by every
+ * adapter and called by nobody: the warnings it produced — including "this
+ * combination is not represented exactly" — were unreachable.
+ */
+export interface RolePermissionAnalysis {
+    role: string;
+    harness: string;
+    permissions: CommonPermissions;
+    /** Whether the harness can express neutral permissions at all. */
+    supported: boolean;
+    /** The harness's own settings, when it can. */
+    native?: Record<string, unknown>;
+    /** Whether those settings represent the neutral intent exactly. */
+    exact?: boolean;
+    /** What the native settings actually permit an unattended agent to do. */
+    capabilities?: UnattendedCapability[];
+    /** Whether those capabilities clear the unattended floor. */
+    floor?: FloorResult;
+    /**
+     * How hard a floor shortfall is. A role that auto-denies (`unattended: deny`)
+     * silently does less than asked, so that is a failure; one that waits can at
+     * least be rescued by a human attaching a console, so that is a warning.
+     */
+    floorSeverity?: 'fail' | 'warn';
+    /** Native settings that contradict the neutral block; empty when they agree. */
+    conflicts?: PermissionConflict[];
+    /** A role-named line when the floor is not met; absent when it is. */
+    floorWarning?: string;
+    /** Role-named translation warnings, ready to print verbatim by any command. */
+    warnings: string[];
+}
+export interface PermissionConflict {
+    /** The native setting both sources speak to, e.g. `permission_mode`. */
+    key: string;
+    /** What the neutral `permissions:` block translates to. */
+    fromNeutral: string;
+    /** What `harness_options` states directly. */
+    fromNative: string;
+    /** The role-named line commands print. */
+    warning: string;
+}
+/** Resolve one role's permissions through its adapter. Never throws. */
+export declare function analyzeRolePermissions(role: ResolvedRole): RolePermissionAnalysis;
+/** Every line a command should show for a role: translation, conflicts, floor. */
+export declare function allWarnings(a: RolePermissionAnalysis): string[];
+/** Resolve every role's permissions, in config order. */
+export declare function analyzeFleetPermissions(roles: ResolvedRole[]): RolePermissionAnalysis[];
+/** Render an analysis's native settings compactly, for one-line reporting. */
+export declare function formatNative(native: Record<string, unknown> | undefined): string;

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>;