@consiliency/agent-board-cli 1.22.5 → 1.24.0

package/dist/doctor.js

@@ -0,0 +1,453 @@
+// CREDPATH IF-0-CREDPATH-4 — `agent-board doctor --harness <h>`, as a module. SL-6 registers it.
+//
+// Doctor judges ONE identity: the harness's identity FILE, read through the client's trusted
+// open (`readIdentityFile`), never doctor's own shell environment. Every networked check is bound
+// to that file's handle and fingerprint through a client whose credentials resolve from the
+// file alone. Records written by live harness processes are judged against the same identity.
+//
+// Exit 0 iff every check passes; else 1 if any check fails; else 2. The `runtime` check passes
+// 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 { randomBytes } from "node:crypto";
+import { homedir, userInfo } from "node:os";
+import { 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, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
+import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
+export const DOCTOR_CHECKS = Object.freeze([
+    "identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime",
+]);
+export const REPORTABLE_TOKEN = /^[A-Za-z0-9._/-]{1,64}$/;
+const reportable = (value) => value === null ? null : REPORTABLE_TOKEN.test(value) ? value : "unrecognised";
+/**
+ * The pin, over the live wake_producers whose cwd (realpath) is doctor's cwd, and only while our
+ * plugin's server is registered there. All at the pin (our plugin's version) → unchanged; NONE at
+ * it → `plugin_pin_mismatch`; a MIXED set → `plugin_pin_ambiguous` (which one is ours is unknown).
+ * A record elsewhere was launched by whatever registration applies THERE. An earlier reason is
+ * kept and this one appended.
+ */
+function pinCheck(verdict, entries, cwd, fs) {
+    // Only while our plugin's server is registered here: one turned off by `disabledMcpServers`
+    // launched nothing whose version could be judged (panel S1).
+    const pin = verdict.plugin?.installed && verdict.plugin.serverActive ? verdict.plugin.version : null;
+    if (pin === null)
+        return verdict;
+    // Real paths on both sides (panel S2): a server records its physical cwd; doctor may be in a symlink.
+    const real = (path) => fs.realpath(path) ?? resolve(path);
+    const here = entries.flatMap((entry) => entry.status === "live" && entry.record.role === "wake_producer"
+        && real(entry.record.cwd) === real(cwd) ? [entry.record] : []);
+    const atPin = here.filter((record) => record.packageVersion === pin).length;
+    // All at the pin → nothing to say; none → a mismatch; a mixed set → which one is ours is unknown (panel B1).
+    if (atPin === here.length)
+        return verdict;
+    // An earlier reason is kept, never overwritten (panel S5).
+    const earlier = verdict.status === "pass" ? [] : [verdict.reason];
+    if (atPin === 0)
+        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 binary's managed-settings directory per platform (`Zh()`, 2.1.283). */
+function defaultClaudeManagedDir(platform) {
+    if (platform === "darwin")
+        return "/Library/Application Support/ClaudeCode";
+    if (platform === "win32")
+        return "C:\\Program Files\\ClaudeCode";
+    return "/etc/claude-code";
+}
+const FINGERPRINT_KEY = "AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT";
+const HANDLE_KEY = "AGENT_BOARD_EXPECTED_AGENT_HANDLE";
+const KEY_REFERENCE_KEY = "AGENT_BOARD_AGENT_KEY_REFERENCE";
+if (![FINGERPRINT_KEY, HANDLE_KEY, KEY_REFERENCE_KEY].every((key) => IDENTITY_FILE_KEYS.includes(key))) {
+    throw new Error("doctor: an identity key it reads is not in IDENTITY_FILE_KEYS");
+}
+/**
+ * An error's `code`, only when this repository wrote it: a member of the derived
+ * AUTHORED_CAUSE_CODES that this instance carries under the authored provenance brand — the
+ * CLI's `namedCauseCode` gate (#403). Anything else — a code copied from a /session or PostgREST
+ * body, an errno, an unbranded error — is replaced by `fallback`, a fixed local classification.
+ * A shape test cannot do this: a server may put any well-shaped token in `code` (code review
+ * round 1, Astra 4: `sb_secret_…` passed the previous `^[A-Za-z0-9_.:-]{1,80}$` filter).
+ */
+export function authoredCode(error, fallback) {
+    const value = error?.code;
+    if (typeof value === "string" && AUTHORED_CAUSE_CODES.has(value) && codeProvenance(error) === "authored")
+        return value;
+    return fallback;
+}
+const codeOf = authoredCode;
+/** A refusal the service marks retryable (5xx, 429, …) is about the service, not the identity. */
+function isRetryable(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth += 1) {
+        if (current.retryable === true)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+// Transport failures, by the errno/undici codes and error names Node's fetch surfaces. These
+// say nothing about the identity, so they are undetermined; any other refusal is a fail.
+const NETWORK_CODES = new Set([
+    "ECONNREFUSED", "ECONNRESET", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT", "EHOSTUNREACH", "ENETUNREACH", "EPIPE",
+    "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT", "UND_ERR_SOCKET", "UND_ERR_CLOSED",
+]);
+export function isNetworkError(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth += 1) {
+        const candidate = current;
+        if (typeof candidate.code === "string" && NETWORK_CODES.has(candidate.code))
+            return true;
+        if (candidate.name === "AbortError" || candidate.name === "TimeoutError")
+            return true;
+        if (candidate.name === "TypeError" && candidate.message === "fetch failed")
+            return true;
+        current = candidate.cause;
+    }
+    return false;
+}
+/**
+ * The session mint signs with the identity's key, so a keystore that cannot be reached fails
+ * `whoami` too. That says nothing about the identity: undetermined, like `keystore_key`.
+ */
+export function isKeystoreUnreachable(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth += 1) {
+        if (current instanceof KeystoreUnavailableError)
+            return true;
+        if (current instanceof AgentSocketSelectionError && current.reason === "unreachable")
+            return true;
+        const code = current.code;
+        if (code === "keystore_unavailable" || code === "agent_socket_unreachable")
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+function rowsOf(result) {
+    const data = result?.data;
+    return Array.isArray(data) ? data.filter((row) => !!row && typeof row === "object") : [];
+}
+/** The ambient env minus every identity and generic name, plus the file: the file is the identity. */
+export function fileIdentityEnv(ambient, values) {
+    const drop = new Set([...IDENTITY_TRIGGER_FIELDS, ...GENERIC_SUPABASE_FIELDS]);
+    const env = {};
+    for (const [name, value] of Object.entries(ambient))
+        if (!drop.has(name))
+            env[name] = value;
+    return { ...env, ...values };
+}
+function defaultClient(fileEnv) {
+    const client = createAgentBoardClient({ resolveCredentials: () => resolveCredentials(undefined, fileEnv) });
+    return {
+        whoami: (input) => client.whoami(input),
+        boardMemberships: (query) => client.boardMemberships(query),
+    };
+}
+/**
+ * The default os_keychain probe. Doctor never holds private-key bytes, so it does not read the
+ * item: it asks the client's own backend to SIGN a nonce, exactly as a session mint would. A
+ * signature proves the key is present; it does not prove WHICH key, so the result is
+ * `present_unverified`.
+ *
+ * What `whoami` then proves, and what it does not (code review round 1, Opus B1 / Astra 2): the
+ * session mint sends `agent_slug`, `key_id`, `key_version` and a signature — never the file's
+ * fingerprint — and the server verifies the signature against the key enrolled under that
+ * key_id. So a passing `whoami` proves the keychain holds the enrolled key FOR THE FILE'S KEY_ID.
+ * It says nothing about the file's `AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT`, which stays
+ * unverified for os_keychain; the check's reason says so. By default the backend runs with the
+ * client's own exec; `spawn` (the client's exported exec seam) exists only so tests can stand in
+ * for the keychain CLI. Nothing here reads its output; doctor.test.ts K-0 pins that no
+ * key-decoding API is reachable.
+ */
+export function osKeychainProbe(spawn) {
+    return async (keyReference) => {
+        const reference = normalizeKeyReference(keyReference);
+        try {
+            const capability = await createOsKeychainBackend(spawn ? { exec: spawn } : {})(reference);
+            await capability.sign(randomBytes(32));
+            return { kind: "present_unverified" };
+        }
+        catch (error) {
+            // The client raises one code for "no item" and "cannot reach the keychain"; only its
+            // message tells them apart (pinned by K-2 against the client's real backend).
+            if (error instanceof KeystoreUnavailableError && /no key found/.test(error.message)) {
+                return { kind: "absent", reason: "key_absent" };
+            }
+            return { kind: "unreachable", reason: codeOf(error, "keystore_unavailable") };
+        }
+    };
+}
+/** The default agent_socket probe: the loaded key's fingerprint, derived from the agent's identity list. */
+export const agentSocketProbe = async (keyReference, expectedFingerprint, env) => {
+    const reference = normalizeKeyReference(keyReference);
+    // A `#<pub>` handle pins the key itself; otherwise the file's fingerprint is the only selector,
+    // and a match IS the comparison.
+    const pinned = { ...reference, publicKeyFingerprint: reference.handle.includes("#") ? null : expectedFingerprint };
+    try {
+        const selected = await selectAgentSocketIdentity(pinned, { env });
+        return { kind: "found", fingerprint: selected.publicKeyFingerprint };
+    }
+    catch (error) {
+        if (error instanceof AgentSocketSelectionError) {
+            return error.reason === "unreachable"
+                ? { kind: "unreachable", reason: codeOf(error, "agent_socket_unreachable") }
+                : { kind: "absent", reason: codeOf(error, "agent_socket_no_match") };
+        }
+        // No socket to ask (`SSH_AUTH_SOCK` unset): nothing was learned about the key.
+        if (error instanceof KeystoreUnavailableError)
+            return { kind: "unreachable", reason: codeOf(error, "keystore_unavailable") };
+        return { kind: "absent", reason: codeOf(error, "key_reference_invalid") };
+    }
+};
+const defaultKeystoreProbe = async (keyReference, expectedFingerprint, env) => {
+    const resolver = normalizeKeyReference(keyReference).resolver;
+    if (resolver === "agent_socket")
+        return agentSocketProbe(keyReference, expectedFingerprint, env);
+    if (resolver === "os_keychain")
+        return osKeychainProbe()(keyReference, expectedFingerprint, env);
+    return { kind: "unreachable", reason: `resolver_unsupported:${resolver}` };
+};
+const check = (status, reason) => ({ status, reason });
+export const OS_KEYCHAIN_PRESENT = "present; key_id proven server-side by whoami; file fingerprint unverified for os_keychain";
+async function keystoreCheck(values, env, probe) {
+    let result;
+    try {
+        result = await probe(values[KEY_REFERENCE_KEY], values[FINGERPRINT_KEY], env);
+    }
+    catch (error) {
+        return check("undetermined", codeOf(error, "keystore_probe_error"));
+    }
+    if (result.kind === "unreachable")
+        return check("undetermined", result.reason);
+    if (result.kind === "absent")
+        return check("fail", result.reason);
+    // Presence, and the key_id is proven by `whoami`; the file's fingerprint is NOT (see osKeychainProbe).
+    if (result.kind === "present_unverified")
+        return check("pass", OS_KEYCHAIN_PRESENT);
+    return result.fingerprint === values[FINGERPRINT_KEY]
+        ? check("pass", "fingerprint_matches")
+        : check("fail", "fingerprint_mismatch");
+}
+async function whoamiCheck(client, expectedHandle) {
+    let rows;
+    try {
+        rows = rowsOf(await client.whoami({}));
+    }
+    catch (error) {
+        if (isNetworkError(error))
+            return { check: check("undetermined", "network_error"), agentId: null };
+        if (isKeystoreUnreachable(error))
+            return { check: check("undetermined", "keystore_unreachable"), agentId: null };
+        if (isRetryable(error))
+            return { check: check("undetermined", "service_unavailable"), agentId: null };
+        return { check: check("fail", codeOf(error, "whoami_refused")), agentId: null };
+    }
+    const row = rows[0];
+    if (!row)
+        return { check: check("fail", "no_acting_identity"), agentId: null };
+    if (row.handle !== expectedHandle)
+        return { check: check("fail", "handle_mismatch"), agentId: null };
+    const agentId = typeof row.agent_id === "string" ? row.agent_id : null;
+    if (!agentId)
+        return { check: check("fail", "no_agent_id"), agentId: null };
+    return { check: check("pass", "expected_handle"), agentId };
+}
+const ACTIVE_MEMBERSHIP = new Set(["joined", "subscribed"]);
+async function membershipCheck(client, agentId) {
+    let rows;
+    try {
+        rows = rowsOf(await client.boardMemberships({ agentId, limit: 50 }));
+    }
+    catch (error) {
+        if (isNetworkError(error))
+            return check("undetermined", "network_error");
+        if (isRetryable(error))
+            return check("undetermined", "service_unavailable");
+        return check("fail", codeOf(error, "membership_read_refused"));
+    }
+    const active = rows.filter((row) => row.agent_id === agentId && ACTIVE_MEMBERSHIP.has(String(row.membership_state)));
+    return active.length > 0 ? check("pass", "member") : check("fail", "no_membership");
+}
+const TIER_RANK = { tier0: 0, wake: 1 };
+/** IF-0-CREDPATH-4 runtime, over already-read records. Exported for its fixtures. */
+export function judgeRuntime(harness, entries, identity) {
+    const fails = [];
+    const unknowns = [];
+    if (entries.some((entry) => entry.status === "untrusted"))
+        fails.push("record_untrusted");
+    const live = entries.filter((entry) => entry.status === "live")
+        .map((entry) => entry.record);
+    for (const record of live) {
+        if (record.identitySource === "env")
+            unknowns.push("identity_source_env");
+        else if (identity === null)
+            unknowns.push("identity_unknown");
+        else if (record.identityHandle !== identity.handle || record.identityFingerprint !== identity.fingerprint)
+            fails.push("identity_mismatch");
+    }
+    const producers = live.filter((record) => record.role === "wake_producer");
+    const liveProducer = producers.length > 0;
+    for (const record of live) {
+        if (record.wake.tier === "arming") {
+            unknowns.push("arming");
+            continue;
+        }
+        if (record.role === "wake_producer") {
+            if (TIER_RANK[record.wake.tier] < TIER_RANK[expectedWakeTier(harness, record.flags)])
+                fails.push("below_expected_tier");
+        }
+        else if (record.wake.tier !== "tier0") {
+            fails.push(`${record.role}_above_tier0`);
+        }
+        else if (record.role === "tools_only" && !liveProducer) {
+            unknowns.push("tools_only_without_producer");
+        }
+    }
+    if (!liveProducer)
+        unknowns.push("no_live_wake_producer");
+    const byHash = new Map();
+    for (const record of live) {
+        if (record.wake.tier !== "wake" || record.sessionHash === null)
+            continue;
+        byHash.set(record.sessionHash, (byHash.get(record.sessionHash) ?? 0) + 1);
+    }
+    if ([...byHash.values()].some((count) => count > 1))
+        fails.push("duplicate_wake_server");
+    const unique = (list) => [...new Set(list)].join(",");
+    if (fails.length > 0)
+        return check("fail", unique(fails));
+    if (unknowns.length > 0)
+        return check("undetermined", unique(unknowns));
+    return check("pass", "wake_producer_live");
+}
+function worst(checks) {
+    return checks.find((item) => item.status === "fail")
+        ?? checks.find((item) => item.status === "undetermined")
+        ?? checks[0];
+}
+export async function runDoctor(options) {
+    assertIdentityHarness(options.harness);
+    const harness = options.harness;
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const trust = options.trust ?? {};
+    const checks = {};
+    let values = null;
+    try {
+        values = (await readIdentityFile({ ...trust, harness, env })).values;
+        checks.identity_file = check("pass", "trusted");
+    }
+    catch (error) {
+        checks.identity_file = check("fail", codeOf(error, "identity_unreadable"));
+    }
+    if (values === null) {
+        checks.keystore_key = check("undetermined", "no_identity_file");
+        checks.whoami = check("undetermined", "no_identity_file");
+        checks.board_membership = check("undetermined", "no_identity_file");
+    }
+    else {
+        const fileEnv = fileIdentityEnv(env, values);
+        checks.keystore_key = await keystoreCheck(values, fileEnv, options.probeKeystore ?? defaultKeystoreProbe);
+        let client = null;
+        try {
+            client = (options.createClient ?? defaultClient)(fileEnv);
+        }
+        catch (error) {
+            checks.whoami = check("fail", codeOf(error, "client_unavailable"));
+        }
+        if (client) {
+            const who = await whoamiCheck(client, values[HANDLE_KEY]);
+            checks.whoami = who.check;
+            checks.board_membership = who.agentId === null
+                ? check("undetermined", "whoami_not_passed")
+                : await membershipCheck(client, who.agentId);
+        }
+        else {
+            checks.board_membership = check("undetermined", "whoami_not_passed");
+        }
+    }
+    let entries = [];
+    try {
+        entries = readSessionRecords(harness, { ...trust, env, isAlive: options.isAlive });
+        checks.runtime = judgeRuntime(harness, entries, values && { handle: values[HANDLE_KEY], fingerprint: values[FINGERPRINT_KEY] });
+    }
+    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;
+    if (userName === undefined) {
+        try {
+            userName = (options.lookupUserName ?? (() => userInfo().username))() || undefined;
+        }
+        catch {
+            userName = undefined;
+        }
+    }
+    const verdicts = cwds.map((dir) => {
+        try {
+            return judgeRegistration(harness, { cwd: dir, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? defaultClaudeManagedDir(platform),
+                platform, userName, regQuery: options.regQuery });
+        }
+        catch (error) {
+            return check("undetermined", codeOf(error, "registration_unreadable"));
+        }
+    });
+    // `cwds[0]` is doctor's own cwd: the pin and the report are about it.
+    verdicts[0] = pinCheck(verdicts[0], entries, cwd, fs);
+    const registration = worst(verdicts);
+    checks.registration = check(registration.status, registration.reason);
+    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 };
+    const here = verdicts[0];
+    if (harness === "claude") {
+        const plugin = here.plugin;
+        report.plugin = {
+            installed: plugin?.installed ?? false,
+            installed_version: reportable(plugin?.version ?? null),
+            pinned_mcp_version: reportable(plugin?.pinnedMcpVersion ?? null),
+            source_ref: reportable(plugin?.sourceRef ?? null),
+            auto_update: plugin ? { effective: plugin.autoUpdate.effective, source: plugin.autoUpdate.source } : { effective: false, source: "undetermined" },
+        };
+        if (here.hookCounts)
+            report.registration = { hook_counts: { SessionStart: here.hookCounts.SessionStart, FileChanged: here.hookCounts.FileChanged } };
+        if (here.managedPolicy) {
+            report.managed_policy = {
+                checked: [...here.managedPolicy.checked], evidence: [...here.managedPolicy.evidence],
+                unreadable_sources_possible: here.managedPolicy.unreadableSourcesPossible, platform: here.managedPolicy.platformLabel,
+            };
+        }
+    }
+    return report;
+}
+/** 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.plugin) {
+        const { plugin } = report;
+        const counts = report.registration?.hook_counts;
+        lines.push([
+            `${"plugin".padEnd(12)} installed=${plugin.installed ? "yes" : "no"}`,
+            `version=${plugin.installed_version ?? "none"}`,
+            `pinned_mcp=${plugin.pinned_mcp_version ?? "none"}`,
+            `ref=${plugin.source_ref ?? "none"}`,
+            `auto_update=${plugin.auto_update.effective ? "on" : "off"}(${plugin.auto_update.source})`,
+            counts ? `hooks SessionStart=${counts.SessionStart} FileChanged=${counts.FileChanged}` : "hooks undetermined",
+        ].join(" "));
+    }
+    if (report.managed_policy) {
+        const policy = report.managed_policy;
+        lines.push([
+            `${"admin policy".padEnd(12)} checked ${policy.checked.join(",") || "none"}`,
+            policy.evidence.length > 0 ? `; found ${policy.evidence.join(",")}` : "",
+            policy.unreadable_sources_possible ? `; ${policy.platform} MDM profiles not fully readable` : "",
+        ].join(""));
+    }
+    return [`agent-board doctor --harness ${report.harness}`, ...lines, `exit ${report.exit}`].join("\n");
+}