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

package/dist/isolation/policy.js

@@ -1,5 +1,57 @@
-import { join, dirname } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { BACKENDS, ON_UNAVAILABLE, NETWORK_MODES, } from './types.js';
+/** A mount that the forbidden-path policy refuses. Raised before any launch. */
+export class IsolationPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IsolationPolicyError';
+    }
+}
+/**
+ * Resolve a path to its canonical form, following symlinks as far as the
+ * filesystem allows and normalising the rest. Without this, `~/link-to-ssh`
+ * and `/home/u/.ssh` are different strings for the same directory, and a
+ * string comparison against the forbidden list is trivially side-stepped.
+ */
+export function canonicalPath(p) {
+    const abs = resolve(p);
+    let head = abs;
+    let tail = '';
+    for (;;) {
+        try {
+            return tail ? join(realpathSync.native(head), tail) : realpathSync.native(head);
+        }
+        catch {
+            const parent = dirname(head);
+            if (parent === head)
+                return abs; // nothing on this path exists yet
+            tail = tail ? join(basename(head), tail) : basename(head);
+            head = parent;
+        }
+    }
+}
+const within = (child, parent) => child === parent || child.startsWith(parent + sep);
+/**
+ * How a canonical mount path collides with a canonical forbidden path.
+ *
+ * `parent` matters as much as the other two: binding `$HOME` does not name
+ * `~/.ssh`, but it exposes it just as completely.
+ */
+export function mountConflict(mount, forbidden) {
+    if (mount === forbidden)
+        return 'exact';
+    if (within(mount, forbidden))
+        return 'descendant';
+    if (within(forbidden, mount))
+        return 'parent';
+    return null;
+}
+const CONFLICT_WORDING = {
+    exact: 'is',
+    descendant: 'is inside',
+    parent: 'would expose',
+};
 /** Read-only system dirs exposed under the allowlist model. */
 const SYSTEM_RO = ['/usr', '/bin', '/sbin', '/lib', '/lib64', '/etc'];
 /** Ephemeral scratch mounts. */
@@ -52,6 +104,12 @@ export function validateIsolationConfig(raw) {
     }
     return problems;
 }
