@ours.network/fleet 0.17.0 → 0.17.2

package/README.md

@@ -302,9 +302,27 @@ ours-fleet loops reload <Role>
 ours-fleet loops run-now|disable|enable <Role> <Loop>
 ours-fleet rm <Name>
 ours-fleet doctor [--harness H]
+ours-fleet version [--json]         build identity, capabilities, installs on PATH
 ours-fleet init
 ```
 
+### Which build am I running?
+
+`--version` prints a semver, and a semver does not identify an artifact: version
+bumps land in their own release commit, so a build cut between two releases
+carries the previous version while already containing new behaviour. Two installs
+on one host once both reported `0.16.0` while disagreeing about whether
+`monitor.interrupt: after_tool` was valid.
+
+Every build therefore stamps `dist/build-info.json` with a content-derived build
+id, its commit, and the capability tokens the shipped code declares.
+`ours-fleet version` prints that identity plus every `ours-fleet` it can see on
+`PATH`; `ours-fleet doctor` fails when two of them share a semver but are
+different builds, or when the executable on `PATH` is a different artifact from
+the one running. Two prefixes holding identical content are not a conflict.
+Installs predating the stamp are compared by hashing their `dist/`, so two of
+those are still told apart.
+
 A permanent role brought up via `-c custom.yaml` remembers that file (`.config-path`
 in its state dir) across supervisor-triggered restarts — systemd/launchd re-invoke the
 agent process with no arguments, so without this the role would silently fall back to
@@ -437,6 +455,20 @@ schedule or selector changes reset that loop to its configured initial delay.
 `run-now` still obeys idle-only admission and returns exit 3 when busy; an
 unavailable or uncertain control plane returns exit 2 and is never retried.
 
+A failed state write — a full disk is the case seen in practice — never stops the
+manager. The failure is held in memory as `health: failed`, `anomaly:
+persist_failed`; the occurrence that could not be checkpointed is recorded as
+`skipped_unpersisted` rather than started, since a run that is not on disk is one
+a restart would submit twice; and the manager keeps a bounded retry armed (1s
+doubling to 60s) so it resumes on its own once writes land. Because that health
+flip is itself unwritable, readers do not trust a stored file that has stopped
+advancing: `status`, `loops status`, and `doctor` report `stale` — never the
+recorded health — once the checkpoint of a role that still has a loop to run is
+more than 5 minutes old. A role whose loops are all disabled stops checkpointing
+by design and is never called stale. `status` asks the live control socket
+whenever it is there, including when the first checkpoint never got written, and
+`doctor` fails a running role that has no stored loop state at all.
+
 A scheduled turn has typed internal provenance and no owner authority. It cannot
 cancel owner work and its ordinary completion is local only. Material proactive
 owner reporting remains possible solely through an already-open authenticated
@@ -501,8 +533,12 @@ mode can cross.
 
 ACP exposes agent-specific session mode IDs and `session/set_mode`, but no
 portable permission-policy capability. Fleet uses that primitive where an
-adapter has a corresponding mode and otherwise translates at the adapter;
-live session metadata reports both normalized and harness-native modes.
+adapter has a corresponding mode and otherwise translates at the adapter. The
+bundled Codex ACP adapter couples approval and sandboxing in its advertised
+mode IDs, so fleet preserves the selected sandbox preset and enforces approval
+independently on the app-server turn request. Thus `allow` + `workspace` is
+actually `never` + `workspace-write`, never `danger-full-access`. Live session
+metadata reports the normalized policy and the ACP sandbox-preset ID.
 
 ### Isolation at creation time
 

package/dist/application/role-removal-service.js

@@ -74,7 +74,7 @@ export class RoleRemovalService {
             cpSync(sourceState, join(recoveryPath, 'state'), { recursive: true });
         if (role?.sourceFile.includes('/fleet.d/') && existsSync(role.sourceFile))
             cpSync(role.sourceFile, join(recoveryPath, basename(role.sourceFile)));
-        if (role)
+        if (role || preview.lifetime === 'temporary')
             await rmRole(cfg, preview.role, this.options.ops);
         else {
             await this.options.ops.backend.uninstall(preview.role);

package/dist/application/session-control.d.ts

@@ -13,6 +13,16 @@ export interface ConversationPageView {
 export interface ConversationFollowHandle {
     close(): void;
 }
+/**
+ * An interrupt that reached the session. `state` says whether the turn stopped
+ * cooperatively or through bounded forced recovery — both are accepted, so no
+ * consumer may render `forced` as a failed interrupt.
+ */
+export interface InterruptReceipt {
+    accepted: true;
+    state: 'settled' | 'forced';
+    reasonCode?: string;
+}
 export interface RoleSessionControl {
     describe(): Promise<SessionDescriptor>;
     snapshot(): Promise<SessionSnapshot>;
@@ -21,9 +31,7 @@ export interface RoleSessionControl {
         limit?: number;
     }): Promise<OutputPage>;
     sendText(text: string): Promise<SendReceipt>;
-    interrupt?(): Promise<{
-        accepted: true;
-    }>;
+    interrupt?(): Promise<InterruptReceipt>;
     respondPermission?(request: {
         permissionId: string;
         optionId: string;
@@ -40,8 +48,7 @@ export interface RoleSessionControl {
         actorBrowserSession: string;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
-    interruptV2?(commandId: string): Promise<{
-        accepted: true;
+    interruptV2?(commandId: string): Promise<InterruptReceipt & {
         commandId: string;
     }>;
     respondPermissionV2?(request: {
@@ -76,9 +83,7 @@ export declare class AcpRoleSessionAdapter implements RoleSessionControl {
         limit?: number;
     }): Promise<OutputPage>;
     sendText(text: string): Promise<SendReceipt>;
-    interrupt(): Promise<{
-        accepted: true;
-    }>;
+    interrupt(): Promise<InterruptReceipt>;
     conversationPage(request?: {
         after?: string;
         limit?: number;
@@ -89,8 +94,7 @@ export declare class AcpRoleSessionAdapter implements RoleSessionControl {
         actorBrowserSession: string;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
-    interruptV2(commandId: string): Promise<{
-        accepted: true;
+    interruptV2(commandId: string): Promise<InterruptReceipt & {
         commandId: string;
     }>;
     respondPermissionV2(request: {

package/dist/application/session-control.js

@@ -51,8 +51,13 @@ export class AcpRoleSessionAdapter {
         };
     }
     async interrupt() {
-        await this.call('interrupt');
-        return { accepted: true };
+        const result = await this.call('interrupt');
+        // A pre-0.17.1 role control server answers `interrupt` with no result body.
+        return {
+            accepted: true,
+            state: result?.state === 'forced' ? 'forced' : 'settled',
+            ...(typeof result?.reasonCode === 'string' ? { reasonCode: result.reasonCode } : {}),
+        };
     }
     async conversationPage(request = {}) {
         return await this.call('conversation_page', {
@@ -78,7 +83,13 @@ export class AcpRoleSessionAdapter {
         }
     }
     async interruptV2(commandId) {
-        return await this.call('interrupt_v2', { commandId });
+        const receipt = await this.call('interrupt_v2', { commandId });
+        return {
+            ...receipt,
+            accepted: true,
+            state: receipt.state === 'forced' ? 'forced' : 'settled',
+            ...(typeof receipt.reasonCode === 'string' ? { reasonCode: receipt.reasonCode } : {}),
+        };
     }
     async respondPermissionV2(request) {
         try {

package/dist/atomic-file.d.ts

@@ -11,6 +11,12 @@ export interface LockDeps {
     now?(): number;
     sleep?(ms: number): Promise<void>;
 }
+/** The syscalls a replace depends on, injectable so faults can be forced deterministically. */
+export interface WriteDeps {
+    writeSync?(fd: number, buffer: Buffer, offset: number, length: number): number;
+    fsyncSync?(fd: number): void;
+    closeSync?(fd: number): void;
+}
 /**
  * Run `fn` holding a cross-process lock. `mkdir` is atomic on every platform we
  * support, so the directory's existence IS the lock; the timestamp inside lets a
@@ -27,4 +33,4 @@ export declare function withFileLock<T>(lockPath: string, fn: () => T | Promise<
  * half-written one — and an interrupted write leaves the previous contents
  * intact.
  */
-export declare function replaceFileAtomically(path: string, contents: string, mode?: number): void;
+export declare function replaceFileAtomically(path: string, contents: string, mode?: number, deps?: WriteDeps): void;

package/dist/atomic-file.js

@@ -53,17 +53,45 @@ export async function withFileLock(lockPath, fn, deps = {}, staleMs = DEFAULT_ST
  * half-written one — and an interrupted write leaves the previous contents
  * intact.
  */
-export function replaceFileAtomically(path, contents, mode = 0o600) {
+export function replaceFileAtomically(path, contents, mode = 0o600, deps = {}) {
+    const write = deps.writeSync ?? writeSync;
+    const fsync = deps.fsyncSync ?? fsyncSync;
+    const close = deps.closeSync ?? closeSync;
     const dir = dirname(path);
     mkdirSync(dir, { recursive: true });
     const tmp = join(dir, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
     const fd = openSync(tmp, 'w', mode);
+    let closed = false;
     try {
-        writeSync(fd, contents);
-        fsyncSync(fd); // the bytes are on disk before anything points at them
+        const buffer = Buffer.from(contents, 'utf8');
+        // A single writeSync is not a guarantee: the kernel may stop short, and a
+        // truncated temp renamed over the target is silent data loss.
+        for (let written = 0; written < buffer.length;) {
+            const advanced = write(fd, buffer, written, buffer.length - written);
+            // A write that accepts nothing would spin forever; fail instead.
+            if (advanced <= 0)
+                throw new Error(`write made no progress at byte ${written} of ${buffer.length}`);
+            written += advanced;
+        }
+        fsync(fd); // the bytes are on disk before anything points at them
+        close(fd); // a temp we could not close cleanly is not publishable
+        closed = true;
     }
-    finally {
-        closeSync(fd);
+    catch (e) {
+        // Cleanup must not mask why we are here: the original failure is what the
+        // caller needs, and a temp we could not finish must never be renamed over
+        // the last good file nor left occupying space on a disk that may be full.
+        if (!closed) {
+            try {
+                close(fd);
+            }
+            catch { /* already failing */ }
+        }
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { /* best effort */ }
+        throw e;
     }
     try {
         renameSync(tmp, path);

package/dist/build-info.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.17.2",
+  "buildId": "53ac2113797a",
+  "commit": "87c798da51200d4826182e298773832bc7e1eca7",
+  "dirty": false,
+  "builtAt": "2026-08-13T21:21:28.910Z",
+  "capabilities": [
+    "monitor.interrupt.after_tool"
+  ]
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Capability tokens declared by THIS source tree.
+ *
+ * Semver cannot answer "does this artifact support X": version bumps land in a
+ * separate release commit, so every build cut between two releases carries the
+ * previous version while already containing new behaviour. A token is added in
+ * the same commit as the feature it names, travels inside the built artifact
+ * (dist/build-info.json), and is therefore the only honest answer to that
+ * question — for this process and for any other install on the host.
+ *
+ * Add a token when a change makes previously-invalid configuration valid, or
+ * otherwise changes what an operator's fleet.yaml is allowed to say. Never
+ * remove one without also rejecting the configuration it admitted.
+ */
+/** `monitor.interrupt: after_tool` — cancel at the next tool boundary (#67). */
+export declare const CAP_MONITOR_INTERRUPT_AFTER_TOOL = "monitor.interrupt.after_tool";
+export declare const CAPABILITIES: readonly ["monitor.interrupt.after_tool"];
+export type Capability = (typeof CAPABILITIES)[number];
+/** Does this build declare `token`? */
+export declare const hasCapability: (token: string) => boolean;

package/dist/capabilities.js

@@ -0,0 +1,21 @@
+/**
+ * Capability tokens declared by THIS source tree.
+ *
+ * Semver cannot answer "does this artifact support X": version bumps land in a
+ * separate release commit, so every build cut between two releases carries the
+ * previous version while already containing new behaviour. A token is added in
+ * the same commit as the feature it names, travels inside the built artifact
+ * (dist/build-info.json), and is therefore the only honest answer to that
+ * question — for this process and for any other install on the host.
+ *
+ * Add a token when a change makes previously-invalid configuration valid, or
+ * otherwise changes what an operator's fleet.yaml is allowed to say. Never
+ * remove one without also rejecting the configuration it admitted.
+ */
+/** `monitor.interrupt: after_tool` — cancel at the next tool boundary (#67). */
+export const CAP_MONITOR_INTERRUPT_AFTER_TOOL = 'monitor.interrupt.after_tool';
+export const CAPABILITIES = [
+    CAP_MONITOR_INTERRUPT_AFTER_TOOL,
+];
+/** Does this build declare `token`? */
+export const hasCapability = (token) => CAPABILITIES.includes(token);

package/dist/cli.js

@@ -6,6 +6,7 @@ import { join as joinPath, resolve as resolvePath } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
+import { analyzeInstalls, buildInfo, buildLabel, discoverInstalls, runningLabel, } from './provenance.js';
 import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir, watchdogsRoot } from './paths.js';
 import { findRole, loadConfig, ROLE_NAME_RE } from './config.js';
 import { formatDuration } from './duration.js';
@@ -22,13 +23,13 @@ import { acquireRunLock, latestReport, listRuns, readReport, releaseRunLock, rep
 import { lastProvenance, spawnDryRun, spawnPermanent, spawnTemp, } from './spawn.js';
 import { stringify } from 'yaml';
 import { resolvedRolePlan } from './resolved-plan.js';
-import { formatProvenance } from './creation.js';
+import { creationBuildNote, formatProvenance, readProvenance } from './creation.js';
 import { doctor } from './doctor.js';
 import { allWarnings, analyzeFleetPermissions, formatNative } from './permissions.js';
 import { AI_DOCS } from './docs.js';
 import { controlRequest, controlSocketPath, followControl, livenessNote, } from './session/control.js';
 import { SessionControlError } from './session/types.js';
-import { readScheduledLoops } from './loops/state.js';
+import { readScheduledLoops, storedLoopHealth } from './loops/state.js';
 import { startWebConsole } from './web/runtime.js';
 import { requestWebControl } from './web/control.js';
 import { WebServiceManager } from './web/service.js';
@@ -68,6 +69,52 @@ program.command('docs')
     .alias('man')
     .description('print the complete AI-friendly command and configuration reference')
     .action(() => { process.stdout.write(AI_DOCS); });
+// `--version` prints the semver alone, because scripts parse it. Semver cannot
+// identify an artifact — two installs on one host once reported 0.16.0 and
+// disagreed about `monitor.interrupt: after_tool` — so the full identity of the
+// executable answering, and of every other install it can see, lives here.
+program.command('version')
+    .description('build identity, capabilities, and every ours-fleet install on this host')
+    .option('--json', 'emit the machine-readable build report')
+    .action(opts => {
+    const info = buildInfo();
+    const installs = discoverInstalls();
+    const running = installs.find(i => i.running);
+    const skew = analyzeInstalls(installs);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            ...info,
+            packageRoot: running?.packageRoot,
+            executable: binPath,
+            node: process.versions.node,
+            platform: process.platform,
+            installs: installs.map(i => ({
+                packageRoot: i.packageRoot,
+                version: i.version,
+                buildId: i.build?.buildId ?? null,
+                capabilities: i.build?.capabilities ?? null,
+                bin: i.bin ?? null,
+                running: i.running,
+            })),
+            skew,
+        }, null, 2)}\n`);
+        return;
+    }
+    console.log(runningLabel());
+    if (info.commit)
+        console.log(`  commit:       ${info.commit.slice(0, 12)}${info.dirty ? ' (dirty tree)' : ''}`);
+    if (info.builtAt)
+        console.log(`  built:        ${info.builtAt}`);
+    console.log(`  executable:   ${binPath}`);
+    if (running)
+        console.log(`  package root: ${running.packageRoot}`);
+    console.log(`  node:         v${process.versions.node} on ${process.platform}`);
+    console.log(`  capabilities: ${info.capabilities.join(', ') || '(none declared)'}`);
+    for (const i of installs.filter(i => i.pathIndex !== undefined))
+        console.log(`  on PATH:      ${i.bin} -> ${buildLabel(i)}`);
+    for (const s of skew)
+        console.error(`${s.severity}: ${s.message}`);
+});
 function acpStateDir(name) {
     const permanent = agentDir(name);
     if (existsSync(controlSocketPath(permanent)))
@@ -171,6 +218,9 @@ cOpt(program.command('config').description('validate + print the merged plan (no
             process.stdout.write(`${JSON.stringify(resolvedPlan(cfg), null, 2)}\n`);
             return;
         }
+        // Which artifact resolved this plan. Two installs can share a semver and
+        // disagree about what fleet.yaml means; the plan below is only true of this one.
+        console.log(`build:  ${runningLabel()}`);
         console.log(`config: ${cfg.files.join(' + ') || '(none)'}`);
         for (const diagnostic of cfg.diagnostics)
             console.log(`warning: ${diagnostic.message}`);
@@ -256,7 +306,7 @@ cOpt(program.command('up [names...]').description('create/start every role (or j
         die(e);
     }
 });
-cOpt(program.command('down [names...]').description('stop roles'))
+cOpt(program.command('down [names...]').description('stop configured roles or exact named temporary roles'))
     .action(async (names, opts) => {
     try {
         await down(loadConfig(opts.configuration), names, deps());
@@ -439,6 +489,12 @@ program.command('logs <name>').description('show the role log').option('-f, --fo
 program.command('status <name>').description('unit/agent state')
     .action(async (name) => {
     console.log(await pickBackend().status(name));
+    // A role outlives the artifact that created it. If a different build is
+    // reporting now, its settings may resolve differently than at creation.
+    const created = readProvenance(agentDir(name));
+    const buildNote = created && creationBuildNote(created);
+    if (buildNote)
+        console.log(`build: ${buildNote}`);
     // A held-down role looks like a healthy running unit from the outside — the
     // runner is alive on purpose. Say so, with the reason and when (3.2).
     const ledger = readRestartLedger(agentDir(name));
@@ -474,13 +530,37 @@ program.command('status <name>').description('unit/agent state')
             console.log('session: acp control unavailable');
         }
     }
-    const loopState = readScheduledLoops(agentDir(name));
+    // Loop health is asked of the live manager first: when its state writes are
+    // failing it is the ONLY source that can say so — the stored file is frozen
+    // at whatever it last managed to record, which is why a role with every loop
+    // dead still reported `healthy` for 2h51m. The probe cannot be conditional on
+    // there being a stored file either: a manager whose very first checkpoint hit
+    // ENOSPC never wrote one, and it is precisely the one worth asking.
+    let loopState = readScheduledLoops(agentDir(name));
+    let loopEvidence = 'stored';
+    const loopControl = permanentLoopControlDir(name);
+    if (loopControl) {
+        try {
+            const response = await controlRequest(loopControl, { command: 'loop_status' }, 2_000);
+            if (response.ok) {
+                loopState = response.result;
+                loopEvidence = 'live';
+            }
+        }
+        catch { /* stored evidence stays honest */ }
+    }
     if (loopState) {
         const values = Object.values(loopState.loops);
         const enabled = values.filter(loop => loop.enabled && !loop.operatorDisabled).length;
         const next = values.filter(loop => loop.enabled && !loop.operatorDisabled)
             .map(loop => Date.parse(loop.nextDueAt)).filter(Number.isFinite).sort((a, b) => a - b)[0];
-        console.log(`loops: ${enabled} enabled${next ? `, next ${formatDuration(Math.max(0, next - Date.now()))}` : ''}, ${loopState.health}`);
+        const verdict = storedLoopHealth(loopState, Date.now());
+        const health = loopEvidence === 'live' ? loopState.health : verdict.health;
+        console.log(`loops: ${enabled} enabled${next ? `, next ${formatDuration(Math.max(0, next - Date.now()))}` : ''}, ${health}`
+            + (loopEvidence === 'stored' && verdict.stale
+                ? ` (no state update for ${formatDuration(verdict.ageMs)}; last recorded ${verdict.recorded})` : '')
+            + (loopState.anomaly ? ` anomaly=${loopState.anomaly}` : '')
+            + ` evidence=${loopEvidence}`);
     }
 });
 const loopsCommand = program.command('loops')
@@ -579,13 +659,20 @@ cOpt(loopsCommand.command('status [role] [loop]').description('show live or stor
                     }
                 }
                 catch { /* stored evidence remains honest; timeout is not offline */ }
-            results.push({ role: role.name, evidence, state });
+            // Stored evidence is only as current as the last write that landed.
+            const verdict = state && evidence === 'stored' ? storedLoopHealth(state, Date.now()) : undefined;
+            results.push({
+                role: role.name, evidence, state,
+                health: verdict ? verdict.health : state?.health ?? null,
+                staleMs: verdict?.stale ? verdict.ageMs : null,
+            });
         }
         if (opts.json)
             console.log(JSON.stringify({ schemaVersion: 1, roles: results }));
         else {
             const rows = results.flatMap(result => renderLoopRows(result.role, result.state, loopName)
-                .map(row => `${row} evidence=${result.evidence}`));
+                .map(row => `${row} evidence=${result.evidence} health=${result.health}`
+                + (result.staleMs === null ? '' : ` stale=${formatDuration(result.staleMs)}`)));
             console.log(rows.join('\n') || '(no scheduled loop state)');
         }
     }
