@consiliency/agent-board-cli 1.22.5 → 1.23.0

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt } from "@consiliency/agent-board-client";
+import { type DoctorOptions, type DoctorReport } from "./doctor.js";
 import { DevicePendingEnrollmentStore } from "./enroll_runtime.js";
 type JsonObject = Record<string, unknown>;
 export interface CliIo {
@@ -303,6 +304,8 @@ export type StringFieldsOf<T> = {
 }[keyof T];
 type FleetTupleField = StringFieldsOf<FleetOnboardingIntent>;
 export declare const FLEET_TUPLE_DISPOSITION: Readonly<Record<FleetTupleField, FleetTupleDisposition>>;
-export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner): Command;
-export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner): Promise<void>;
+/** `runDoctor`'s shape; a seam so the exit-code wiring is testable without a live board. */
+export type DoctorRunner = (options: DoctorOptions) => Promise<DoctorReport>;
+export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner): Command;
+export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner): Promise<void>;
 export {};

package/dist/cli.js

@@ -1,8 +1,11 @@
 import { Command, Option } from "commander";
 import { createHash, randomUUID } from "node:crypto";
+import * as nodeFs from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, } from "@consiliency/agent-board-client";
+import { dirname, join } from "node:path";
+import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, assertIdentityHarness, identityFilePath, resolveHostSegment, identityConfigRoot, walkTrustedDirectory, IDENTITY_HARNESSES, CredentialResolutionError, } from "@consiliency/agent-board-client";
+import { formatDoctorReport, runDoctor } from "./doctor.js";
+import { identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, } from "./identity_writer.js";
 import { DevicePendingEnrollmentStore, FilePendingEnrollmentStore, FleetDeviceContinuationStore, makeBrowserOpener, prepareFleetRuntimeOutput, publishFinalizedFleetTemplate, } from "./enroll_runtime.js";
 function isRuntimeStatus(value) {
     return Boolean(value && typeof value === "object" && "runtime" in value);
@@ -2052,8 +2055,74 @@ function buildPendingFleetTemplate(intent, publishableKeyFieldReference = DEFAUL
     const mismatch = localKeyMismatchFailure(pending, intent, ref);
     if (mismatch)
         throw new FleetSafeMessageError("fleet_onboarding_local_key_mismatch", mismatch);
+    fleetIdentityFilePreflight(pending, host);
     return pending;
 }
+function isIdentityHarness(kind) {
+    return IDENTITY_HARNESSES.includes(kind);
+}
+const FLEET_HOST_MISMATCH_MESSAGE = "this host's identity file would be written for a different host than the one "
+    + '--expected-agent-handle names: the part of the handle before "-<harness-kind>" must equal this host\'s short '
+    + "hostname, or MESSAGE_BOARD_WAKE_MACHINE_ID when it is set. Set MESSAGE_BOARD_WAKE_MACHINE_ID to that part if "
+    + "this is the right machine. Neither value is echoed: both can carry operator-supplied text.";
+/**
+ * CREDPATH SL-6 — the fleet half of the identity-file preflight, for identity harnesses only.
+ *
+ * Called from `buildPendingFleetTemplate`, which BOTH fleet paths run before the server is
+ * asked to commit (run, device begin, and the device resume's candidate), so a value the file
+ * would refuse is refused while the bounded invite use is unspent (#176, and #521's
+ * single-use rule). Three things are checked, all before any write:
+ *   - the host the file's path names (`resolveHostSegment`) is the host the handle names;
+ *   - the config root is absolute;
+ *   - the board URL, session URL and publishable key are the non-secret shapes the file
+ *     requires, judged by SL-2's own preflight so there is one shape rule. An ABSENT key is
+ *     left to `resolveFleetPublishableKey`, which names the variable.
+ * Every refusal is a literal this file writes; no operand is echoed.
+ */
+const TRUSTED_WALK_CAUSES = new Set(["identity_path_symlink", "identity_path_foreign_owner",
+    "identity_path_permissions", "identity_absent"]);
+function fleetIdentityFilePreflight(pending, host) {
+    if (!isIdentityHarness(pending.harnessKind))
+        return;
+    if (resolveHostSegment(process.env) !== host) {
+        throw new FleetSafeMessageError("identity_host_mismatch", FLEET_HOST_MISMATCH_MESSAGE);
+    }
+    try {
+        identityFilePath(pending.harnessKind, process.env);
+    }
+    catch {
+        throw new FleetSafeMessageError("identity_config_root_relative", "the identity file's config root must be absolute: XDG_CONFIG_HOME (or HOME) is relative. Nothing was sent.");
+    }
+    try {
+        identityDirectoryPreflight(pending.harnessKind);
+    }
+    catch (error) {
+        // The client's message names the path, and the path carries the handle's host — operator
+        // text. Only the client's code crosses, and only from its closed walk vocabulary.
+        const raw = error?.code;
+        const cause = typeof raw === "string" && TRUSTED_WALK_CAUSES.has(raw) ? raw : "unknown";
+        throw new FleetSafeMessageError("identity_path_untrusted", `the directory the harness's identity file would be written to is not private to you (${cause}): `
+            + "$XDG_CONFIG_HOME (or ~/.config) and every directory above it must not be a user-owned symlink, "
+            + "foreign-owned, world-writable, or group-writable by a group other than your private one, and "
+            + "agent-board/ beneath it must be yours and mode 700. The path is not echoed: it carries the handle's host. "
+            + "Nothing was sent.");
+    }
+    const publishableKey = process.env[pending.publishableKeyFieldReference]?.trim() ?? "";
+    if (!publishableKey)
+        return;
+    try {
+        resolveIdentityDeployment({
+            MESSAGE_BOARD_ENROLL_BOARD_URL: pending.staticMcpEnvironment.AGENT_BOARD_URL,
+            MESSAGE_BOARD_ENROLL_SESSION_URL: pending.staticMcpEnvironment.AGENT_BOARD_SESSION_URL,
+            MESSAGE_BOARD_ENROLL_PUBLISHABLE_KEY: publishableKey,
+        });
+    }
+    catch {
+        throw new FleetSafeMessageError("identity_secret_value", "a value this fleet enrollment would write into the harness's identity file (the board URL, the session URL "
+            + "or the publishable key) is not the non-secret shape that file requires; an identity file carries public "
+            + "values only. The value is not echoed. Nothing was sent.");
+    }
+}
 async function finalizeFleetOutcome(options, intent, result, frozenPending) {
     if (intent.kind !== "fleet_onboarding")
         return result;
@@ -2106,6 +2175,14 @@ async function finalizeFleetOutcomeInner(options, intent, result, frozenPending)
     // Shaped (and therefore content-checked) BEFORE anything is written to disk.
     const enrollment = fleetSafeOutput(outcome);
     const published = await publishFinalizedFleetTemplate(options.runtimeOutput, finalized);
+    // CREDPATH SL-6 — the declared `identityEnvPath`, written. Its host was matched against this
+    // process's environment by `fleetIdentityFilePreflight`, in this same process: `run` built
+    // `pending` above the commit, and a device resume builds its candidate template (compared
+    // equal to the stored one) before `deviceComplete`, so a resume from another host is refused
+    // there.
+    if (isIdentityHarness(pending.harnessKind)) {
+        await writeIdentityFile(pending.harnessKind, finalized.runtimeEnv, process.env);
+    }
     return { enrollment, materialization: { generation: published.generation, digest: published.digest } };
 }
 export const FLEET_TUPLE_DISPOSITION = Object.freeze({
@@ -2361,6 +2438,64 @@ function fleetSafeOutput(result) {
     throughPresentationGate(() => assertPresentationSafe(shaped, "fleet_enrollment_output"));
     return shaped;
 }
+/**
+ * The filesystem as `writeIdentityFile` will leave it: every component that exists is read for
+ * real, and every one that does not is the 0700, caller-owned directory the writer creates
+ * there. So the reader's own trusted walk (`walkTrustedDirectory`), run over this BEFORE the
+ * commit, refuses exactly what the writer's walk would refuse after it — a group-writable
+ * ~/.config, a foreign owner, a symlink, a non-private `agent-board/` — while the token is
+ * still unspent. Only ENOENT is planned over; anything else is the real answer.
+ */
+const PLANNED_IDENTITY_DIRECTORY_FS = {
+    lstatSync(path) {
+        try {
+            return nodeFs.lstatSync(path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return { uid: process.getuid?.() ?? -1, gid: process.getgid?.() ?? -1, mode: nodeFs.constants.S_IFDIR | 0o700,
+                dev: 0, ino: 0, size: 0, isSymbolicLink: () => false, isDirectory: () => true, isFile: () => false };
+        }
+    },
+    readlinkSync: (path) => nodeFs.readlinkSync(path),
+    openSync: (path, flags) => nodeFs.openSync(path, flags),
+    fstatSync: (fd) => nodeFs.fstatSync(fd),
+    readSync: (fd, buffer, offset, length, position) => nodeFs.readSync(fd, buffer, offset, length, position),
+    closeSync: (fd) => nodeFs.closeSync(fd),
+};
+/** `identityFilePath`'s refusals, then the directory walk the writer will make, both pre-commit. */
+function identityDirectoryPreflight(harness) {
+    const path = identityFilePath(harness, process.env);
+    walkTrustedDirectory(dirname(path), join(identityConfigRoot(process.env), "agent-board"), { fs: PLANNED_IDENTITY_DIRECTORY_FS });
+}
+const HARNESS_OPTION_DESCRIPTION = "write this harness's identity file (agy, claude, codex, grok, opencode, pi) after enrolling";
+function identityFilePreflight(options) {
+    if (options.harness === undefined)
+        return null;
+    if (options.fleetOnboarding) {
+        throw new FleetPreflightError("enroll_harness_with_fleet", "--harness is for a plain enrollment; a fleet enrollment names its harness with --harness-kind. Nothing was sent.");
+    }
+    identityDirectoryPreflight(options.harness);
+    return { harness: options.harness, deployment: resolveIdentityDeployment(process.env) };
+}
+const IDENTITY_WRITE_CAUSE = /^[a-z0-9_]{1,80}$|^E[A-Z]{2,20}$/;
+async function writeEnrolledIdentityFile(plan, result) {
+    if (plan === null)
+        return result;
+    const outcome = result;
+    try {
+        const path = await writeIdentityFile(plan.harness, identityValuesFromEnrollment(outcome, plan.deployment), process.env);
+        return { ...result, identityFile: path };
+    }
+    catch (error) {
+        const raw = error?.code;
+        const cause = typeof raw === "string" && IDENTITY_WRITE_CAUSE.test(raw) ? raw : "unknown";
+        throw new CredentialResolutionError("identity_write_failed_after_commit", `enrollment COMMITTED on the server (agentHandle=${outcome.agentHandle}); only writing the ${plan.harness} `
+            + `identity file failed (${cause}). Do NOT re-run the enrollment: its token is spent. Fix the cause and write `
+            + "the file from this enrollment's values, or revoke the agent's key before enrolling again.");
+    }
+}
 function addFleetOptions(command) {
     return command
         .option("--fleet-onboarding", "atomically enroll and bind the creator-authorized fleet tuple")
@@ -2404,7 +2539,8 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
-        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)");
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
+        .option("--harness <harness>", HARNESS_OPTION_DESCRIPTION);
     addFleetOptions(runCommand)
         .action((options) => runHandler(io, "agent_board.enroll", async () => {
         // The non-fleet half of what `requiredOption` used to do. The fleet half is the
@@ -2413,6 +2549,7 @@ function addEnrollCommands(program, io, enrollment) {
         if (!options.fleetOnboarding && !String(options.slug ?? "").trim()) {
             throw new FleetPreflightError("enroll_run_slug_required", "enroll run requires --slug");
         }
+        const identityPlan = identityFilePreflight(options);
         // ORDER IS THE CONTRACT on this path (#254). The intent is built and the whole
         // pending template is constructed BEFORE the filesystem is touched and before the
         // server is asked to commit anything — which is the order `enroll device` (begin
@@ -2432,8 +2569,9 @@ function addEnrollCommands(program, io, enrollment) {
             requestedScopes: csv(options.requestedScopes),
             requestedBoardScopes: csv(options.requestedBoardScopes),
         });
-        if (intent.kind !== "fleet_onboarding")
-            return finalizeFleetOutcome(options, intent, await call());
+        if (intent.kind !== "fleet_onboarding") {
+            return writeEnrolledIdentityFile(identityPlan, await finalizeFleetOutcome(options, intent, await call()));
+        }
         const pending = throughPresentationGate(() => buildPendingFleetTemplate(intent, options.publishableKeyFieldReference));
         // BOTH local prerequisites of fleet finalization, checked before the server is
         // asked to commit anything. The publishable key used to be read only inside
@@ -2481,6 +2619,7 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--code <code>", "the authorization code (prefer stdin; argv leaks via /proc/<pid>/cmdline)")
         .option("--redirect-response <url>", "the full redirect response URL")
         .option("--slug <slug>", "override the agent slug")
+        .option("--harness <harness>", HARNESS_OPTION_DESCRIPTION)
         .action(async (options) => {
         // A5: keep the auth code off argv where practical. When neither --code nor
         // --redirect-response is supplied and stdin is piped, read the code from stdin.
@@ -2488,12 +2627,16 @@ function addEnrollCommands(program, io, enrollment) {
         if (!code && !options.redirectResponse) {
             code = await readCodeFromStdin();
         }
-        return runHandler(io, "agent_board.complete_enrollment", () => enrollment.complete({
-            enrollmentId: options.enrollmentId,
-            code,
-            redirectResponse: options.redirectResponse,
-            slug: options.slug,
-        }));
+        return runHandler(io, "agent_board.complete_enrollment", async () => {
+            // `complete` is where begin/complete commits, so the preflight sits here, not in `begin`.
+            const identityPlan = identityFilePreflight(options);
+            return writeEnrolledIdentityFile(identityPlan, await enrollment.complete({
+                enrollmentId: options.enrollmentId,
+                code,
+                redirectResponse: options.redirectResponse,
+                slug: options.slug,
+            }));
+        });
     });
     // RFC 8628 device authorization — the correct flow for a HEADLESS host. `run`'s
     // loopback receiver binds the SERVER's localhost (useless when the human's browser
@@ -2513,9 +2656,12 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
-        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)");
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
+        .option("--harness <harness>", HARNESS_OPTION_DESCRIPTION);
     addFleetOptions(deviceCommand)
         .action((options) => runHandler(io, "agent_board.enroll_device", async () => {
+        // Before either branch: a non-fleet resume commits in `deviceComplete` too.
+        const identityPlan = identityFilePreflight(options);
         if (options.enrollmentId) {
             if (!enrollment.deviceComplete) {
                 // #402 — a SAFE message rather than a plain `Error`. These two fire BEFORE the
@@ -2542,7 +2688,7 @@ function addEnrollCommands(program, io, enrollment) {
                 // `Boolean(options.fleetOnboarding)`. Do NOT make it outcome-keyed to match:
                 // it governs FAILURE text, and turning it on here would blank the guard's
                 // refusal message into "fleet enrollment failed before completion".
-                return fleetSafeOutput(await enrollment.deviceComplete({ enrollmentId: options.enrollmentId }));
+                return writeEnrolledIdentityFile(identityPlan, fleetSafeOutput(await enrollment.deviceComplete({ enrollmentId: options.enrollmentId })));
             }
             if (!enrollment.deviceDeletePending) {
                 throw new FleetSafeMessageError("fleet_device_resume_runner_incomplete", "fleet device resume is not supported by this runner (EnrollmentCommandRunner.deviceDeletePending is "
@@ -2713,7 +2859,7 @@ function addEnrollCommands(program, io, enrollment) {
                 // for the final JSON outcome). The device_code secret is never surfaced.
                 onDeviceAuthorization: (prompt) => io.writeStderr(renderDevicePrompt(prompt)),
             });
-            return result;
+            return writeEnrolledIdentityFile(identityPlan, result);
         });
     }, Boolean(options.fleetOnboarding)));
 }
@@ -3016,7 +3162,44 @@ function addInviteCommands(program, client, io) {
         return { result, instructions: buildAgentJoinInstructions({ invite: branded, deployment: { ...instructionDeployment, fleetHarnessTemplate: instructionTemplate, fleetOnboardingInvite: branded } }) };
     }));
 }
-export function createProgram(client, io, enrollment = defaultEnrollmentRunner()) {
+/**
+ * CREDPATH IF-0-CREDPATH-4 — top-level `agent-board doctor --harness <h> [--json]`. Distinct
+ * from `runtime doctor` (the runtime-discovery diagnostics), which it does not replace. The
+ * process exits with the report's own code: 0 every check passed, 1 one failed, 2 one could
+ * not be determined. A refused `--harness` is a usage error (1); doctor itself throwing is 2,
+ * because nothing was judged.
+ */
+function addDoctorCommand(program, io, doctor) {
+    program
+        .command("doctor")
+        .description("check one harness's identity file, keystore key, board access, registration and live wake runtime")
+        // Not `requiredOption`: commander's own usage exit would bypass the JSON envelope (#402).
+        .option("--harness <harness>", "the harness to check (agy, claude, codex, grok, opencode, pi)")
+        .option("--json", "print the report as JSON")
+        .action(async (options) => {
+        const harness = String(options.harness ?? "");
+        let report;
+        try {
+            assertIdentityHarness(harness);
+        }
+        catch (error) {
+            writeFailureEnvelope(io, toOperationFailure("agent_board.doctor", error));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            report = await doctor({ harness });
+        }
+        catch (error) {
+            writeFailureEnvelope(io, toOperationFailure("agent_board.doctor", error));
+            process.exitCode = 2;
+            return;
+        }
+        io.writeStdout(options.json ? `${JSON.stringify(report, null, 2)}\n` : `${formatDoctorReport(report)}\n`);
+        process.exitCode = report.exit;
+    });
+}
+export function createProgram(client, io, enrollment = defaultEnrollmentRunner(), doctor = runDoctor) {
     const program = new Command()
         .name("agent-board")
         .description("Thin CLI surface for the agent_board RPC and canonical read contracts")
@@ -3040,12 +3223,13 @@ export function createProgram(client, io, enrollment = defaultEnrollmentRunner()
     addRoomsCommands(program, client, io);
     addInviteCommands(program, client, io);
     addEnrollCommands(program, io, enrollment);
+    addDoctorCommand(program, io, doctor);
     return program;
 }
 export async function runCli(argv, io = {
     writeStdout: (message) => process.stdout.write(message),
     writeStderr: (message) => process.stderr.write(message),
-}, client = createAgentBoardClient(), enrollment = defaultEnrollmentRunner()) {
-    const program = createProgram(client, io, enrollment);
+}, client = createAgentBoardClient(), enrollment = defaultEnrollmentRunner(), doctor = runDoctor) {
+    const program = createProgram(client, io, enrollment, doctor);
     await program.parseAsync(argv, { from: "user" });
 }

package/dist/doctor.d.ts

@@ -0,0 +1,104 @@
+import { type IdentityHarness, type OperationSuccess, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
+import { type RegistrationFs } from "./doctor_scopes.js";
+export type DoctorStatus = "pass" | "fail" | "undetermined";
+export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime"];
+export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number];
+export interface DoctorCheck {
+    status: DoctorStatus;
+    reason: string;
+}
+export interface DoctorReport {
+    harness: IdentityHarness;
+    exit: 0 | 1 | 2;
+    checks: Record<DoctorCheckName, DoctorCheck>;
+}
+/**
+ * The two reads doctor makes, on a client whose credentials come from the identity file. Typed
+ * as the client's own `OperationSuccess` envelope, so `defaultClient` below stops compiling if
+ * the rows move out of `data`.
+ */
+type RowsEnvelope = Pick<OperationSuccess<ReadonlyArray<Record<string, unknown>>>, "data">;
+export interface DoctorClient {
+    whoami(input: Record<string, never>): Promise<RowsEnvelope>;
+    boardMemberships(query: {
+        agentId: string;
+        limit?: number;
+    }): Promise<RowsEnvelope>;
+}
+export type KeystoreProbeResult = {
+    kind: "found";
+    fingerprint: string;
+}
+/** The key signed, but its fingerprint was not derivable here; `whoami` proves it server-side. */
+ | {
+    kind: "present_unverified";
+} | {
+    kind: "absent";
+    reason: string;
+} | {
+    kind: "unreachable";
+    reason: string;
+};
+/** Find the key a reference names; a fingerprint, when reported, is derived from the key, never echoed from the reference. */
+export type KeystoreProbe = (keyReference: string, expectedFingerprint: string, env: NodeJS.ProcessEnv) => Promise<KeystoreProbeResult>;
+export interface DoctorOptions {
+    harness: string;
+    /** Path inputs only (HOME, XDG_*, host id, harness config dirs). Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Default `process.cwd()`. */
+    cwd?: string;
+    trust?: TrustOptions;
+    isAlive?: (pid: number, processStartedAt: string | null) => boolean;
+    createClient?: (fileEnv: NodeJS.ProcessEnv) => DoctorClient;
+    probeKeystore?: KeystoreProbe;
+    registrationFs?: RegistrationFs;
+    /** Claude Code's managed directory. Default `/etc/claude-code`. */
+    claudeManagedDir?: string;
+}
+/**
+ * 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 declare function authoredCode(error: unknown, fallback: string): string;
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * 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 declare function isKeystoreUnreachable(error: unknown): boolean;
+/** The ambient env minus every identity and generic name, plus the file: the file is the identity. */
+export declare function fileIdentityEnv(ambient: NodeJS.ProcessEnv, values: Record<string, string>): NodeJS.ProcessEnv;
+/**
+ * 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 declare function osKeychainProbe(spawn?: OsKeychainExec): KeystoreProbe;
+/** The default agent_socket probe: the loaded key's fingerprint, derived from the agent's identity list. */
+export declare const agentSocketProbe: KeystoreProbe;
+export declare const OS_KEYCHAIN_PRESENT = "present; key_id proven server-side by whoami; file fingerprint unverified for os_keychain";
+interface FileIdentity {
+    handle: string;
+    fingerprint: string;
+}
+/** IF-0-CREDPATH-4 runtime, over already-read records. Exported for its fixtures. */
+export declare function judgeRuntime(harness: IdentityHarness, entries: readonly SessionRecordEntry[], identity: FileIdentity | null): DoctorCheck;
+export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+/** Human-readable form; `--json` prints the report object itself. */
+export declare function formatDoctorReport(report: DoctorReport): string;
+export {};