+/**
+ * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * own state directory, so it is covered by the state dir's existing lifecycle
+ * and by the forbidden-path exception, and is never shared with a peer.
+ */
+export const harnessRuntimeDir = (stateDir, harnessId) => join(stateDir, 'harness', harnessId);
 /** Parse a `host:container` secret pair; a bare path maps to itself. */
 function parseSecret(pair) {
     const i = pair.indexOf(':');
@@ -61,12 +119,17 @@ function parseSecret(pair) {
 }
 /**
  * Resolve a raw (already validated) isolation block against runtime context into
- * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ * a defaults-filled, backend-agnostic policy, and REFUSE any mount that would
+ * breach the forbidden-path list.
+ *
+ * The mount model is an allowlist: only the durable set (state dir, cwd, harness
+ * config, declared fs/secrets) plus read-only system dirs are exposed. The
+ * forbidden list — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws
+ * — is now enforced on top of that, so a role cannot ask its way back in.
  *
- * The mount model is an allowlist: only the durable set (state dir, cwd, Claude
- * config, declared fs/secrets) plus read-only system dirs are exposed; everything
- * else on the host — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws —
- * is simply never mounted, and thus absent inside the sandbox (§5.2).
+ * Not pure: canonicalising a path reads the filesystem, because symlink aliases
+ * are one of the ways a forbidden path gets requested. Throws
+ * `IsolationPolicyError`; callers surface it against the role.
  */
 export function resolveIsolation(cfg, ctx) {
     const { stateDir, runCwd, home } = ctx;
@@ -75,10 +138,26 @@ export function resolveIsolation(cfg, ctx) {
         mounts.push({ src: p, dst: p, mode: 'rw' }); };
     const addRo = (p) => { if (!mounts.some(m => m.src === p))
         mounts.push({ src: p, dst: p, mode: 'ro' }); };
+    /** Writable bind whose destination differs from its source (the per-role home). */
+    const addRw2 = (src, dst) => {
+        if (!mounts.some(m => m.src === src && m.dst === dst))
+            mounts.push({ src, dst, mode: 'rw' });
+    };
     // Durable set: state dir + cwd, then only the active harness's config/auth roots.
     addRw(stateDir);
     addRw(runCwd);
-    if (ctx.harness === 'codex') {
+    if (ctx.harnessHome && ctx.harnessRuntimeDir) {
+        // The harness home is backed by a PER-ROLE directory (5.1): the agent gets a
+        // writable home for its sessions, caches and history, and anything a future
+        // CLI version writes lands there too. The shared credentials, global
+        // instructions and configuration are then layered back read-only, so they
+        // are readable and cannot be rewritten — for this role or for its peers.
+        // Order matters: the writable home must precede the read-only overlays.
+        addRw2(ctx.harnessRuntimeDir, ctx.harnessHome);
+        for (const p of ctx.harnessSharedPaths ?? [])
+            addRo(p);
+    }
+    else if (ctx.harness === 'codex') {
         addRw(join(home, '.codex'));
         addRo(join(home, '.agents'));
     }
@@ -105,6 +184,34 @@ export function resolveIsolation(cfg, ctx) {
         ...SENSITIVE_HOME.map(p => join(home, p)),
         agentsRoot, // sibling agents' state dirs (this agent's own is explicitly mounted)
     ];
+    // ENFORCE the list, before anything builds a backend argv. Until now it was
+    // observational: the allowlist model kept these paths out by default, but a
+    // role that asked for one in `fs.write`, `secrets`, or a Codex `add_dirs` got
+    // it mounted anyway, and the "blocklist" recorded a guarantee it never made.
+    //
+    // The role's OWN state dir is the one legitimate descendant of the agents
+    // root, so it is excepted by exact canonical identity — which does not
+    // exempt its parent, and does not exempt a sibling.
+    const forbidden = blocklist.map(canonicalPath);
+    const ownStateDir = canonicalPath(stateDir);
+    for (const m of mounts) {
+        for (const [role, path] of [['source', m.src], ['destination', m.dst]]) {
+            const canon = canonicalPath(path);
+            // The role's own state dir and anything inside it (its per-role harness
+            // runtime home, 5.1) is the one legitimate descendant of the agents root.
+            // This does not exempt the root above it, nor a sibling beside it.
+            if (within(canon, ownStateDir))
+                continue;
+            for (let i = 0; i < forbidden.length; i++) {
+                const kind = mountConflict(canon, forbidden[i]);
+                if (!kind)
+                    continue;
+                const alias = canon === resolve(path) ? '' : ` (resolves to '${canon}')`;
+                throw new IsolationPolicyError(`isolation: refusing to mount ${role} '${path}'${alias} — it ` +
+                    `${CONFLICT_WORDING[kind]} the forbidden path '${blocklist[i]}'`);
+            }
+        }
+    }
     return {
         backend: cfg.backend ?? 'auto',
         onUnavailable: cfg.on_unavailable ?? 'warn',

package/dist/isolation/resources.d.ts

@@ -5,9 +5,12 @@ export interface ResourceArgs {
 }
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): because tmux
- * panes are children of the shared tmux server rather than the per-role unit, the
- * only reliable per-agent limit is a transient scope at the pane itself.
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * a child of a tmux SERVER rather than of the role's own runner process, so the
+ * only reliable per-agent limit is a transient scope at the pane itself. (Since
+ * #32 that server is per role rather than fleet-wide, which is what keeps one
+ * role's `stop` off every other role's pane — the limit still belongs on the
+ * pane.)
  *
  * mem/pids are always enforced (their controllers are delegated to `--user` by
  * default). cpu degrades to a warning when the cpu controller is not delegated.

package/dist/isolation/resources.js

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs';
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): because tmux
- * panes are children of the shared tmux server rather than the per-role unit, the
- * only reliable per-agent limit is a transient scope at the pane itself.
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * a child of a tmux SERVER rather than of the role's own runner process, so the
+ * only reliable per-agent limit is a transient scope at the pane itself. (Since
+ * #32 that server is per role rather than fleet-wide, which is what keeps one
+ * role's `stop` off every other role's pane — the limit still belongs on the
+ * pane.)
  *
  * mem/pids are always enforced (their controllers are delegated to `--user` by
  * default). cpu degrades to a warning when the cpu controller is not delegated.

package/dist/isolation/types.d.ts

@@ -50,6 +50,19 @@ export interface WrapContext {
     harness?: string;
     /** Harness-declared writable roots (for example Codex --add-dir). */
     additionalWriteDirs?: string[];
+    /**
+     * The harness's home directory on the host (`~/.claude`, `~/.codex`). Mounted
+     * from `harnessRuntimeDir` so the agent's own runtime state is per-role (5.1).
+     */
+    harnessHome?: string;
+    /** Per-role writable directory backing `harnessHome` inside the sandbox. */
+    harnessRuntimeDir?: string;
+    /**
+     * Shared credentials, global instructions and configuration. Mounted READ-ONLY
+     * on top of the per-role home, so an agent can read them and cannot rewrite
+     * them for itself or for its peers.
+     */
+    harnessSharedPaths?: string[];
     brokerEndpoint?: string;
 }
 /**
@@ -68,7 +81,12 @@ export interface ResolvedIsolation {
     system: string[];
     /** ephemeral scratch tmpfs mounts (/tmp, ~/.cache). */
     tmpfs: string[];
-    /** sensitive host paths guaranteed absent from the sandbox (observability). */
+    /**
+     * Sensitive host paths that are ENFORCED absent from the sandbox: any mount
+     * that is, sits inside, or would expose one of these is refused by
+     * `resolveIsolation` before a backend argv is built. Retained on the resolved
+     * policy for diagnostics — doctor and `config` report what is being enforced.
+     */
     blocklist: string[];
 }
 /** A pluggable isolation backend (bubblewrap, podman, none). */

package/dist/monitor.d.ts

@@ -38,14 +38,29 @@ export interface MonitorDeps {
         set(fn: () => void, ms: number): ReturnType<typeof setTimeout>;
         clear(t: ReturnType<typeof setTimeout>): void;
     };
-    /** Structured prompt delivery used by ACP sessions. Tmux remains the fallback. */
+    /**
+     * Structured prompt delivery used by ACP sessions. Tmux remains the fallback.
+     * `succeeded` is the turn's TERMINAL result, not merely that the session took
+     * the prompt: a refused or cancelled wake was seen and not acted on, and must
+     * not commit the cursor.
+     */
     delivery?: {
-        submit(text: string): Promise<{
-            accepted: boolean;
+        submit(text: string, options?: {
+            interrupt?: boolean;
+        }): Promise<{
+            succeeded: boolean;
+            outcome: string;
             detail?: string;
         }>;
     };
 }
+/**
+ * Why the monitor is not healthy. Each cause clears on its OWN recovery signal
+ * and nothing else — a successful poll proves the stream works, and proves
+ * nothing whatsoever about whether wakes are being delivered or whether the
+ * turns they trigger keep dying.
+ */
+export type StatusCause = 'connectivity' | 'delivery' | 'modal' | 'offline' | 'turns-failing' | 'auth';
 /** Best-effort daemon config (issue #17): the fields the MCP client reads. */
 interface DaemonConfig {
     apiToken?: string;
@@ -149,6 +164,8 @@ export declare class Monitor {
     private currentAbort;
     private apiErrorStreak;
     private readonly turnFailThreshold;
+    /** Active degradations, keyed by cause. Empty means armed. */
+    private readonly causes;
     constructor(o: MonitorOpts);
     /** Resume the last delivered cursor; only a brand-new monitor primes at stream tip. */
     prime(): Promise<void>;
@@ -190,7 +207,19 @@ export declare class Monitor {
     private readPersistedCursor;
     /** Atomically persist body-free delivery state; restart always resumes from deliveredCursor. */
     private persistState;
-    private setStatus;
+    /** Record a degradation under its own cause and republish the status. */
+    private degrade;
+    /**
+     * Clear exactly the causes this recovery signal speaks to. Anything else
+     * stays: one successful poll must never be able to erase `turns failing`.
+     */
+    private recover;
+    /**
+     * 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.
+     */
+    private writeStatus;
 }
 export declare function createMonitor(o: MonitorOpts): Monitor;
 export {};

package/dist/monitor.js

@@ -234,11 +234,73 @@ export function looksRunning(pane) {
         return true; // "(12s · … tokens)" elapsed meter
     return false;
 }
-/** Is the injected line still sitting unsubmitted in the composer (bottom of pane)? */
+const COMPOSER_TOP = /^[^\S\n]*[╭┌][─━]/;
+const COMPOSER_BOTTOM = /^[^\S\n]*[╰└][─━]/;
+const COMPOSER_PROMPT = /^[^\S\n]*(?:[│┃|][^\S\n]*)?[❯›>][^\S\n]*$/;
+/**
+ * Remove wrapping-only whitespace and box chrome from composer rows. Notification
+ * lines contain no meaningful whitespace distinction, so this lets a fragment
+ * cross an arbitrary terminal wrap without matching unrelated transcript text.
+ */
+function normalizeComposerRows(rows) {
+    return rows.map((raw, i) => {
+        let row = raw;
+        if (i > 0)
+            row = row.replace(/^[^\S\n]*(?:[│┃|][^\S\n]*)?/, '');
+        row = row.replace(/[^\S\n]*(?:[│┃|])?[^\S\n]*$/, '');
+        return row;
+    }).join('').replace(/\s+/g, '');
+}
+/**
+ * Is the injected line still sitting unsubmitted in the composer?
+ *
+ * The footer has variable height and the line may wrap across any number of
+ * rows, so a fixed tail window cannot identify the composer. Prefer the final
+ * bordered composer region; for a borderless/truncated capture, require the
+ * notification prefix to follow a composer prompt. This keeps old submitted
+ * wake lines in the transcript from causing stray Enters.
+ */
 function stillInComposer(pane, line) {
-    const frag = line.slice(0, 48);
-    const tail = pane.split('\n').slice(-4).join('\n');
-    return tail.includes(frag);
+    if (!pane)
+        return false; // dead pane: do not waste Enters
+    const lines = pane.split('\n');
+    let bottom = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (COMPOSER_BOTTOM.test(lines[i])) {
+            bottom = i;
+            break;
+        }
+    }
+    let top = -1;
+    if (bottom >= 0) {
+        for (let i = bottom - 1; i >= 0; i--) {
+            if (COMPOSER_TOP.test(lines[i])) {
+                top = i;
+                break;
+            }
+        }
+    }
+    const from = top >= 0 ? top + 1 : 0;
+    const to = bottom >= 0 ? bottom : lines.length;
+    let wakeRow = -1;
+    let wakeColumn = -1;
+    for (let i = to - 1; i >= from; i--) {
+        const column = lines[i].lastIndexOf(PREFIX);
+        if (column >= 0) {
+            wakeRow = i;
+            wakeColumn = column;
+            break;
+        }
+    }
+    if (wakeRow < 0)
+        return false;
+    // Without both box boundaries, only trust text visibly in a composer prompt.
+    // This is the safe fallback for borderless TUIs and truncated captures.
+    if (top < 0 && !COMPOSER_PROMPT.test(lines[wakeRow].slice(0, wakeColumn)))
+        return false;
+    const rows = lines.slice(wakeRow, to);
+    rows[0] = rows[0].slice(wakeColumn);
+    return normalizeComposerRows(rows).includes(line.replace(/\s+/g, ''));
 }
 export class Monitor {
     name;
@@ -260,6 +322,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 +342,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 +371,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 +416,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;
@@ -381,20 +447,27 @@ export class Monitor {
     async deliver(pid, batch) {
         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})` : ''}`);
+            const result = await this.deps.delivery.submit(line, { interrupt: this.cfg.interrupt });
+            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.recordTurn('completed');
+            this.recover('delivery', 'modal');
+            if (result.detail !== 'injected' && result.detail !== 'startedNewTurn')
+                this.recordTurn('completed');
             return true;
         }
+        if (this.cfg.interrupt)
+            await this.deps.tmux.sendKey(this.name, 'C-c');
         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;
         }