@@ -981,7 +1068,7 @@ cOpt(program.command('watchdog-report <name> [runId]')
         die(e);
     }
 });
-cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fleet.d file if spawned)'))
+cOpt(program.command('rm <name>').description('stop + remove a role (temporary evidence is archived)'))
     .action(async (name, opts) => {
     try {
         await rmRole(loadConfig(opts.configuration), name, deps());
@@ -992,7 +1079,7 @@ cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fl
 });
 cOpt(program.command('spawn [name]').description('spawn a new agent (permanent by default)'))
     .option('--role <name>', 'role name (alternative to the positional name)')
-    .option('--temp', 'temporary: detached supervisor, auto-cleaned, gone on reboot')
+    .option('--temp', 'temporary: independent transient supervisor, archived on retirement, gone on reboot')
     .option('--harness <id>', 'harness adapter (default: defaults.harness)')
     .option('--session <backend>', 'session backend: tmux|acp (default: defaults.session or tmux)')
     .option('--mission <text>', 'one-line mission')
@@ -1092,7 +1179,8 @@ cOpt(program.command('spawn [name]').description('spawn a new agent (permanent b
         // The same provenance that was persisted, so what the operator reads now
         // and what a reviewer reads later cannot disagree (6.6).
         if (lastProvenance) {
-            console.log(`  created by ${lastProvenance.command} v${lastProvenance.fleetVersion} `
+            console.log(`  created by ${lastProvenance.command} `
+                + `v${lastProvenance.fleetVersion}+${lastProvenance.fleetBuild} `
                 + `at ${lastProvenance.createdAt} (${lastProvenance.lifetime})`);
             for (const line of formatProvenance(lastProvenance))
                 console.log(line);

package/dist/config.d.ts

@@ -98,8 +98,15 @@ export type OwnerChannelConfigInput = Omit<Partial<OwnerChannelConfig>, 'attachm
 export declare const DEFAULT_OWNER_ATTACHMENT_MIME: readonly ["application/pdf", "application/json", "text/plain", "image/png", "image/jpeg", "image/gif", "image/webp", "audio/ogg", "audio/mpeg", "audio/wav", "audio/x-wav", "audio/mp4", "audio/webm", "application/msword", "application/vnd.ms-excel", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.presentationml.presentation"];
 /** Default wake sources when a role does not list its own (design §2). */
 export declare const DEFAULT_WAKE_SOURCES: NotifyEventType[];
-/** Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems. */
-export declare function validateMonitorConfig(raw: unknown): string[];
+/**
+ * Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems.
+ *
+ * `capabilities` defaults to what this build declares. A value is rejected in two
+ * distinct ways: unknown to every build (a typo), or known but absent from the
+ * artifact doing the validating — the second names the capability and the build,
+ * because the same fleet.yaml may well be accepted by another install on the host.
+ */
+export declare function validateMonitorConfig(raw: unknown, capabilities?: readonly string[]): string[];
 export interface RoleConfig {
     harness?: string;
     session?: SessionBackendId;

package/dist/config.js

@@ -6,6 +6,8 @@ import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from '.
 import { getAdapter } from './harness/registry.js';
 import { resolveWatchdogs } from './watchdog/config.js';
 import { resolveLoops } from './loops/config.js';
+import { CAPABILITIES, CAP_MONITOR_INTERRUPT_AFTER_TOOL } from './capabilities.js';
+import { runningLabel } from './provenance.js';
 /** The 8 content-free event types the ours daemon appends to notifications.log. */
 export const NOTIFY_EVENT_TYPES = [
     'message_received', 'file_received', 'sibling_contact_added', 'local_contact_request',
@@ -30,8 +32,15 @@ const MONITOR_MODES = ['fleet', 'native'];
 const MONITOR_DEFAULT_BATCH_MS = 2000;
 const MONITOR_DEFAULT_TURN_FAIL_THRESHOLD = 3;
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-/** Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems. */
-export function validateMonitorConfig(raw) {
+/**
+ * Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems.
+ *
+ * `capabilities` defaults to what this build declares. A value is rejected in two
+ * distinct ways: unknown to every build (a typo), or known but absent from the
+ * artifact doing the validating — the second names the capability and the build,
+ * because the same fleet.yaml may well be accepted by another install on the host.
+ */
+export function validateMonitorConfig(raw, capabilities = CAPABILITIES) {
     const problems = [];
     if (!isPlainObject(raw))
         return ['monitor: must be a mapping'];
@@ -54,6 +63,11 @@ export function validateMonitorConfig(raw) {
     if (m.interrupt !== undefined
         && typeof m.interrupt !== 'boolean' && m.interrupt !== 'after_tool')
         problems.push("monitor.interrupt: must be true, false, or 'after_tool'");
+    else if (m.interrupt === 'after_tool' && !capabilities.includes(CAP_MONITOR_INTERRUPT_AFTER_TOOL))
+        problems.push(`monitor.interrupt: 'after_tool' needs capability ${CAP_MONITOR_INTERRUPT_AFTER_TOOL}, `
+            + `which the build validating this config (${runningLabel()}) does not declare. `
+            + 'Another install on this host may accept the same file — run `ours-fleet doctor` '
+            + 'to see which artifact serves which path.');
     if (m.turn_fail_threshold !== undefined
         && (typeof m.turn_fail_threshold !== 'number' || !Number.isInteger(m.turn_fail_threshold)
             || m.turn_fail_threshold < 1))

package/dist/creation.d.ts

@@ -151,6 +151,12 @@ export interface CreationProvenance {
     /** The command that created the role, without its arguments. */
     command: string;
     fleetVersion: string;
+    /**
+     * Build id of the artifact that created the role. Two installs can report the
+     * same fleetVersion and resolve the same fleet.yaml differently, so the semver
+     * alone does not identify what actually ran. `unknown` for a pre-provenance build.
+     */
+    fleetBuild: string;
     createdAt: string;
     lifetime: 'permanent' | 'temporary';
     role: string;
@@ -187,6 +193,16 @@ export declare function buildProvenance(o: {
 }): CreationProvenance;
 /** Write the provenance record atomically, before the role is started. */
 export declare function writeProvenance(stateDir: string, p: CreationProvenance): void;
+/** Read the provenance a role was created with, if it has one. */
+export declare function readProvenance(stateDir: string): CreationProvenance | undefined;
+/**
+ * One line when the artifact reporting on a role is not the one that created it.
+ *
+ * A role carries its creating build in creation.json. If a different build now
+ * manages it, the role's fleet.yaml may mean something different than it did at
+ * creation — and because both can report the same semver, nothing else says so.
+ */
+export declare function creationBuildNote(p: CreationProvenance): string | undefined;
 /** One concise line per non-built-in setting, for the post-creation summary. */
 export declare function formatProvenance(p: CreationProvenance): string[];
 /** Classify one setting: an explicit CLI value, a fleet default, or built-in. */

package/dist/creation.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { replaceFileAtomically, withFileLock } from './atomic-file.js';
 import { stateRoot } from './paths.js';
 import { resolveEndpoint } from './monitor.js';
+import { buildInfo, UNKNOWN_BUILD } from './provenance.js';
 /**
  * One creation transaction: role name and ours identity reserved together,
  * every artifact journalled, and everything undone in reverse on failure.
@@ -242,6 +243,7 @@ export function buildProvenance(o) {
         version: 1,
         command: 'ours-fleet spawn',
         fleetVersion: o.fleetVersion,
+        fleetBuild: buildInfo().buildId,
         createdAt: (o.now ?? new Date()).toISOString(),
         lifetime: o.lifetime,
         role: o.role,
@@ -255,6 +257,32 @@ export function buildProvenance(o) {
 export function writeProvenance(stateDir, p) {
     replaceFileAtomically(join(stateDir, CREATION_PROVENANCE_FILE), JSON.stringify(p, null, 2) + '\n', 0o600);
 }
+/** Read the provenance a role was created with, if it has one. */
+export function readProvenance(stateDir) {
+    try {
+        return JSON.parse(readFileSync(join(stateDir, CREATION_PROVENANCE_FILE), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One line when the artifact reporting on a role is not the one that created it.
+ *
+ * A role carries its creating build in creation.json. If a different build now
+ * manages it, the role's fleet.yaml may mean something different than it did at
+ * creation — and because both can report the same semver, nothing else says so.
+ */
+export function creationBuildNote(p) {
+    const now = buildInfo();
+    const created = p.fleetBuild ?? UNKNOWN_BUILD;
+    if (created === now.buildId && p.fleetVersion === now.version)
+        return undefined;
+    return `created by ours-fleet ${p.fleetVersion}+${created}, reported by ${now.version}+${now.buildId}`
+        + (created === UNKNOWN_BUILD
+            ? ' — the creating build predates build provenance and cannot be identified'
+            : ' — different artifact, so its resolved settings may differ');
+}
 /** One concise line per non-built-in setting, for the post-creation summary. */
 export function formatProvenance(p) {
     const mark = {