@ours.network/fleet 0.10.0-nightly.4 → 0.10.1

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,7 +16,16 @@ 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;
 }
+/**
+ * Record who owns wake delivery for this run. Returning true means a fleet
+ * monitor is taking ownership back from a native harness and must start at the
+ * current stream tip rather than replay notifications the native owner was
+ * responsible for.
+ */
+export declare function recordMonitorOwner(dir: string, owner: 'fleet' | 'native'): boolean;
 /**
  * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
  * `paneArgv` defaults to `launch.argv`; when isolation is active the caller passes
@@ -24,6 +34,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 +82,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>;