@ours.network/fleet 0.17.1 → 0.17.3

package/dist/monitor.js

@@ -109,6 +109,48 @@ export function resolveEndpoint(env) {
         headers: token ? { 'x-ours-api-token': token } : {},
     };
 }
+/**
+ * Ask the daemon's authoritative identity index. The notifications endpoint is
+ * intentionally unsuitable for lifecycle: it serves an empty 200 page for a
+ * valid but missing identity, which made a closed temp identity look healthy.
+ */
+export async function probeIdentityPresence(name, fetch, env) {
+    const ep = resolveEndpoint(env);
+    let response;
+    try {
+        response = await fetch(`${ep.origin}/identities`, { headers: ep.headers });
+    }
+    catch (error) {
+        return { state: 'unknown', detail: `identity index unreachable (${msg(error)})` };
+    }
+    if (!response.ok)
+        return {
+            state: 'unknown',
+            detail: response.status === 401
+                ? `daemon rejected the API token (401) — ${authResolutionHint(ep)}`
+                : `identity index returned HTTP ${response.status}`,
+        };
+    try {
+        const body = await response.json();
+        if (!Array.isArray(body.identities))
+            return { state: 'unknown', detail: 'identity index response is malformed' };
+        // A healthy daemon normally has at least its Human identity. During daemon
+        // restart, however, the authenticated endpoint can briefly serve a valid
+        // but empty index while state is still loading. Empty is therefore not
+        // enough authority to retire a live temporary role.
+        if (body.identities.length === 0)
+            return { state: 'unknown', detail: 'identity index is temporarily empty' };
+        const found = body.identities.find(identity => (typeof identity === 'string' ? identity : identity?.name) === name);
+        if (!found)
+            return { state: 'absent' };
+        return typeof found === 'string'
+            ? { state: 'present', temporary: false, stale: false }
+            : { state: 'present', temporary: found.temporary === true, stale: found.stale === true };
+    }
+    catch (error) {
+        return { state: 'unknown', detail: `identity index response is unreadable (${msg(error)})` };
+    }
+}
 /** Actionable, secret-free description of every token source for this profile. */
 export function authResolutionHint(ep) {
     const tokenPath = join(ep.stateDir, 'daemon-token');

package/dist/ops.d.ts

@@ -1,5 +1,6 @@
 import type { FleetConfig, ResolvedRole } from './config.js';
 import type { InstallOutcome as BackendInstallOutcome, SupervisorBackend } from './supervisor/types.js';
+import { type Exec } from './exec.js';
 /** An install outcome tagged with the role it belongs to. */
 export interface InstallOutcome extends BackendInstallOutcome {
     role: string;
@@ -8,6 +9,11 @@ export interface OpsDeps {
     backend: SupervisorBackend;
     binPath: string;
     log(line: string): void;
+    /** Process/service inspection for exact temporary-supervisor lifecycle commands. */
+    exec?: Exec;
+    /** Test seam for exact detached-supervisor signaling/liveness. */
+    kill?(pid: number, signal: NodeJS.Signals | 0): void;
+    sleep?(ms: number): Promise<void>;
     /**
      * Called the INSTANT a registration is created, before anything else can
      * fail. A creation transaction that learns about registrations only from

package/dist/ops.js

@@ -6,6 +6,8 @@ import { findRole } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { generateBriefing } from './briefing.js';
 import { resetRestartLedger } from './runner.js';
+import { archiveTempState, stopTempSupervisor, tempSupervisorLiveness, } from './temp-lifecycle.js';
+import { realExec } from './exec.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
@@ -174,7 +176,23 @@ async function reconcileWatchdogScheduler(cfg, deps, configPath) {
     }
 }
 export async function down(cfg, names, deps) {
-    for (const role of selectRoles(cfg, names)) {
+    const roles = names.length ? names.map(name => cfg.roles.find(role => role.name === name)) : cfg.roles;
+    for (let index = 0; index < roles.length; index++) {
+        const role = roles[index];
+        const requested = names[index];
+        if (!role && requested && /^[A-Za-z0-9_-]+$/.test(requested)
+            && existsSync(agentDir(requested, true))) {
+            try {
+                const outcome = await stopTempSupervisor(requested, { exec: deps.exec ?? realExec });
+                deps.log(`■ ${outcome === 'stopped' ? 'stopping' : 'stopped'} temporary role ${requested}`);
+            }
+            catch (e) {
+                deps.log(`  ! could not stop temporary role ${requested}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            continue;
+        }
+        if (!role)
+            throw new Error(`no such role '${requested}'`);
         // Never swallow the backend's reason. "maybe not running" hid real stop
         // failures — a wedged unit, an unreachable user bus — behind a guess.
         try {
@@ -213,6 +231,33 @@ export async function restartRoles(cfg, names, deps, mode, configPath) {
 }
 /** Stop + forget a role: unit, state dir, and its fleet.d file when spawned. */
 export async function rmRole(cfg, name, deps) {
+    const temporaryDir = /^[A-Za-z0-9_-]+$/.test(name) ? agentDir(name, true) : '';
+    const configured = cfg.roles.find(role => role.name === name);
+    if (!configured && temporaryDir && existsSync(temporaryDir)) {
+        const lifecycleDeps = { exec: deps.exec ?? realExec, ...(deps.kill ? { kill: deps.kill } : {}) };
+        const stopOutcome = await stopTempSupervisor(name, lifecycleDeps);
+        const sleep = deps.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+        let liveness = stopOutcome === 'already-stopped' ? 'stopped' : 'unknown';
+        // The supervisor normally archives itself. A detached fallback may keep
+        // running after SIGTERM, so directory age or a fixed delay is never
+        // cleanup authority: poll exact ownership and archive only after a proven
+        // stop. Unknown and still-running both fail closed with evidence in place.
+        for (let i = 0; i < 50 && existsSync(temporaryDir) && liveness !== 'stopped'; i++) {
+            liveness = await tempSupervisorLiveness(temporaryDir, lifecycleDeps);
+            if (liveness === 'stopped')
+                break;
+            if (i < 49)
+                await sleep(100);
+        }
+        if (existsSync(temporaryDir) && liveness !== 'stopped')
+            throw new Error(`temporary role '${name}' supervisor is ${liveness}; refusing to archive live or ambiguous state`);
+        const archived = existsSync(temporaryDir)
+            ? archiveTempState(name, 'operator-stop', 'retired', 'operator removal completed after supervisor liveness was proven stopped; evidence preserved')
+            : undefined;
+        deps.log(`removed temporary role '${name}'`
+            + `${archived ? `; evidence archived at ${archived}` : '; supervisor archived its evidence'}`);
+        return;
+    }
     const role = findRole(cfg, name);
     await deps.backend.uninstall(name);
     rmSync(agentDir(name), { recursive: true, force: true });

package/dist/owner-channel/channel.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { type OwnerChannelConfig } from '../config.js';
-import type { SessionHandle } from '../session/types.js';
+import { type FetchLike } from '../monitor.js';
+import { type SessionHandle } from '../session/types.js';
 import { type OwnerFleetOps } from './commands.js';
 import type { ManagedFleetSpawnResult } from '../fleet-proxy.js';
 import { type OursToolClient } from './mcp.js';
@@ -19,8 +20,12 @@ export interface OwnerChannelOptions {
     command?: string;
     log(line: string): void;
     client?: OursToolClient;
-    /** Test seam; production uses `ours-mcp watch <identity>`. */
+    /** Legacy child-process test seam; production uses the direct notification API. */
     watch?: (identity: string) => ChildProcessWithoutNullStreams;
+    /** Test seam for the production direct notification long-poll. */
+    watchFetch?: FetchLike;
+    /** Test seam for the long-poll stall bound; production uses OWNER_WATCH_STALL_MS. */
+    watchStallMs?: number;
     /** Test seam; production uses the detached ours-fleet CLI (`fleetCliOps`). */
     fleet?: OwnerFleetOps;
     /** Forwarded to fleet CLI invocations spawned for owner commands. */
@@ -152,6 +157,7 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     private stopping;
     private watchProcess?;
     private watchTask?;
+    private watchAbort?;
     private drainTask?;
     private drainRequested;
     private readonly completionTasks;
@@ -250,6 +256,16 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     /** Map only event shape and allowlisted status to owner-safe phase text. */
     private progressPhase;
     private watchLoop;
+    /**
+     * `recovered` distinguishes a first-ever start (no state, nothing lost) from a
+     * cursor we HAD and can no longer read. Only the latter is a recovery, and the
+     * caller needs to know because the reason it reports is the only evidence a
+     * durable cursor was ever lost.
+     */
+    private readWatchState;
+    private writeWatchState;
+    /** Compatibility path for injected child-process tests; production is direct. */
+    private legacyWatchLoop;
     private errorText;
     private logError;
 }

package/dist/owner-channel/channel.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, readdir, rm } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { join } from 'node:path';
 import { DEFAULT_OWNER_ATTACHMENT_MIME, canonicalCid, } from '../config.js';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { resolveEndpoint } from '../monitor.js';
+import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, interruptOutcome, } from '../session/types.js';
 import { VERSION } from '../version.js';
 import { dispatchOwnerCommand, fleetCliOps, isOwnerCommandText, } from './commands.js';
 import { OursMcpClient } from './mcp.js';
@@ -24,6 +28,15 @@ const COMMENTARY_MAX_CHARS = 1_600;
 const COMMENTARY_MAX_BYTES = 6_400;
 const COMMENTARY_MAX_UPDATES = 32;
 const COMMENTARY_DEDUPE_LIMIT = 512;
+const OWNER_WATCH_STALL_MS = 120_000;
+const OWNER_WATCH_BACKOFF_MAX_MS = 30_000;
+/**
+ * Credentials that are wrong now are wrong on the next attempt too. Retrying a
+ * permanent 401 forever burns the daemon and hides the real fault behind an
+ * endless reconnect log, so the watch stops after this many consecutive auth
+ * rejections and records a terminal reason instead.
+ */
+const OWNER_WATCH_AUTH_FATAL_ATTEMPTS = 5;
 /** A relay attempt that failed only because no owner route exists yet. */
 class RelayUnroutableError extends Error {
 }
@@ -59,6 +72,7 @@ export class OwnerChannel {
     stopping = false;
     watchProcess;
     watchTask;
+    watchAbort;
     drainTask;
     drainRequested = false;
     completionTasks = new Set();
@@ -136,7 +150,7 @@ export class OwnerChannel {
             void cleanupAttachmentRoot(this.attachmentRoot, Date.now(), this.attachmentConfig.retention_ms).catch(error => this.logError('attachment crash cleanup failed', error));
         }
         this.ready = true;
-        this.watchTask = this.watchLoop();
+        this.watchTask = this.options.watch ? this.legacyWatchLoop() : this.watchLoop();
         // Do not make role startup wait for an old owner request to finish a turn.
         void this.drain().catch(error => this.logError('initial drain failed', error));
     }
@@ -159,6 +173,10 @@ export class OwnerChannel {
         this.watchProcess = undefined;
         if (watch && watch.exitCode === null)
             watch.kill('SIGTERM');
+        this.watchAbort?.abort();
+        if (!this.options.watch)
+            await this.watchTask?.catch(error => this.logError('watch shutdown failed', error));
+        this.watchTask = undefined;
         await this.managementTail;
         try {
             await this.client.close();
@@ -825,6 +843,15 @@ export class OwnerChannel {
         }
         catch (error) {
             await rm(outbox, { recursive: true, force: true });
+            if (error instanceof SessionControlError
+                && error.reasonCode === ACP_CANCEL_DEADLINE_EXCEEDED) {
+                // drainAll deferred this authenticated message before delivery. The
+                // adapter generation is terminating, so leave the wire unhandled and
+                // body-free: the resumed owner channel will replay it exactly once.
+                this.options.log(`[${this.options.role}] owner request ${requestId.slice(0, 12)} `
+                    + `held for adapter resume reason=${ACP_CANCEL_DEADLINE_EXCEEDED}`);
+                return false;
+            }
             this.logError('request delivery failed', error);
             await this.send(sender.id, ownerNotices.deliveryFailed(this.options.role), wireId);
             this.state.remember(wireId);
@@ -874,7 +901,7 @@ export class OwnerChannel {
             harness: this.options.harness,
             version: VERSION,
             snapshot: () => this.options.session.snapshot(),
-            interrupt: () => this.options.session.interrupt('owner'),
+            interrupt: async () => interruptOutcome(await this.options.session.interrupt('owner')),
             runHarnessCommand: command => this.runHarnessCommand(sender, command, wireId),
             restart: mode => this.restartSelf(sender, mode, wireId),
             comments: () => this.commentsState(),
@@ -1549,6 +1576,123 @@ export class OwnerChannel {
         return undefined;
     }
     async watchLoop() {
+        const endpoint = resolveEndpoint({ ...process.env, ...(this.options.env ?? {}) });
+        const fetch = this.options.watchFetch
+            ?? ((url, init) => globalThis.fetch(url, init));
+        const sleep = this.options.binderDeps?.sleep
+            ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+        const restored = this.readWatchState();
+        let state = restored.state;
+        // An unreadable cursor is the ONLY reason to restart at the tip. Say so on
+        // the next successful connect, and drain first: everything the lost cursor
+        // would have pointed at is still in the inbox, which is the authority.
+        let recovering = restored.recovered;
+        let cursor = state?.cursor ?? 'tip';
+        let delayMs = 1_000;
+        let authFailures = 0;
+        if (recovering)
+            await this.drain().catch(error => this.logError('cursor recovery drain failed', error));
+        while (!this.stopping) {
+            const ctrl = new AbortController();
+            this.watchAbort = ctrl;
+            let stalled = false;
+            let authRejected = false;
+            const timer = setTimeout(() => { stalled = true; ctrl.abort(); }, this.options.watchStallMs ?? OWNER_WATCH_STALL_MS);
+            timer.unref?.();
+            try {
+                const response = await fetch(`${endpoint.url(this.options.config.identity)}?since=${cursor}`, { headers: endpoint.headers, signal: ctrl.signal });
+                if (response.status === 401) {
+                    authRejected = true;
+                    authFailures++;
+                    const at = cursor === 'tip' ? state?.cursor ?? 0 : cursor;
+                    if (authFailures >= OWNER_WATCH_AUTH_FATAL_ATTEMPTS) {
+                        state = this.writeWatchState(state, at, 'OWNER_WATCH_AUTH_FATAL', true);
+                        this.options.log(`[${this.options.role}] owner watch stopped `
+                            + `reason=OWNER_WATCH_AUTH_FATAL after ${authFailures} consecutive HTTP 401 responses; `
+                            + 'owner notifications require re-authorization and will not be retried');
+                        return;
+                    }
+                    state = this.writeWatchState(state, at, 'OWNER_WATCH_AUTH_FAILED', true);
+                    throw new Error('OWNER_WATCH_AUTH_FAILED: daemon rejected notification credentials');
+                }
+                if (!response.ok)
+                    throw new Error(`daemon returned HTTP ${response.status}`);
+                const body = await response.json();
+                const next = typeof body.cursor === 'number' ? body.cursor : cursor === 'tip' ? 0 : cursor;
+                const reconnect = (state?.consecutiveFailures ?? 0) > 0;
+                state = this.writeWatchState(state, next, recovering ? 'OWNER_WATCH_CURSOR_RECOVERED' : 'OWNER_WATCH_CONNECTED', false, reconnect);
+                recovering = false;
+                authFailures = 0;
+                cursor = next;
+                delayMs = 1_000;
+                // Notification events are content-free hints. The inbox remains the
+                // authority and its wire-level durable dedupe prevents duplicate turns.
+                if ((body.events?.length ?? 0) > 0)
+                    await this.drain();
+            }
+            catch (error) {
+                if (this.stopping)
+                    return;
+                const reason = stalled
+                    ? 'OWNER_WATCH_STALLED' : 'OWNER_WATCH_STREAM_ERROR';
+                const current = cursor === 'tip' ? state?.cursor ?? 0 : cursor;
+                cursor = current;
+                // Only THIS iteration's auth rejection is already written. A stale
+                // AUTH_FAILED from an earlier attempt must never suppress the cursor,
+                // the failure counter, or a later STALLED transition.
+                if (!authRejected)
+                    state = this.writeWatchState(state, current, reason, true);
+                this.options.log(`[${this.options.role}] owner watch reconnect `
+                    + `reason=${authRejected ? 'OWNER_WATCH_AUTH_FAILED' : reason} `
+                    + `delay_ms=${delayMs} cursor=${current}`);
+                await sleep(delayMs);
+                delayMs = Math.min(delayMs * 2, OWNER_WATCH_BACKOFF_MAX_MS);
+            }
+            finally {
+                clearTimeout(timer);
+                if (this.watchAbort === ctrl)
+                    this.watchAbort = undefined;
+            }
+        }
+    }
+    /**
+     * `recovered` distinguishes a first-ever start (no state, nothing lost) from a
+     * cursor we HAD and can no longer read. Only the latter is a recovery, and the
+     * caller needs to know because the reason it reports is the only evidence a
+     * durable cursor was ever lost.
+     */
+    readWatchState() {
+        const path = join(this.options.stateDir, '.owner-channel-watch.json');
+        if (!existsSync(path))
+            return { recovered: false };
+        try {
+            const value = JSON.parse(readFileSync(path, 'utf8'));
+            if (value.version !== 1 || !Number.isSafeInteger(value.cursor) || value.cursor < 0
+                || !Number.isSafeInteger(value.reconnects) || value.reconnects < 0
+                || !Number.isSafeInteger(value.consecutiveFailures) || value.consecutiveFailures < 0)
+                throw new Error('invalid owner watch state');
+            return { state: value, recovered: false };
+        }
+        catch {
+            this.options.log(`[${this.options.role}] owner watch `
+                + 'reason=OWNER_WATCH_CURSOR_RECOVERED invalid cursor state; draining inbox and starting at tip');
+            return { recovered: true };
+        }
+    }
+    writeWatchState(previous, cursor, reason, failed, reconnected = false) {
+        const state = {
+            version: 1,
+            cursor,
+            reconnects: (previous?.reconnects ?? 0) + (reconnected ? 1 : 0),
+            consecutiveFailures: failed ? (previous?.consecutiveFailures ?? 0) + 1 : 0,
+            reason,
+            updatedAt: new Date(this.options.binderDeps?.now?.() ?? Date.now()).toISOString(),
+        };
+        replaceFileAtomically(join(this.options.stateDir, '.owner-channel-watch.json'), `${JSON.stringify(state)}\n`, 0o600);
+        return state;
+    }
+    /** Compatibility path for injected child-process tests; production is direct. */
+    async legacyWatchLoop() {
         let delayMs = 1_000;
         while (!this.stopping) {
             try {

package/dist/owner-channel/commands.d.ts

@@ -1,4 +1,4 @@
-import type { SessionEvent, SessionSnapshot } from '../session/types.js';
+import type { InterruptOutcome, SessionEvent, SessionSnapshot } from '../session/types.js';
 import { type OwnerCommentsState } from './notices.js';
 /**
  * Fleet-level effects a deterministic owner command may trigger. Production
@@ -22,7 +22,7 @@ export interface OwnerCommandContext {
     harness: string;
     version: string;
     snapshot(): SessionSnapshot;
-    interrupt(): Promise<void>;
+    interrupt(): Promise<InterruptOutcome>;
     /**
      * Deliver raw slash text to the agent harness. Only commands the bundled
      * ACP adapter for `harness` verifiably executes locally may be forwarded

package/dist/owner-channel/commands.js

@@ -71,13 +71,18 @@ export const ownerCommands = [
     {
         name: 'interrupt', summary: "cancel the agent's active turn",
         execute: noArgs('/interrupt', async (ctx) => {
+            let outcome;
+            // Only a cancellation that never reached the session is a failure. A
+            // forced recovery stopped the turn: say so, and say it plainly.
             try {
-                await ctx.interrupt();
+                outcome = await ctx.interrupt();
             }
             catch {
                 return ctx.reply(ownerNotices.interruptFailed(ctx.role));
             }
-            await ctx.reply(ownerNotices.interrupted(ctx.role));
+            await ctx.reply(outcome?.state === 'forced'
+                ? ownerNotices.interruptForced(ctx.role)
+                : ownerNotices.interrupted(ctx.role));
         }),
     },
     {

package/dist/owner-channel/notices.d.ts

@@ -24,6 +24,8 @@ export declare const ownerNotices: {
     receivedInterrupting: () => string;
     status: (role: string, snapshot: SessionSnapshot) => string;
     interrupted: (role: string) => string;
+    /** The turn IS cancelled — say how, without implying the owner must retry. */
+    interruptForced: (role: string) => string;
     interruptFailed: (role: string) => string;
     commandStarted: (command: string) => string;
     commandOutcome: (command: string, outcome: TurnOutcome, output?: string) => string;

package/dist/owner-channel/notices.js

@@ -28,6 +28,9 @@ export const ownerNotices = {
         + 'The response will arrive in this channel when ready.',
     status: (role, snapshot) => `📊 ${role} status: ${snapshot.readiness}; session is ${snapshot.alive ? 'online' : 'offline'}.`,
     interrupted: (role) => `🛑 Interrupt sent to ${role}'s active turn.`,
+    /** The turn IS cancelled — say how, without implying the owner must retry. */
+    interruptForced: (role) => `🛑 Interrupt enforced: ${role}'s turn ignored the cancellation, so the session `
+        + 'was stopped and is restarting. It resumes automatically.',
     interruptFailed: (role) => `⚠️ Could not interrupt ${role}'s active turn.`,
     commandStarted: (command) => `⏳ Running ${command} — the result will follow in this channel.`,
     commandOutcome: (command, outcome, output) => {

package/dist/provenance.d.ts

@@ -0,0 +1,77 @@
+export declare const PACKAGE_NAME = "@ours.network/fleet";
+export declare const BIN_NAME = "ours-fleet";
+/** Stand-in build id for artifacts built before this module existed. */
+export declare const UNKNOWN_BUILD = "unknown";
+/** Identity of one built artifact, written into dist/ at build time. */
+export interface BuildInfo {
+    version: string;
+    /** First 12 hex of a sha256 over every other file in dist/. */
+    buildId: string;
+    /** Commit the build was cut from, when git was available. */
+    commit?: string;
+    /** Whether that working tree had uncommitted changes. */
+    dirty?: boolean;
+    builtAt?: string;
+    capabilities: string[];
+}
+/** One @ours.network/fleet package directory on this host. */
+export interface Install {
+    packageRoot: string;
+    version: string;
+    /** Absent for a pre-provenance build — its identity is unknowable. */
+    build?: BuildInfo;
+}
+export interface InstallRecord extends Install {
+    /** The PATH candidate that reaches this install, if any. */
+    bin?: string;
+    realBin?: string;
+    /** Position of `bin`'s directory in PATH; absent when off PATH. */
+    pathIndex?: number;
+    /** Whether this is the install executing right now. */
+    running: boolean;
+}
+export type SkewKind = 'version-build-conflict' | 'shadowed-runtime' | 'unknown-build-identity';
+export interface InstallSkew {
+    kind: SkewKind;
+    severity: 'error' | 'warn';
+    message: string;
+}
+/** Read the install rooted at `packageRoot`, or undefined if that is not one. */
+export declare function readInstall(packageRoot: string): Install | undefined;
+/** Walk up from `from` to the @ours.network/fleet package directory containing it. */
+export declare function findPackageRoot(from: string): string | undefined;
+/**
+ * Every install reachable from PATH, plus the one executing right now.
+ * PATH order is preserved; an install reached by several PATH entries is listed
+ * once, at its earliest position.
+ */
+export declare function discoverInstalls(opts?: {
+    path?: string;
+    argv1?: string;
+    binName?: string;
+    platform?: NodeJS.Platform;
+}): InstallRecord[];
+/**
+ * sha256 over an install's dist/ tree, first 12 hex — the same bytes and order
+ * `scripts/build-info.mjs` hashes, so a stamped install's digest equals its
+ * buildId. This is what tells two PRE-provenance installs apart: they both
+ * report `unknown`, but they are not the same artifact, and the host that
+ * motivated this module had exactly that pair.
+ */
+export declare function contentDigest(packageRoot: string): string | undefined;
+/** `0.17.0+9f1c2a3b4d5e`, or `…+unknown` for a pre-provenance build. */
+export declare const buildLabel: (install: Pick<Install, "version" | "build">) => string;
+/** What an install says it can do — never guessed from its version. */
+export declare const capabilitySummary: (install: Install) => string;
+/**
+ * Conflicts an operator must know about. `version-build-conflict` is the one
+ * that bit this host: same semver, different artifact, silently different rules.
+ *
+ * `digest` is only consulted inside a version group of two or more, so the
+ * common single-install case never hashes anything.
+ */
+export declare function analyzeInstalls(records: InstallRecord[], digest?: (packageRoot: string) => string | undefined): InstallSkew[];
+/** Identity of the build executing right now. */
+export declare function buildInfo(): BuildInfo;
+/** `ours-fleet 0.17.0+9f1c2a3b4d5e` — one line, safe for any operator output. */
+export declare const runningLabel: () => string;