@ours.network/fleet 0.10.3 → 0.11.0

package/dist/cli.js

@@ -6,13 +6,19 @@ import { join as joinPath } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
-import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
-import { loadConfig } from './config.js';
+import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir, watchdogsRoot } from './paths.js';
+import { loadConfig, ROLE_NAME_RE } from './config.js';
+import { formatDuration } from './duration.js';
 import { resolvedPlan } from './resolved-plan.js';
 import { Tmux, tmuxArgs } from './tmux.js';
 import { pickBackend } from './supervisor/index.js';
 import { up, down, restartRoles, rmRole } from './ops.js';
 import { readRestartLedger, runSupervised, runTemp } from './runner.js';
+import { executeWatchdogRun, runWatchdogAgent } from './watchdog/run.js';
+import { readSchedulerState, resetSchedulerState, runScheduler } from './watchdog/scheduler.js';
+import { partitionRestartNames } from './watchdog/config.js';
+import { WatchdogServiceManager } from './watchdog/service.js';
+import { acquireRunLock, latestReport, listRuns, readReport, releaseRunLock, reportsDir, } from './watchdog/store.js';
 import { lastProvenance, spawnDryRun, spawnPermanent, spawnTemp, } from './spawn.js';
 import { stringify } from 'yaml';
 import { resolvedRolePlan } from './resolved-plan.js';
@@ -22,6 +28,9 @@ import { allWarnings, analyzeFleetPermissions, formatNative } from './permission
 import { AI_DOCS } from './docs.js';
 import { controlRequest, controlSocketPath, followControl, livenessNote, } from './session/control.js';
 import { SessionControlError } from './session/types.js';
+import { startWebConsole } from './web/runtime.js';
+import { requestWebControl } from './web/control.js';
+import { WebServiceManager } from './web/service.js';
 import './harness/claude-code.js'; // registers the claude-code adapter
 import './harness/codex.js'; // registers the codex adapter
 // sudo/su shells lack XDG_RUNTIME_DIR, breaking every systemctl/journalctl
@@ -37,6 +46,7 @@ const deps = () => ({
     backend: pickBackend(),
     binPath,
     log: l => console.log(l),
+    watchdogService: new WatchdogServiceManager(),
 });
 const die = (e) => { console.error(String(e instanceof Error ? e.message : e)); process.exit(1); };
 /** Exec a child with our stdio (logs/attach). */
