@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/dist/doctor.js

@@ -9,18 +9,33 @@
 // only with a live `wake_producer` at its expected tier, so 0 is never returned without runtime
 // evidence. Output is names and codes only: no identity value, key or path content is printed,
 // and an error's `code` is printed only when this repository authored it (`authoredCode`).
-import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, readdirSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join, resolve } from "node:path";
-import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, normalizeKeyReference, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
-import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
+import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, listHarnessProcesses, normalizeKeyReference, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
+import { compareVersions } from "./claude_marketplace.js";
+import { CLAUDE_PLUGIN_MCP_PACKAGE, judgeMcpEntry, judgeRegistration, nodeRegistrationFs, packageIdentity, readScopes, } from "./doctor_scopes.js";
 import { resolveKeyslotDir } from "./assets.js";
+import { cacheStateOf, measureKeyslot, progressText, scanOf, scanSourceOf, STATUS_SCAN_TIMEOUT_MS, } from "./keyslot_status.js";
 import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
 export const DOCTOR_CHECKS = Object.freeze([
     "identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime",
 ]);
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime`'s informational hint. It never changes `runtime`'s status or
+ * reason, or the exit code (pinned in `doctor_runtime_hint.test.ts`'s exit-invariance cases); where
+ * it overlaps `registration`'s existing `plugin_pin_mismatch`, that reason stays and the hint only
+ * explains it. Precedence when more than one applies: `session_predates_install`, then `no_session`
+ * (zero live records, and no pre-install process found either), then `stale_session_version`, then
+ * `no_target_first_session`, then `none`. `session_predates_install` is checked FIRST, ahead of
+ * `no_session`, because the motivating case (a harness that wrote no record at all before setup
+ * finished — the macmini claude case) has zero live records: a `no_session`-first order would
+ * mask it.
+ */
+export const RUNTIME_HINTS = Object.freeze([
+    "no_session", "stale_session_version", "session_predates_install", "no_target_first_session", "none",
+]);
 export const REPORTABLE_TOKEN = /^[A-Za-z0-9._/-]{1,64}$/;
 /**
  * A path prints only when absolute and made of the token alphabet (no spaces, quotes or control
@@ -63,6 +78,42 @@ function pinCheck(verdict, entries, cwd, fs) {
         return { ...verdict, status: "fail", reason: [...earlier, "plugin_pin_mismatch"].join(",") };
     return { ...verdict, status: verdict.status === "fail" ? "fail" : "undetermined", reason: [...earlier, "plugin_pin_ambiguous"].join(",") };
 }
+/** The IF-552-2 validity window, the same for the carry: `scannedAt ≤ now + 300` and `now − scannedAt < 86400`. */
+export const SCAN_CACHE_TTL_S = 86_400;
+export const SCAN_CACHE_FUTURE_S = 300;
+/** Cache states that are STRUCTURAL: the cache cannot serve here at all. `lock_busy` never is. */
+const STRUCTURAL_UNUSABLE = /^(untrusted:.+|state_root_relative|machine_id_unreadable)$/;
+const UNWRITABLE_WRITE = new Set(["not_written:untrusted_dir", "not_written:write_failed"]);
+const sameJson = (a, b) => {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => sameJson(a[k], b[k]));
+};
+/**
+ * IF-552-3's carry: setup's result serves instead of phase 2 only when (1) phase 1's `scan.inputs`
+ * deep-equals the carried inputs, (2) the cache could not serve STRUCTURALLY (phase 1 `unusable`
+ * with a structural reason, or `miss:absent` beside a key-step write of `not_written:untrusted_dir`
+ * or `write_failed`; `lock_busy` never qualifies: a held lock may be a tombstone being written), and
+ * (3) the carried scan is inside the validity window. Reads phase 1's `scan.cache`, never only
+ * `exit2_reasons`.
+ */
+export function carryQualifies(phase1, carried, now) {
+    const inputs = scanOf(phase1).inputs;
+    if (!inputs || typeof inputs !== "object" || !sameJson(inputs, carried.inputs))
+        return false;
+    const { state, reason } = cacheStateOf(phase1);
+    const structural = (state === "unusable" && STRUCTURAL_UNUSABLE.test(reason))
+        || (state === "miss" && reason === "absent" && UNWRITABLE_WRITE.has(carried.cacheWrite));
+    if (!structural)
+        return false;
+    return carried.scannedAt <= now + SCAN_CACHE_FUTURE_S && now - carried.scannedAt < SCAN_CACHE_TTL_S;
+}
 /** The binary's managed-settings directory per platform (`Zh()`, 2.1.283). */
 function defaultClaudeManagedDir(platform) {
     if (platform === "darwin")
@@ -273,17 +324,8 @@ async function keystoreCheck(values, env, probe) {
  *  - status.sh absent, unrunnable, timed out or unparseable → 2.
  */
 const STATUS_MODES = new Set(["sealed", "unsealed", "contradiction", "undetermined"]);
-const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|capability_(error|incapable|incapable-for-keyslot))$/;
-const STATUS_TIMEOUT_MS = 180_000;
-function runStatus(file, args, env) {
-    return new Promise((done) => {
-        execFile(file, args, { env, timeout: STATUS_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout) => {
-            const failure = error;
-            const code = !failure ? 0 : typeof failure.code === "number" && !failure.killed ? failure.code : null;
-            done({ code, stdout: String(stdout ?? "") });
-        });
-    });
-}
+/** Every exit-2 cause status.sh can emit (KSC-8 derives the list from status.sh and probe.sh). */
+export const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|scan_not_cached|scan_timed_out|capability_(error|incapable|incapable-for-keyslot))$/;
 /** The keyslot whose socket is the same file as `socket`, or null. */
 function matchKeyslot(socket, env) {
     const dir = keyslotSocketDir(env);
@@ -309,7 +351,18 @@ function matchKeyslot(socket, env) {
     }
     return null;
 }
+/** A keyslot socket's shape: `<dir>/agent-board/<slot>.sock`, the slot a name the keyslot scripts accept. */
+function keyslotShaped(socket) {
+    const match = /\/agent-board\/([^/]+)\.sock$/.exec(socket);
+    return match !== null && SLOT_RE.test(match[1]);
+}
+const isoOf = (value) => (typeof value === "string" ? value : null);
+const numOf = (value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
 async function keyStorageCheck(harness, values, fileEnv, env, options) {
+    const judged = await keyStorageJudge(harness, values, fileEnv, env, options);
+    return "check" in judged ? judged : { check: judged };
+}
+async function keyStorageJudge(harness, values, fileEnv, env, options) {
     let reference;
     try {
         reference = normalizeKeyReference(values[KEY_REFERENCE_KEY]);
@@ -333,6 +386,10 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
         const problems = externalDeclarationProblems(env, socket, uid, machineId);
         if (problems.length === 0)
             return check("pass", "external");
+        // #552: with no runtime dir the keyslot cannot be located at all. Only a socket of the keyslot's
+        // own shape says so; any other undeclared socket stays external_undeclared.
+        if (keyslotSocketDir(env) === null && keyslotShaped(socket))
+            return check("undetermined", "runtime_dir_unset");
         return check("undetermined", problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch");
     }
     let dir;
@@ -342,21 +399,54 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
     catch {
         return check("undetermined", "status_absent");
     }
-    if (!existsSync(join(dir, "status.sh")))
+    const writeStderr = options.writeStderr ?? ((line) => { process.stderr.write(`${line}\n`); });
+    const now = options.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+    let carried = false;
+    const measured = await measureKeyslot({
+        dir, harness, slot, env, scan: options.rescan ? "fresh" : "use", onFailure: "stop", run: options.statusRunner, budgets: options.statusBudgets,
+        skipScan: (phase1) => {
+            carried = options.setupScan !== undefined && carryQualifies(phase1, options.setupScan, now());
+            return carried;
+        },
+        notify: (event) => {
+            if (event.kind === "before") {
+                const { state, reason } = cacheStateOf(event.phase1);
+                const why = options.rescan ? "rescan requested" : `${state}${reason ? `:${reason}` : ""}` || "no cache";
+                writeStderr(`doctor: key_storage: scanning for plaintext copies of the key (${why}); this can take several minutes on a large home`);
+            }
+            else if (event.kind === "progress") {
+                writeStderr(`doctor: key_storage: ${progressText(event.folders)}`);
+            }
+        },
+    });
+    if (measured.absent)
         return check("undetermined", "status_absent");
-    const run = await runStatus(join(dir, "status.sh"), ["--harness", harness, "--slot", slot, "--json"], env);
-    if (run.code === null)
+    const scanPhase = measured.phases.find((phase) => phase.mode !== "only");
+    const phase1 = measured.phases.find((phase) => phase.mode === "only");
+    // A phase 1 that did not finish is status_did_not_complete; a SCAN that did not is scan_timed_out.
+    if (phase1 && phase1.code === null)
         return check("undetermined", "status_did_not_complete");
-    let report;
-    try {
-        const parsed = JSON.parse(run.stdout);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            throw new Error("not an object");
-        report = parsed;
+    // Only the helper's own budget is a timeout. Any other end of the scan without a report (SIGKILL:
+    // code null; TERM/INT, which status.sh traps: 143/130 with no JSON) is undetermined
+    // status_unreadable, the same for every signal: doctor could not finish checking, and AC-7 keeps
+    // doctor's key_storage reasons (#552 review r2). Setup, which must not enroll, refuses instead.
+    const budgetS = Math.round((options.statusBudgets?.scanMs ?? STATUS_SCAN_TIMEOUT_MS) / 1000);
+    // The helper's own scan budget ran out: scan_timed_out at once. Phase 1's report is never judged in
+    // its place (#552 review r2, gemini): it answers a different question (the cache), and judging it
+    // turned a timeout into whatever phase 1 said.
+    if (scanPhase !== undefined && scanPhase.timedOut) {
+        return {
+            check: check("undetermined", "scan_timed_out"),
+            scan: { source: "none", scanned_at: null, age_s: null, duration_s: null, cache_state: null, gave_up: { after_s: budgetS, folders: measured.folders } },
+        };
     }
-    catch {
+    if (scanPhase !== undefined && scanPhase.code === null)
+        return check("undetermined", "status_unreadable");
+    if (scanPhase === undefined && measured.code === null)
+        return check("undetermined", "status_did_not_complete");
+    const report = measured.report;
+    if (report === null)
         return check("undetermined", "status_unreadable");
-    }
     const seam = typeof env.KEYSEAL_TEST_ROOT === "string" && env.KEYSEAL_TEST_ROOT !== "";
     const own = {
         machine_id: (value) => machineId !== null && value === machineId,
@@ -371,24 +461,58 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
         if (!matches(report[field]))
             return check("undetermined", `status_field_mismatch:${field}`);
     }
-    if (run.code === 1)
-        return check("fail", "keyslot_status_failed");
-    if (run.code === 2) {
-        const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+    // The report is about this host, user and slot: now it may say when OUR scan ran.
+    const scanReport = (source, of) => {
+        const scan = scanOf(of);
+        const { state, reason } = cacheStateOf(of);
+        return {
+            source, scanned_at: isoOf(scan.scanned_at), age_s: numOf(scan.age_s), duration_s: numOf(scan.duration_s),
+            cache_state: state === "" ? null : `${state}${reason ? `:${reason}` : ""}`,
+        };
+    };
+    const gaveUp = () => ({
+        check: check("undetermined", "scan_timed_out"),
+        scan: { ...scanReport("none", report), gave_up: { after_s: budgetS, folders: measured.folders } },
+    });
+    const code = measured.code;
+    const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+    let scan;
+    let effectiveCode = code;
+    if (carried && options.setupScan) {
+        // Setup's result stands in for phase 2: scan_not_cached is satisfied by it.
+        scan = {
+            source: "setup_run", scanned_at: new Date(options.setupScan.scannedAt * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"),
+            age_s: now() - options.setupScan.scannedAt, duration_s: numOf(options.setupScan.scan.duration_s), cache_state: scanReport("none", report).cache_state,
+        };
+        if (code === 2 && reasons.length === 1 && reasons[0] === "scan_not_cached")
+            effectiveCode = 0;
+    }
+    else {
+        const source = scanSourceOf(report);
+        if (source !== "none")
+            scan = scanReport(source, report);
+    }
+    const withScan = (result) => (scan ? { check: result, scan } : { check: result });
+    if (effectiveCode === 1)
+        return withScan(check("fail", "keyslot_status_failed"));
+    if (effectiveCode === 2) {
+        // status.sh's own self-bound: the scan gave up, and nothing else is undetermined.
+        if (scanPhase !== undefined && reasons.length === 1 && reasons[0] === "scan_timed_out")
+            return gaveUp();
         const named = reasons.length > 0 && reasons.every((reason) => typeof reason === "string" && STATUS_EXIT2_REASON.test(reason));
-        return check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined");
+        return withScan(check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined"));
     }
-    if (run.code !== 0)
-        return check("undetermined", "status_unexpected_exit");
+    if (effectiveCode !== 0)
+        return withScan(check("undetermined", "status_unexpected_exit"));
     if (report.mode === "sealed")
-        return check("pass", "sealed");
+        return withScan(check("pass", "sealed"));
     if (report.mode === "unsealed") {
         const optin = report.optin;
         if (optin?.ok !== true)
-            return check("fail", "unsealed_optin_invalid");
-        return unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid");
+            return withScan(check("fail", "unsealed_optin_invalid"));
+        return withScan(unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid"));
     }
-    return check("undetermined", "status_mode_unexpected");
+    return withScan(check("undetermined", "status_mode_unexpected"));
 }
 async function whoamiCheck(client, expectedHandle) {
     let rows;
@@ -482,6 +606,120 @@ export function judgeRuntime(harness, entries, identity) {
         return check("undetermined", unique(unknowns));
     return check("pass", "wake_producer_live");
 }
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime_hint`, over the SAME already-read `entries` `judgeRuntime` saw.
+ * Exported for its fixtures. Never reads `checks.runtime`'s own verdict, and never influences it:
+ * this is purely informational (see `RUNTIME_HINTS`'s doc comment for the precedence).
+ */
+export function judgeRuntimeHint(harness, entries, fs, options) {
+    const live = entries.filter((entry) => entry.status === "live")
+        .map((entry) => entry.record);
+    if (options.installedAt) {
+        // Checked even with ZERO live records (the macmini claude case: the harness wrote no record at
+        // all): an empty `live` makes every candidate process uncovered by construction, exactly as it
+        // should. Checking this before the `live.length === 0` fallback below is load-bearing — that
+        // fallback would otherwise short-circuit the one case IF-0-ONBOARD-3 names first.
+        //
+        // The same real-path comparison `pinCheck` uses for a record's cwd against doctor's own: a
+        // process is covered by a live record that is EITHER that process's own writer (pid-equal,
+        // true for pi/opencode's in-process plugin) OR launched from the same directory (true for the
+        // mcp child claude/codex/grok/agy launch, whose own pid never matches the harness's). Two
+        // uncovered sessions sharing one cwd is a stated false negative of the cwd half.
+        const real = (path) => fs.realpath(path) ?? resolve(path);
+        const recordPids = new Set(live.map((record) => record.pid));
+        const recordCwds = new Set(live.map((record) => real(record.cwd)));
+        const installedAt = options.installedAt;
+        const raw = (options.harnessProcesses ?? listHarnessProcesses)(harness, { startedBefore: installedAt });
+        // `startedBefore` is passed through as an optimisation hint to the injected/real lister; this
+        // cutoff is enforced here too, so an injected function that ignores it cannot fabricate a hint.
+        const processes = raw.filter((process) => process.startedAt.getTime() < installedAt.getTime());
+        const uncovered = processes.some((process) => !recordPids.has(process.pid) && !(process.cwd !== null && recordCwds.has(real(process.cwd))));
+        if (uncovered)
+            return "session_predates_install";
+    }
+    if (live.length === 0)
+        return "no_session";
+    if (options.installedVersion) {
+        const stale = live.some((record) => {
+            const installed = options.installedVersion(record.packageName);
+            return installed !== null && (compareVersions(record.packageVersion, installed) ?? 0) < 0;
+        });
+        if (stale)
+            return "stale_session_version";
+    }
+    if (harness === "opencode"
+        && live.some((record) => record.role === "wake_producer" && record.wake.tier === "tier0" && record.wake.reason === "no_target")) {
+        return "no_target_first_session";
+    }
+    return "none";
+}
+/** Default `statMtime`: a file that cannot be stat'd proves nothing, never an error. */
+function defaultStatMtime(path) {
+    try {
+        return statSync(path).mtime;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ONBOARD IF-0-ONBOARD-3 — the default `installedAt`/`installedVersion`, derived ONLY from what
+ * doctor already reads for its own `registration` check (never a new probe): each scope file's
+ * board-identified mcp entry (codex/grok/agy, and claude's own non-plugin mcp registrations — an
+ * `npx -y @consiliency/agent-board-mcp@<version> …` stanza) and `packages`/`plugin` spec (pi,
+ * opencode — a pinned `<package>@<version>` entry). `files` is in ascending precedence (SAME as
+ * `readScopes` returns it), so a later file's match for the same package overrides an earlier
+ * one's, exactly as the harness itself would resolve it.
+ *
+ * For claude, the plugin verdict `pinCheck` already computed and trusts (never an unvalidated
+ * directory source) is preferred over a raw config scan, per its own `versionFrom`/`sourceKind`
+ * guard — the same one `pinCheck` applies.
+ *
+ * `installedAt` is the LATEST mtime among every file that named a version this way: several files
+ * naming different packages (pi's own `packages` row plus an unrelated mcp row) both count, since
+ * either being freshly written is evidence this harness's board setup was just touched. A file (or
+ * a claude directory source) whose mtime cannot be read contributes nothing — not an error, and
+ * never lowers the claim to "no evidence at all" by itself.
+ *
+ * Exported for its fixtures.
+ */
+export function defaultInstallEvidence(harness, plugin, files, fs, statMtime) {
+    const found = new Map();
+    const VERSIONED = /^\d+[\w.+-]*$/;
+    // A live record's own `packageName` (written by the package itself, e.g. pi's `extension.ts`
+    // `PACKAGE_NAME`) is always bare — never carries a source scheme. pi's OWN config spec does
+    // (`npm:@consiliency/agent-board-pi@<v>`, pi's install-manifest convention); opencode's does not.
+    // Strip the scheme here so both key the same way a live record does.
+    const bare = (identity) => (identity.startsWith("npm:") ? identity.slice("npm:".length) : identity);
+    for (const file of files) {
+        for (const entry of file.contribution.mcp) {
+            if (!judgeMcpEntry(entry, fs).board)
+                continue;
+            for (const word of [entry.command ?? "", ...entry.args]) {
+                const identity = packageIdentity(word);
+                const version = word.slice(identity.length + 1);
+                if (identity !== word && VERSIONED.test(version))
+                    found.set(bare(identity), { version, path: file.path });
+            }
+        }
+        for (const spec of file.contribution.packages) {
+            const identity = packageIdentity(spec);
+            const version = spec.slice(identity.length + 1);
+            if (identity !== spec && VERSIONED.test(version))
+                found.set(bare(identity), { version, path: file.path });
+        }
+    }
+    if (harness === "claude" && plugin?.installed && plugin.version
+        && !(plugin.sourceKind === "directory" && plugin.versionFrom !== "source")) {
+        found.set(CLAUDE_PLUGIN_MCP_PACKAGE, { version: plugin.version, path: plugin.sourceKind === "directory" ? plugin.sourcePath : null });
+    }
+    const installedVersion = (packageName) => found.get(packageName)?.version ?? null;
+    const mtimes = [...found.values()]
+        .map((candidate) => (candidate.path ? statMtime(candidate.path) : null))
+        .filter((mtime) => mtime !== null);
+    const installedAt = mtimes.length > 0 ? new Date(Math.max(...mtimes.map((mtime) => mtime.getTime()))) : undefined;
+    return { installedAt, installedVersion };
+}
 function worst(checks) {
     return checks.find((item) => item.status === "fail")
         ?? checks.find((item) => item.status === "undetermined")
@@ -494,6 +732,7 @@ export async function runDoctor(options) {
     const cwd = options.cwd ?? process.cwd();
     const trust = options.trust ?? {};
     const checks = {};
+    let keyStorageScan;
     let values = null;
     try {
         values = (await readIdentityFile({ ...trust, harness, env })).values;
@@ -511,7 +750,9 @@ export async function runDoctor(options) {
     else {
         const fileEnv = fileIdentityEnv(env, values);
         checks.keystore_key = await keystoreCheck(values, fileEnv, options.probeKeystore ?? defaultKeystoreProbe);
-        checks.key_storage = await keyStorageCheck(harness, values, fileEnv, env, options);
+        const storage = await keyStorageCheck(harness, values, fileEnv, env, options);
+        checks.key_storage = storage.check;
+        keyStorageScan = storage.scan;
         let client = null;
         try {
             client = (options.createClient ?? defaultClient)(fileEnv);
@@ -530,17 +771,23 @@ export async function runDoctor(options) {
             checks.board_membership = check("undetermined", "whoami_not_passed");
         }
     }
+    const fs = options.registrationFs ?? nodeRegistrationFs;
     let entries = [];
+    // ONBOARD IF-0-ONBOARD-3: `runtime_hint` is computed further down, once records were read
+    // without throwing (a caught `records_unreadable` must never be misread as `no_session` from the
+    // empty `entries` the catch leaves behind) AND registration has been read (its scope files and
+    // claude's plugin verdict are the default install evidence).
+    let recordsReadable = false;
     try {
         entries = readSessionRecords(harness, { ...trust, env, isAlive: options.isAlive });
         checks.runtime = judgeRuntime(harness, entries, values && { handle: values[HANDLE_KEY], fingerprint: values[FINGERPRINT_KEY] });
+        recordsReadable = true;
     }
     catch (error) {
         checks.runtime = check("undetermined", codeOf(error, "records_unreadable"));
     }
     // Registration is read for this directory and for every live record's.
     const cwds = [...new Set([cwd, ...entries.flatMap((entry) => entry.status === "live" ? [entry.record.cwd] : [])])];
-    const fs = options.registrationFs ?? nodeRegistrationFs;
     const home = env.HOME && env.HOME.trim() !== "" ? env.HOME : homedir();
     const platform = options.platform ?? process.platform;
     let userName = options.userName;
@@ -566,10 +813,41 @@ export async function runDoctor(options) {
     verdicts[0] = pinCheck(verdicts[0], entries, cwd, fs);
     const registration = worst(verdicts);
     checks.registration = check(registration.status, registration.reason);
+    // ONBOARD IF-0-ONBOARD-3: `runtime_hint`, now that registration (this cwd's scope files and
+    // claude's plugin verdict) has been read — the default install evidence, unless a caller
+    // overrides either half. Computing the default is best-effort: a throw here (an unreadable
+    // scope file, say) leaves both unset rather than failing the whole report.
+    let runtimeHint = "none";
+    if (recordsReadable) {
+        let defaultInstalledAt;
+        let defaultInstalledVersion;
+        if (options.installedAt === undefined || options.installedVersion === undefined) {
+            try {
+                const { files } = readScopes(harness, { cwd, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? defaultClaudeManagedDir(platform),
+                    platform, userName, regQuery: options.regQuery, claudeMarketplacePackaged: options.claudeMarketplacePackaged,
+                    claudeMarketplaceTrust: options.claudeMarketplaceTrust });
+                const evidence = defaultInstallEvidence(harness, verdicts[0].plugin, files, fs, options.statMtime ?? defaultStatMtime);
+                defaultInstalledAt = evidence.installedAt;
+                defaultInstalledVersion = evidence.installedVersion;
+            }
+            catch {
+                // Leave both unset: the hint degrades to what it can prove, never a guess.
+            }
+        }
+        runtimeHint = judgeRuntimeHint(harness, entries, fs, {
+            installedAt: options.installedAt ?? defaultInstalledAt,
+            installedVersion: options.installedVersion ?? defaultInstalledVersion,
+            harnessProcesses: options.harnessProcesses,
+        });
+    }
     const ordered = Object.fromEntries(DOCTOR_CHECKS.map((name) => [name, checks[name]]));
     const statuses = Object.values(ordered).map((item) => item.status);
     const exit = statuses.every((status) => status === "pass") ? 0 : statuses.includes("fail") ? 1 : 2;
     const report = { harness, exit, checks: ordered };
+    if (runtimeHint !== "none")
+        report.runtime_hint = runtimeHint;
+    if (keyStorageScan)
+        report.key_storage_scan = keyStorageScan;
     const here = verdicts[0];
     if (harness === "claude") {
         const plugin = here.plugin;
@@ -594,9 +872,21 @@ export async function runDoctor(options) {
     }
     return report;
 }
+/** An age in seconds, as a short human span. */
+function ago(seconds) {
+    if (seconds === null)
+        return "?";
+    if (seconds < 120)
+        return `${seconds} s`;
+    if (seconds < 7200)
+        return `${Math.floor(seconds / 60)} min`;
+    return `${Math.floor(seconds / 3600)} h`;
+}
 /** Human-readable form; `--json` prints the report object itself. */
 export function formatDoctorReport(report) {
     const lines = DOCTOR_CHECKS.map((name) => `${report.checks[name].status.padEnd(12)} ${name}: ${report.checks[name].reason}`);
+    if (report.runtime_hint)
+        lines.push(`${"runtime_hint".padEnd(12)} ${report.runtime_hint}`);
     if (report.plugin) {
         const { plugin } = report;
         const counts = report.registration?.hook_counts;
@@ -610,6 +900,23 @@ export function formatDoctorReport(report) {
             counts ? `hooks SessionStart=${counts.SessionStart} FileChanged=${counts.FileChanged}` : "hooks undetermined",
         ].join(" "));
     }
+    const scan = report.key_storage_scan;
+    if (scan) {
+        const rescan = `\`agent-board doctor --harness ${report.harness} --rescan\``;
+        if (scan.gave_up) {
+            const after = scan.gave_up.after_s > 0 && scan.gave_up.after_s % 60 === 0 ? `${scan.gave_up.after_s / 60} min` : `${scan.gave_up.after_s} s`;
+            lines.push(`${"scan".padEnd(12)} gave up after ${after} (${scan.gave_up.folders ?? "?"} folders so far); ${rescan} retries`);
+        }
+        else if (scan.source === "fresh") {
+            lines.push(`${"scan".padEnd(12)} fresh (${scan.duration_s ?? "?"} s)${report.checks.key_storage.status === "pass" ? ", no plaintext copy found" : ""}`);
+        }
+        else if (scan.source === "setup_run") {
+            lines.push(`${"scan".padEnd(12)} setup's scan at ${scan.scanned_at ?? "?"} (${ago(scan.age_s)} ago), no plaintext copy found`);
+        }
+        else if (scan.source === "cached") {
+            lines.push(`${"scan".padEnd(12)} cached at ${scan.scanned_at ?? "?"} (${ago(scan.age_s)} ago); ${rescan} scans again`);
+        }
+    }
     if (report.managed_policy) {
         const policy = report.managed_policy;
         lines.push([

package/dist/identity_writer.d.ts

@@ -1,46 +1 @@
-import { type EnrollmentOutcome } from "@consiliency/agent-board-client";
-export interface OwnerOnlyWriteOptions {
-    syncDirectory?: (path: string) => Promise<void>;
-}
-/** Create `path` exclusively (never following a planted link) at 0600, write, fsync. */
-export declare function writeOwnerOnlyFile(path: string, content: string): Promise<void>;
-/**
- * Write `content` to `path` so a reader sees the old file or the whole new one, never a
- * part: an exclusive 0600 temp beside it, fsync'd, renamed over it, then the directory
- * fsync'd. On any throw before the rename the temp is removed.
- */
-export declare function writeOwnerOnlyFileAtomic(path: string, content: string, options?: OwnerOnlyWriteOptions): Promise<void>;
-export interface IdentityDeployment {
-    boardUrl: string;
-    sessionUrl: string;
-    publishableKey: string;
-}
-/**
- * Where each deployment value is read, in precedence order: the client's one alias table
- * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
- * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
- * the same table, so the two cannot disagree. The generic Supabase names are in no list: a
- * generic key never fills an identity field, here or in the loader.
- */
-export declare const DEPLOYMENT_ENV_NAMES: Readonly<Record<keyof IdentityDeployment, readonly string[]>>;
-/**
- * The deployment half of an identity, read and shape-checked before enrollment commits. Each
- * value is the shipped default, or env under the board group's all-or-nothing rule (the
- * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
- * naming the variable that switched the group off; not the non-secret shape its key requires →
- * `identity_secret_value`. Both name the variable, never the value.
- */
-export declare function resolveIdentityDeployment(env: NodeJS.ProcessEnv): IdentityDeployment;
-/**
- * The identity file's values for an enrolled agent. The URLs and publishable key come only
- * from `deployment`; everything else from the outcome. Validated by the client's serializer
- * before it is returned.
- */
-export declare function identityValuesFromEnrollment(outcome: EnrollmentOutcome, deployment: IdentityDeployment): Record<string, string>;
-/**
- * Write `harness`'s identity file for this host. Every refusal (bad harness, relative root,
- * invalid host, bad value) fires before the first filesystem change. The directory is then
- * put through the reader's own trusted walk, so the writer never produces a file the loader
- * would refuse to open. Returns the path written.
- */
-export declare function writeIdentityFile(harness: string, values: Readonly<Record<string, string>>, env: NodeJS.ProcessEnv, options?: OwnerOnlyWriteOptions): Promise<string>;
+export { DEPLOYMENT_ENV_NAMES, identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, writeOwnerOnlyFile, writeOwnerOnlyFileAtomic, type IdentityDeployment, type OwnerOnlyWriteOptions, } from "@consiliency/agent-board-client";