@consiliency/agent-board-cli 1.22.5 → 1.23.0

package/dist/doctor.js

@@ -0,0 +1,360 @@
+// 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 } from "node:os";
+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",
+]);
+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();
+    checks.registration = worst(cwds.map((dir) => {
+        try {
+            return judgeRegistration(harness, { cwd: dir, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? "/etc/claude-code" });
+        }
+        catch (error) {
+            return check("undetermined", codeOf(error, "registration_unreadable"));
+        }
+    }));
+    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;
+    return { harness, exit, checks: ordered };
+}
+/** 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}`);
+    return [`agent-board doctor --harness ${report.harness}`, ...lines, `exit ${report.exit}`].join("\n");
+}

package/dist/doctor_scopes.d.ts

@@ -0,0 +1,128 @@
+import type { IdentityHarness } from "@consiliency/agent-board-client";
+export declare const BOARD_MCP_MARKER = "agent-board-mcp";
+export declare const METADATA_ONLY_FLAG = "--metadata-only";
+export declare const OPENCODE_PLUGIN_PACKAGE = "@consiliency/agent-board-opencode";
+export declare const PI_PACKAGE = "npm:@consiliency/agent-board-pi";
+/** Claude Code events that each need exactly one `wake-hook.sh` hook (`docs/local-wake-signal.md`). */
+export declare const CLAUDE_REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "FileChanged"];
+export declare const WAKE_HOOK_MARKER = "wake-hook.sh";
+export interface ScopeContext {
+    cwd: string;
+    home: string;
+    env: Record<string, string | undefined>;
+    /** Claude Code's managed directory (Linux `/etc/claude-code`); injectable for tests. */
+    claudeManagedDir: string;
+    fs: RegistrationFs;
+}
+/** The filesystem reads registration makes; everything is read-only. */
+export interface RegistrationFs {
+    /** File text, or null when the file does not exist. */
+    readFile(path: string): string | null;
+    /** Sorted entry names, or null when the directory does not exist. */
+    readdir(path: string): string[] | null;
+    lstat(path: string): {
+        uid: number;
+        size: number;
+        isFile: boolean;
+    } | null;
+    exists(path: string): boolean;
+    getuid(): number;
+}
+export declare const nodeRegistrationFs: RegistrationFs;
+export declare class UnparseableConfigError extends Error {
+    constructor(message: string);
+}
+/** Keys that name a prototype slot rather than data: a file carrying one is refused. */
+export declare const FORBIDDEN_CONFIG_KEYS: ReadonlySet<string>;
+/** An OWN property of `value`, else undefined: nothing is read through a prototype. */
+export declare function own(value: unknown, key: string): unknown;
+/** JSONC: `//` and `/* *\/` comments and trailing commas removed outside strings, then JSON. */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * A restricted TOML reader: enough of the grammar to read `[mcp_servers.*]` and `[projects.*]`
+ * tables without a new dependency, and fail-closed on anything outside it. It handles bare and
+ * quoted dotted keys, `[table]` and `[[array.table]]` headers, basic/literal (and multi-line)
+ * strings, arrays over several lines, inline tables, and bare scalars. Sub-tables nest, so
+ * `[mcp_servers.x.env]` is `x`'s `env`, never a server named `x.env`.
+ */
+export declare function parseRestrictedToml(text: string): Record<string, unknown>;
+type McpShape = "claude" | "toml" | "agy" | "opencode";
+export interface McpEntry {
+    /** Server name (the harness merges same-named entries across its layers). */
+    name: string;
+    command: string | null;
+    args: string[];
+    /** The harness will not launch it (`disabled: true`, `enabled = false`). */
+    disabled: boolean;
+    /** The entry's own fields, as written: a field-merging harness overlays these across layers. */
+    fields: Readonly<Record<string, unknown>>;
+    shape: McpShape;
+}
+export interface ScopeContribution {
+    mcp: McpEntry[];
+    /** Claude hooks: event → the command strings registered for it. */
+    hooks: Record<string, string[]>;
+    /** opencode `plugin` / pi `packages` specs. */
+    packages: string[];
+}
+export interface ScopeFile {
+    row: string;
+    path: string;
+    contribution: ScopeContribution;
+}
+type Parser = "json" | "json_or_empty" | "jsonc" | "toml";
+export interface ScopeRow {
+    /** Stable row name; reported, and keyed by the per-row fixture table in doctor.test.ts. */
+    name: string;
+    parser: Parser;
+    /** Precedence within the harness: a same-named entry in a higher-ranked row overrides. */
+    rank: number;
+    /**
+     * For a row whose paths walk from cwd up to the git root (cwd first), one file per directory:
+     * which end wins when two of its files name the same server. Absent for a single-path row, and
+     * for a row that already returns its paths in application order (`opencode_project`, which has
+     * two files per directory and must not have them swapped).
+     */
+    walkWins?: "nearest" | "farthest";
+    /** Every candidate file for this row (absent ones are skipped). */
+    paths(ctx: ScopeContext): string[];
+    /** Whether a present file at `path` is loaded by the harness (codex trust). Default: yes. */
+    loaded?(path: string, ctx: ScopeContext): boolean;
+    extract(document: unknown, ctx: ScopeContext): ScopeContribution;
+}
+/** Judge-relevant fields of one entry, from its own fields only. */
+export declare function mcpEntry(name: string, fields: Readonly<Record<string, unknown>>, shape: McpShape): McpEntry;
+/** Directories from `cwd` up to its git root (inclusive); just `cwd` outside a repository. */
+export declare function walkToGitRoot(cwd: string, fs: RegistrationFs): string[];
+/** The frozen, re-checked scope table (see the header for each amendment and its evidence). */
+export declare const HARNESS_CONFIG_SCOPES: Readonly<Record<IdentityHarness, readonly ScopeRow[]>>;
+/**
+ * How a harness combines a same-named entry across its layers (see the header): codex and
+ * opencode overlay the higher layer's fields (measured); claude replaces the whole entry
+ * (inferred); grok is assumed to behave like codex (unmeasured); agy and pi have one layer, so
+ * their value is never used.
+ */
+export declare const MCP_LAYER_MERGE: Readonly<Record<IdentityHarness, "replace" | "fields">>;
+/** A package spec's identity without its version: `@scope/name@1.2.3` → `@scope/name`. */
+export declare function packageIdentity(spec: string): string;
+interface BoardEntryVerdict {
+    board: boolean;
+    flagged: boolean;
+}
+/** A board MCP entry names `agent-board-mcp` in its command/args, or through ONE user-owned wrapper file. */
+export declare function judgeMcpEntry(entry: McpEntry, fs: RegistrationFs): BoardEntryVerdict;
+export interface RegistrationVerdict {
+    status: "pass" | "fail" | "undetermined";
+    reason: string;
+}
+/**
+ * Read every scope row of `harness` for `cwd`. A file that fails to parse is reported, not guessed.
+ * `files` is in ascending precedence: a later file's same-named entry overrides an earlier one's.
+ */
+export declare function readScopes(harness: IdentityHarness, ctx: ScopeContext): {
+    files: ScopeFile[];
+    unparseable: string[];
+};
+/** IF-0-CREDPATH-4 registration, for one working directory. */
+export declare function judgeRegistration(harness: IdentityHarness, ctx: ScopeContext): RegistrationVerdict;
+export {};