@@ -47,6 +57,7 @@ const passthrough = (cmd, args) => new Promise(resolve => {
 const program = new Command()
     .name('ours-fleet')
     .description('Fleet of persistent, identity-bound AI agents — selectable harness and tmux/ACP sessions.')
+    .enablePositionalOptions()
     .version(VERSION);
 const cOpt = (cmd) => cmd.option('-c, --configuration <file>', 'config file (default: ~/fleet.yaml + ~/fleet.d/)');
 const collect = (value, previous) => [...previous, value];
@@ -175,6 +186,19 @@ cOpt(program.command('config').description('validate + print the merged plan (no
             for (const w of perms ? allWarnings(perms) : [])
                 console.log(`    warning:     ${w}`);
         }
+        if (cfg.watchdogs.length) {
+            console.log('watchdogs:');
+            for (const w of cfg.watchdogs) {
+                console.log(`● ${w.name}${w.enabled ? '' : '  (disabled)'}`
+                    + `${readSchedulerState(w.name).heldDown ? '  (held down)' : ''}`);
+                console.log(`  every ${formatDuration(w.intervalMs)} -> ${w.coordinator}`);
+                console.log(`  harness:  ${w.harness} (${w.session})${w.model ? `, model: ${w.model}` : ''}`);
+                console.log(`  identity: ${w.identity}`);
+                console.log(`  watch:    ${w.watch.join(', ')}`);
+                if (w.promptFile)
+                    console.log(`  focus:    ${w.promptFile}`);
+            }
+        }
     }
     catch (e) {
         die(e);
@@ -201,7 +225,21 @@ cOpt(program.command('down [names...]').description('stop roles'))
 cOpt(program.command('restart [names...]').description('re-sync config + bounce, RESUMING context'))
     .action(async (names, opts) => {
     try {
-        await restartRoles(loadConfig(opts.configuration), names, deps(), 'keep', opts.configuration);
+        const cfg = loadConfig(opts.configuration);
+        // Watchdog names can't collide with role names (config validation
+        // guarantees dispatch is unambiguous), so a name matching a configured
+        // watchdog is always a release, never a role restart. Release each
+        // named watchdog directly instead of handing it to restartRoles, which
+        // only knows about roles and would reject it as unknown (3.2 release path).
+        const { watchdogNames, roleNames } = partitionRestartNames(cfg, names);
+        for (const wn of watchdogNames) {
+            resetSchedulerState(wn);
+            console.log(`released watchdog '${wn}' — scheduler resumes on its next poll`);
+        }
+        // Bare `restart` (no names) restarts every role — that meaning must
+        // survive even though filtering an empty array also yields [].
+        if (names.length === 0 || roleNames.length > 0)
+            await restartRoles(cfg, roleNames, deps(), 'keep', opts.configuration);
     }
     catch (e) {
         die(e);
@@ -394,6 +432,144 @@ program.command('status <name>').description('unit/agent state')
         }
     }
 });
+/**
+ * A watchdog is addressable if it's still configured, or its store dir survives
+ * config removal. The name-shape check runs BEFORE any filesystem lookup
+ * (finding #1): a hostile `name` (path separators, '..', etc.) must never
+ * reach `join(watchdogsRoot(), name)` — treated as simply unknown, same as
+ * store.ts's own `watchdogDir` choke-point guard (defense in depth).
+ */
+function watchdogKnown(name, configPath) {
+    try {
+        if (loadConfig(configPath).watchdogs.some(w => w.name === name))
+            return true;
+    }
+    catch { /* config missing/broken: fall through to the store check */ }
+    return ROLE_NAME_RE.test(name) && existsSync(joinPath(watchdogsRoot(), name));
+}
+function renderHeldDownLine(state) {
+    if (!state.heldDown)
+        return undefined;
+    return `HELD DOWN since ${state.heldSince ?? 'unknown'} after ${state.consecutiveFailures} `
+        + `consecutive failures: ${state.lastError ?? 'unknown error'}`;
+}
+/** Full human rendering of one report: header, held-down warning, counts, then non-healthy roles + evidence. */
+function renderReport(report, heldState) {
+    const lines = [`● ${report.watchdog} — run ${report.run_id} (${report.status})`];
+    const held = renderHeldDownLine(heldState);
+    if (held)
+        lines.push(held);
+    const s = report.summary;
+    lines.push(`  checked=${s.checked} healthy=${s.healthy} idle=${s.idle} anomalies=${s.anomalies}`);
+    if (report.error)
+        lines.push(`  error: ${report.error}`);
+    for (const role of report.roles) {
+        if (role.status === 'healthy')
+            continue;
+        lines.push(`  ${role.role}  ${role.status}  ${role.reason ?? ''}`.trimEnd());
+        for (const ev of role.evidence ?? [])
+            lines.push(`    - [${ev.source}] ${ev.detail} (${ev.observed_at})`);
+        if (role.alerted) {
+            const alert = report.alerts.find(a => a.role === role.role);
+            lines.push(`    alerted -> ${alert?.coordinator ?? '?'}`);
+        }
+    }
+    const tail = report.tail;
+    if (report.status === 'error' && tail) {
+        lines.push('  --- output tail ---');
+        for (const l of tail.split('\n'))
+            lines.push(`  ${l}`);
+    }
+    return lines.join('\n');
+}
+function renderRunDuration(startedAt, finishedAt) {
+    const started = Date.parse(startedAt);
+    const finished = Date.parse(finishedAt);
+    return Number.isFinite(started) && Number.isFinite(finished)
+        ? formatDuration(Math.max(0, finished - started)) : '-';
+}
+/** `--list` table: run-id, started, duration, status, checked/healthy/idle/anomalies, [error]. */
+function renderRunList(entries) {
+    const header = ['run-id'.padEnd(18), 'started'.padEnd(22), 'duration'.padEnd(8),
+        'status'.padEnd(10), 'checked/healthy/idle/anomalies', 'error'].join('  ');
+    const rows = entries.map(e => {
+        const s = e.summary;
+        const cols = [
+            e.runId.padEnd(18), (e.startedAt || '-').padEnd(22),
+            renderRunDuration(e.startedAt, e.finishedAt).padEnd(8), e.status.padEnd(10),
+            `${s.checked}/${s.healthy}/${s.idle}/${s.anomalies}`.padEnd(31),
+        ];
+        if (e.error)
+            cols.push(e.error);
+        return cols.join('  ').trimEnd();
+    });
+    return [header, ...rows].join('\n');
+}
+cOpt(program.command('watchdog-run <name>')
+    .description('run one watchdog check now, foreground, same storage as the scheduler'))
+    .action(async (name, opts) => {
+    try {
+        const cfg = loadConfig(opts.configuration);
+        const wd = cfg.watchdogs.find(w => w.name === name);
+        if (!wd)
+            throw new Error(`unknown watchdog '${name}'`);
+        if (!acquireRunLock(name))
+            throw new Error(`watchdog '${name}' is already running (run lock held)`);
+        try {
+            const { report, storedPath } = await executeWatchdogRun(wd, {
+                binPath, log: l => console.log(l), cfg,
+            });
+            console.log(`stored: ${storedPath}`);
+            console.log(renderReport(report, readSchedulerState(name)));
+        }
+        finally {
+            releaseRunLock(name);
+        }
+    }
+    catch (e) {
+        die(e);
+    }
+});
+cOpt(program.command('watchdog-report <name> [runId]')
+    .description('show a watchdog run report: latest by default, a specific run by id, --list, or --json'))
+    .option('--list', 'list runs instead of showing one')
+    .option('--json', 'print the stored report file bytes unmodified')
+    .action((name, runId, opts) => {
+    try {
+        if (!watchdogKnown(name, opts.configuration))
+            throw new Error(`unknown watchdog '${name}'`);
+        if (opts.list) {
+            // --list has no single stored file to echo byte-for-byte, so --json here can't
+            // mean "raw stored bytes" the way it does for a single report. Contract: emit
+            // machine-readable run metadata instead (JSON.stringify of listRuns()'s
+            // RunListEntry[], wrapped in { runs }) — the single-report --json path below is
+            // unaffected and still prints the exact stored bytes.
+            if (opts.json) {
+                console.log(JSON.stringify({ runs: listRuns(name) }, null, 2));
+                return;
+            }
+            const held = renderHeldDownLine(readSchedulerState(name));
+            if (held)
+                console.log(held);
+            console.log(renderRunList(listRuns(name)));
+            return;
+        }
+        const report = runId !== undefined ? readReport(name, runId) : latestReport(name);
+        if (!report) {
+            throw new Error(runId !== undefined
+                ? `watchdog '${name}': no such run '${runId}'`
+                : `watchdog '${name}' has no reports`);
+        }
+        if (opts.json) {
+            console.log(readFileSync(joinPath(reportsDir(name), `${runId ?? report.run_id}.json`), 'utf8'));
+            return;
+        }
+        console.log(renderReport(report, readSchedulerState(name)));
+    }
+    catch (e) {
+        die(e);
+    }
+});
 cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fleet.d file if spawned)'))
     .action(async (name, opts) => {
     try {
@@ -508,6 +684,143 @@ program.command('init').description('one-time host setup (units, dirs, linger)')
         console.log(m);
     console.log('\nNext: copy examples/fleet.yaml to ~/fleet.yaml, edit, then: ours-fleet up');
 });
+const webCommand = cOpt(program.command('web').description('start or open the secure localhost fleet web console'))
+    .enablePositionalOptions()
+    .option('--port <port>', 'loopback service port (default: 49271)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+})
+    .option('--no-open', 'do not open a browser automatically')
+    .action(async (opts) => {
+    try {
+        const manager = new WebServiceManager();
+        for (const line of await manager.install(binPath, opts.port ?? 49_271, opts.configuration))
+            process.stdout.write(line + '\n');
+        await manager.start();
+        if (opts.open !== false) {
+            await requestWebControlWhenReady('open');
+            process.stdout.write('Trusted-browser pairing opened locally.\n');
+        }
+        else
+            process.stdout.write('Web service started; run `ours-fleet web open` to pair a browser.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+const webPort = (command) => cOpt(command)
+    .option('--port <port>', 'loopback service port (default: 49271)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+});
+const webServe = cOpt(webCommand.command('serve').description('run the web console in the foreground'))
+    .option('--port <port>', 'loopback port (default: 49271; 0 chooses a free port)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+});
+webServe
+    .option('--no-open', 'do not open a browser automatically')
+    .action(async (opts) => {
+    try {
+        const consoleServer = await startWebConsole({
+            configPath: opts.configuration, port: opts.port,
+            open: opts.open !== false, binPath,
+            log: line => process.stderr.write(line + '\n'),
+        });
+        process.stdout.write(`ours-fleet web listening on ${consoleServer.address}\n`);
+        process.stdout.write(opts.open !== false
+            ? 'Trusted-browser pairing opened locally.\n'
+            : 'Run `ours-fleet web open` on this computer to pair a browser.\n');
+        const shutdown = async () => { await consoleServer.close(); process.exit(0); };
+        process.once('SIGINT', () => { void shutdown(); });
+        process.once('SIGTERM', () => { void shutdown(); });
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webPort(webCommand.command('install').description('install or update the owner web service'))
+    .action(async (opts) => {
+    try {
+        for (const line of await new WebServiceManager().install(binPath, opts.port ?? 49_271, opts.configuration))
+            process.stdout.write(line + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+for (const [name, description] of [
+    ['start', 'start the installed owner web service'],
+    ['stop', 'stop the owner web service'],
+    ['restart', 'restart the owner web service'],
+])
+    webCommand.command(name).description(description).action(async () => {
+        try {
+            await new WebServiceManager()[name]();
+            process.stdout.write(`Web service ${{ start: 'started', stop: 'stopped', restart: 'restarted' }[name]}.\n`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+webCommand.command('status').description('show native web service status')
+    .action(async () => {
+    try {
+        process.stdout.write(await new WebServiceManager().status() + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('uninstall').description('stop and uninstall the owner web service')
+    .action(async () => {
+    try {
+        process.stdout.write(await new WebServiceManager().uninstall() + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('open').description('securely open or re-pair a browser with the running console')
+    .action(async () => {
+    try {
+        await requestWebControl('open');
+        process.stdout.write('Trusted-browser pairing opened locally.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('revoke-all').description('revoke all trusted browsers and active web sessions')
+    .action(async () => {
+    try {
+        await requestWebControl('revoke-all');
+        process.stdout.write('Revoked all trusted browsers and active web sessions.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+async function requestWebControlWhenReady(command) {
+    let last;
+    for (let attempt = 0; attempt < 40; attempt++) {
+        try {
+            await requestWebControl(command, undefined, 500);
+            return;
+        }
+        catch (error) {
+            last = error;
+            await new Promise(resolve => setTimeout(resolve, 125));
+        }
+    }
+    throw last;
+}
 program.command('_run <name>', { hidden: true }).description('internal: supervisor entrypoint')
     .option('-c, --configuration <file>')
     .action(async (name, opts) => {
@@ -529,4 +842,29 @@ program.command('_run-temp <name>', { hidden: true }).description('internal: tem
         die(e);
     }
 });
+program.command('_run-watchdog <name>', { hidden: true })
+    .description('internal: one watchdog agent run (no cleanup — parent harvests)')
+    .action(async (name) => {
+    try {
+        await runWatchdogAgent(name);
+    }
+    catch (e) {
+        die(e);
+    }
+});
+cOpt(program.command('_run-watchdogs', { hidden: true }))
+    .description('internal: the watchdog scheduler process')
+    .action(async (opts) => {
+    try {
+        let stop = false;
+        process.on('SIGTERM', () => { stop = true; });
+        await runScheduler(opts.configuration, {
+            now: () => new Date(), sleep: ms => new Promise(r => setTimeout(r, ms)),
+            log: l => console.log(l), binPath, shouldStop: () => stop,
+        });
+    }
+    catch (e) {
+        die(e);
+    }
+});
 program.parseAsync(process.argv);

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { type ConfigDiagnostic, type YamlMode } from './config-yaml.js';
 import type { IsolationConfig, WrapContext } from './isolation/types.js';
+import type { ResolvedWatchdog } from './watchdog/config.js';
 export interface OverseeEntry {
     role: string;
     interval: string;
@@ -73,7 +74,8 @@ export interface RoleConfig {
     persona?: string;
     bio?: string;
     briefing_file?: string;
-    model?: string;
+    /** Explicit null means use the selected harness's own default, bypassing fleet defaults. */
+    model?: string | null;
     model_chain?: string[];
     max_tokens?: number;
     autocompact_pct?: number;
@@ -85,7 +87,7 @@ export interface RoleConfig {
     worklog?: WorklogPolicy;
     auth_proxy?: Partial<AuthProxyConfig>;
 }
-export interface ResolvedRole extends RoleConfig {
+export interface ResolvedRole extends Omit<RoleConfig, 'model'> {
     name: string;
     harness: string;
     session: SessionBackendId;
@@ -98,6 +100,7 @@ export interface ResolvedRole extends RoleConfig {
      */
     permissionsDeclared: boolean;
     identity: string;
+    model?: string;
     sourceFile: string;
     monitor: MonitorConfig;
     worklog?: WorklogPolicy;
@@ -112,9 +115,12 @@ export interface FleetConfig {
     startStaggerMs: number;
     /** Warning-first non-plain YAML migration diagnostics, in source order. */
     diagnostics: ConfigDiagnostic[];
+    watchdogs: ResolvedWatchdog[];
 }
 export declare class ConfigError extends Error {
 }
+/** Resolve a model without leaking a default that belongs to another harness. */
+export declare function resolveRoleModel(model: string | null | undefined, harness: string | undefined, defaults: Record<string, unknown>): string | undefined;
 /**
  * The runtime facts the isolation resolver needs for a role. Single-sourced so
  * config validation, doctor, and the runner all judge the SAME mount set — a
@@ -122,6 +128,7 @@ export declare class ConfigError extends Error {
  * a check at all.
  */
 export declare function isolationContextFor(role: ResolvedRole): WrapContext;
+export declare const ROLE_NAME_RE: RegExp;
 /** Load ~/fleet.yaml (or an explicit path) merged with ~/fleet.d/*.yaml drop-ins. */
 export declare function loadConfig(configPath?: string, options?: {
     yamlMode?: YamlMode;

package/dist/config.js

@@ -4,6 +4,7 @@ import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
 import { parseFleetDocument, } from './config-yaml.js';
 import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
 import { getAdapter } from './harness/registry.js';
+import { resolveWatchdogs } from './watchdog/config.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',
@@ -60,6 +61,16 @@ export function validateMonitorConfig(raw) {
 }
 export class ConfigError extends Error {
 }
+/** Resolve a model without leaking a default that belongs to another harness. */
+export function resolveRoleModel(model, harness, defaults) {
+    if (model === null)
+        return undefined;
+    if (typeof model === 'string' && model.trim())
+        return model.trim();
+    const defaultHarness = defaults.harness ?? 'claude-code';
+    const effectiveHarness = harness ?? defaultHarness;
+    return effectiveHarness === defaultHarness ? defaults.model : undefined;
+}
 /**
  * The runtime facts the isolation resolver needs for a role. Single-sourced so
  * config validation, doctor, and the runner all judge the SAME mount set — a
@@ -91,7 +102,7 @@ export function isolationContextFor(role) {
         harnessSharedPaths: split?.shared,
     };
 }
-const NAME_RE = /^[A-Za-z0-9_-]+$/;
+export const ROLE_NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
     'harness', 'session', 'session_options', 'permissions', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
     'briefing_file', 'model', 'model_chain', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
@@ -143,7 +154,7 @@ export function loadConfig(configPath, options = {}) {
     const roles = [];
     for (const { file, doc } of docs) {
         for (const [name, raw] of Object.entries((doc.roles ?? {}))) {
-            if (!NAME_RE.test(name))
+            if (!ROLE_NAME_RE.test(name))
                 throw new ConfigError(`${file}: invalid role name '${name}' (allowed: [A-Za-z0-9_-])`);
             const prev = seen.get(name);
             if (prev)
@@ -177,9 +188,13 @@ export function loadConfig(configPath, options = {}) {
             const monitor = resolveMonitorConfig(defaults.monitor, r.monitor, { base, file, name });
             const worklog = resolveWorklogPolicy(defaults.worklog, r.worklog, file, name);
             const authProxy = resolveAuthProxy(defaults.auth_proxy, r.auth_proxy, file, name);
-            const model = r.model ?? defaults.model;
-            const modelChain = resolveModelChain(model, r.model_chain ?? defaults.model_chain, file, name);
             const harness = r.harness ?? defaults.harness ?? 'claude-code';
+            const defaultHarness = defaults.harness ?? 'claude-code';
+            const inheritsModelDefaults = harness === defaultHarness && r.model !== null;
+            const model = resolveRoleModel(r.model, r.harness, defaults);
+            const modelChain = resolveModelChain(model, r.model_chain ?? (inheritsModelDefaults
+                ? defaults.model_chain
+                : undefined), file, name);
             if (authProxy && harness !== 'claude-code')
                 throw new ConfigError(`${file}: role '${name}' auth_proxy is supported only by claude-code`);
             const env = {
@@ -220,7 +235,8 @@ export function loadConfig(configPath, options = {}) {
             }
         }
     }
-    return { roles, vars, defaults, files, startStaggerMs, diagnostics };
+    const watchdogs = resolveWatchdogs(baseDoc, base, roles, vars, defaults);
+    return { roles, vars, defaults, files, startStaggerMs, diagnostics, watchdogs };
 }
 export function resolveModelChain(model, chain, file = 'config', name = 'role') {
     if (chain === undefined)

package/dist/creation.d.ts

@@ -24,7 +24,10 @@ export interface CreationDeps {
     identityRegistry?: IdentityRegistry;
     /** Verify/create the ours identity. Injectable so tests need no daemon. */
     identityProvisioner?: IdentityProvisioner;
+    /** Descriptive progress around the existing transaction; never a second workflow. */
+    onStage?(stage: CreationCoreStage, evidence?: Record<string, string | boolean>): void;
 }
+export type CreationCoreStage = 'reserving' | 'checking_identity' | 'writing_role' | 'registering_supervisor' | 'starting_temp';
 /**
  * The contract the ours daemon must satisfy for identity names to be reserved
  * atomically across ALL of its clients, not just across fleet processes.
@@ -101,12 +104,15 @@ export interface IdentityProvisioner {
 }
 export type IdentityGuarantee = {
     state: 'verified';
+    evidence: 'verified';
     detail: string;
 } | {
     state: 'created';
+    evidence: 'missing';
     detail: string;
 } | {
     state: 'unverified';
+    evidence: 'missing' | 'unknown';
     detail: string;
 };
 /**
@@ -148,6 +154,9 @@ export interface CreationProvenance {
     createdAt: string;
     lifetime: 'permanent' | 'temporary';
     role: string;
+    /** Additive correlation for non-CLI creation surfaces; never contains request data. */
+    surface?: 'cli' | 'web';
+    creationActionId?: string;
     /** Effective settings, each tagged with where its value came from. */
     settings: Record<string, ProvenanceEntry>;
 }
@@ -170,6 +179,8 @@ export declare function buildProvenance(o: {
     fleetVersion: string;
     now?: Date;
     settings: Record<string, ProvenanceEntry>;
+    surface?: 'cli' | 'web';
+    creationActionId?: string;
 }): CreationProvenance;
 /** Write the provenance record atomically, before the role is started. */
 export declare function writeProvenance(stateDir: string, p: CreationProvenance): void;

package/dist/creation.js

@@ -150,7 +150,10 @@ function readdirSyncSafe(dir) {
  */
 export async function ensureIdentity(name, profile, provisioner, log = () => { }) {
     if (!provisioner)
-        return { state: 'unverified', detail: 'no identity provisioner is configured' };
+        return {
+            state: 'unverified', evidence: 'unknown',
+            detail: 'no identity provisioner is configured',
+        };
     let present;
     try {
         present = await provisioner.exists(name);
@@ -160,18 +163,30 @@ export async function ensureIdentity(name, profile, provisioner, log = () => { }
         log(`identity '${name}': could not be verified (${e.message})`);
     }
     if (present === true)
-        return { state: 'verified', detail: 'the ours daemon reports it exists' };
+        return {
+            state: 'verified', evidence: 'verified',
+            detail: 'the ours daemon reports it exists',
+        };
     if (present === 'unknown')
-        return { state: 'unverified', detail: 'the ours daemon could not be asked' };
+        return {
+            state: 'unverified', evidence: 'unknown',
+            detail: 'the ours daemon could not be asked',
+        };
     if (!provisioner.create) {
         // Loud, and named. The briefing will tell the agent to mint it — which is
         // what actually happens today — but nobody is told it was "predefined".
         log(`identity '${name}' does not exist and this host cannot create one automatically — `
             + `the role will be told to mint it on first boot. Create it in advance to avoid that.`);
-        return { state: 'unverified', detail: 'it does not exist and cannot be created here' };
+        return {
+            state: 'unverified', evidence: 'missing',
+            detail: 'it does not exist and cannot be created here',
+        };
     }
     await provisioner.create(name, profile);
-    return { state: 'created', detail: 'created during spawn, with its bio and persona published' };
+    return {
+        state: 'created', evidence: 'missing',
+        detail: 'created during spawn, with its bio and persona published',
+    };
 }
 /**
  * Ask the running ours daemon whether an identity exists, over the same
@@ -230,6 +245,8 @@ export function buildProvenance(o) {
         createdAt: (o.now ?? new Date()).toISOString(),
         lifetime: o.lifetime,
         role: o.role,
+        surface: o.surface ?? 'cli',
+        creationActionId: o.creationActionId,
         settings: o.settings,
     };
 }