@@ -404,11 +477,25 @@ export class Monitor {
         // Verify submission for THIS line even if stop() arrives mid-flight: the text
         // is already in the composer and we want it submitted (at-least-once). A truly
         // dead pane makes safeCapture return '' ⇒ not-in-composer ⇒ breaks, no wasted Enter.
-        for (let i = 0; i < MAX_ENTER_RETRIES; i++) {
+        for (let i = 0; i < MAX_ENTER_RETRIES;) {
             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;
+            }
+            // A dialog can appear after the initial send. Never let a verification
+            // retry confirm it. Wait under the same bounded modal policy as initial
+            // injection, then re-capture immediately before considering Enter.
+            if (looksModal(capture.pane)) {
+                const state = await this.awaitInjectable(pid);
+                if (state === 'ready')
+                    continue;
+                if (state === 'offline')
+                    this.degrade('offline', 'offline during injection verification');
+                else if (state === 'modal')
+                    this.degrade('modal', `modal wedge during injection verification — ` +
+                        `no Enter sent for ${MODAL_GIVE_UP_MS / 1000}s`);
                 return false;
             }
             if (!stillInComposer(capture.pane, line)) {
@@ -416,11 +503,13 @@ export class Monitor {
                 break;
             }
             await this.deps.tmux.sendKey(this.name, 'Enter');
+            i++;
         }
         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 +531,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 +548,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 +592,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 +684,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>;