@synap-core/cli 1.11.0 → 1.12.2

package/dist/lib/key-approval.js

@@ -0,0 +1,117 @@
+/**
+ * Waiting for a pending agent key to be approved — and resuming that wait.
+ *
+ * Two rules, both learnt from the 2026-10-12 incident:
+ *
+ *  1. The wait asks about the PENDING key, presenting the pending key itself
+ *     (`/auth/key-state`). The old poll authenticated with the person's own
+ *     key — which, mid-incident, was the very key the approval had just
+ *     revoked, so the poll could never see the approval land.
+ *  2. A request is never filed twice. A minted-but-unapproved key is recorded
+ *     (`pendingAgentKeys`); the next connect / `doctor --fix` resumes it. Three
+ *     orphaned requests accumulated in one evening before this.
+ */
+import chalk from "chalk";
+import { log } from "../utils/logger.js";
+import { fetchKeyState } from "./key-state.js";
+import { openPodPage } from "./safe-open.js";
+/** The approval did not land in time. The request stays filed and resumable. */
+export class AgentKeyAwaitingApprovalError extends Error {
+    agentType;
+    approvalUrl;
+    constructor(agentType, approvalUrl) {
+        super(`${agentType} is waiting for your approval — nothing was changed on this computer.\n` +
+            `  Approve it: ${approvalUrl}\n` +
+            `  Then finish with: synap doctor --fix`);
+        this.agentType = agentType;
+        this.approvalUrl = approvalUrl;
+        this.name = "AgentKeyAwaitingApprovalError";
+    }
+}
+/**
+ * Wait until the pod says the key is live (`approved`), refused
+ * (`rejected`: revoked / expired / unknown), or the deadline passes.
+ * Transient failures never end the wait early.
+ */
+export async function waitForKeyLive(opts) {
+    const f = opts.fetch ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    // SYNAP_APPROVAL_TIMEOUT_MS / SYNAP_APPROVAL_POLL_MS: wait longer for an
+    // approval that needs a walk to the phone (and short in tests).
+    const envMs = (name) => {
+        const n = Number(process.env[name]);
+        return Number.isFinite(n) && n > 0 ? n : undefined;
+    };
+    const interval = opts.intervalMs ?? envMs("SYNAP_APPROVAL_POLL_MS") ?? 2000;
+    const deadline = Date.now() + (opts.timeoutMs ?? envMs("SYNAP_APPROVAL_TIMEOUT_MS") ?? 120_000);
+    const base = opts.podUrl.replace(/\/+$/, "");
+    while (Date.now() < deadline) {
+        const s = await fetchKeyState(opts.podUrl, opts.pendingKey, { fetch: f });
+        if (s.state === "active")
+            return "approved";
+        if (s.state === "revoked" || s.state === "expired" || s.state === "unknown")
+            return "rejected";
+        // A current pod refusing to even describe the key (403: a guest's key) is a no.
+        if (s.state === "inactive" && !s.legacy)
+            return "rejected";
+        if (s.legacy && s.state === "inactive" && opts.pendingToken && opts.humanApiKey) {
+            // Older pod: it cannot describe the pending key — ask the pending door.
+            const res = await f(`${base}/api/hub/setup/agent/pending/${opts.pendingToken}`, {
+                headers: { Authorization: `Bearer ${opts.humanApiKey}` },
+                signal: AbortSignal.timeout(15_000),
+            }).catch(() => null);
+            const status = res?.ok ? (await res.json().catch(() => ({}))).status : undefined;
+            if (status === "active")
+                return "approved";
+            if (status === "rejected")
+                return "rejected";
+        }
+        await sleep(interval);
+    }
+    return "timeout";
+}
+/**
+ * What a recorded pending key is now: still waiting (resume it), live
+ * (approved while we were away — promote it), or dead (forget it, file anew).
+ * An unreachable pod keeps it recorded and says so (`unknown`).
+ */
+export async function classifyRecordedPending(pending, deps = {}) {
+    const state = await fetchKeyState(pending.podUrl, pending.hubApiKey, deps);
+    switch (state.state) {
+        case "awaiting_approval":
+            return { kind: "pending", state };
+        case "active":
+            return { kind: "active", state };
+        case "revoked":
+        case "expired":
+        case "unknown":
+            return { kind: "dead", state };
+        case "inactive":
+            // Older pod: inactive is either still pending or refused; resuming the
+            // wait is safe (the pending door settles it), minting another is not.
+            // A current pod refusing the key outright: keep it recorded, mint nothing.
+            return { kind: state.legacy ? "pending" : "unknown", state };
+        case "unreachable":
+            return { kind: "unknown", state };
+    }
+}
+/**
+ * Print the approval link, open it, and wait — the one interactive wait.
+ * The link came from the pod: it is opened only when it is on that pod's own
+ * origin or its pod-admin origin (`openPodPage`), never anywhere else.
+ */
+export async function openAndWait(agentType, approvalUrl, podUrl, wait, openUrl) {
+    log.info(`\n  Approve ${agentType} on your pod:`);
+    log.dim(`  ${approvalUrl}`);
+    openPodPage(approvalUrl, podUrl, openUrl);
+    process.stdout.write(chalk.dim("  Waiting for approval"));
+    const ticker = setInterval(() => process.stdout.write(chalk.dim(".")), 2000);
+    try {
+        return await wait();
+    }
+    finally {
+        clearInterval(ticker);
+        process.stdout.write("\n");
+    }
+}
+//# sourceMappingURL=key-approval.js.map

package/dist/lib/key-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-approval.js","sourceRoot":"","sources":["../../src/lib/key-approval.ts"],"names":[],"mappings":"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"}

package/dist/lib/key-diagnosis.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ONE diagnosis per key problem, from where the keys are and what the pod says
+ * about each. Pure: no IO, so every state is unit-tested.
+ *
+ * Shared by `synap doctor` (and its `--fix`) and `synap whoami`, so the two can
+ * never tell the person two different stories about the same key.
+ *
+ * Each diagnosis carries the ONE right action and the exact command, because
+ * the 2026-10-12 incident was a wrong action taken on a wrong story: a key
+ * that was only AWAITING APPROVAL was reported "revoked or expired", and every
+ * re-run of `init` / `connect` filed another request instead of finishing the
+ * first one.
+ */
+import { type KeyLocation } from "./key-locations.js";
+import type { KeyState } from "./key-state.js";
+export type DiagnosisCode = "ok" | "awaiting_approval" | "replaced_by_other_computer" | "replaced_on_this_computer" | "revoked" | "expired" | "unknown_key" | "refused" | "unverifiable" | "stale_copies" | "env_shadow" | "person_key_dead";
+/** The single thing `doctor --fix` does for a diagnosis. */
+export type FixAction = "approve_and_wait" | "reprovision" | "rewrite" | "edit_shell_rc" | "login" | "none";
+export interface Diagnosis {
+    code: DiagnosisCode;
+    severity: "ok" | "warn" | "error";
+    /** Agent surface (claude-code, codex, …); absent for the person's own key / env. */
+    surface?: string;
+    /** The surface's display name. */
+    label?: string;
+    title: string;
+    lines: string[];
+    /** The exact command that resolves it (what `--fix` runs, or what the person runs). */
+    command?: string;
+    action: FixAction;
+    /** The key the action works with: the one to approve, or the live one to copy. */
+    key?: string;
+    agentUserId?: string;
+    approvalUrl?: string;
+    /** The pod's agent type for the surface, when the pod said. */
+    agentType?: string;
+    /** The copies the diagnosis is about. */
+    locations: KeyLocation[];
+}
+export interface DiagnoseInput {
+    locations: KeyLocation[];
+    /** The pod's answer per key (by plaintext). A key with no entry reads as unreachable. */
+    states: Map<string, KeyState>;
+    /** This computer's instance label for a surface. */
+    instanceIdFor: (surface: string) => string;
+    /** `SYNAP_HUB_API_KEY` as this process sees it. */
+    envKey?: string;
+    /** A surface's display name (the CLI's target label). Default: the surface id. */
+    labelOf?: (surface: string) => string;
+    /** This computer's instance ids for a pod agentType (`thisComputerInstanceIds`). */
+    instanceIdsForAgentType?: (agentType: string) => Set<string>;
+}
+/** Why one key does not work, in one sentence. */
+export declare function describeKeyState(s: KeyState): string;
+/** Diagnose every key for one pod: the person's own key, each agent surface, the env var. */
+export declare function diagnoseKeys(input: DiagnoseInput): Diagnosis[];

package/dist/lib/key-diagnosis.js

@@ -0,0 +1,227 @@
+/**
+ * ONE diagnosis per key problem, from where the keys are and what the pod says
+ * about each. Pure: no IO, so every state is unit-tested.
+ *
+ * Shared by `synap doctor` (and its `--fix`) and `synap whoami`, so the two can
+ * never tell the person two different stories about the same key.
+ *
+ * Each diagnosis carries the ONE right action and the exact command, because
+ * the 2026-10-12 incident was a wrong action taken on a wrong story: a key
+ * that was only AWAITING APPROVAL was reported "revoked or expired", and every
+ * re-run of `init` / `connect` filed another request instead of finishing the
+ * first one.
+ */
+import { envKeySetBy } from "./key-locations.js";
+const day = (iso) => (iso ? iso.replace("T", " ").slice(0, 16) + " UTC" : "an unknown time");
+function stateOf(input, key) {
+    return input.states.get(key) ?? { state: "unreachable", error: "not asked" };
+}
+/** Why one key does not work, in one sentence. */
+export function describeKeyState(s) {
+    switch (s.state) {
+        case "active":
+            return "works";
+        case "awaiting_approval":
+            return "is waiting for your approval (it was never revoked)";
+        case "revoked":
+            return s.replacedBy
+                ? `was replaced on ${day(s.revokedAt)} by a connection created ${day(s.replacedBy.createdAt)}${s.replacedBy.instanceLabel ? ` on ${s.replacedBy.instanceLabel}` : ""}`
+                : `was revoked on ${day(s.revokedAt)}${s.revokedReason ? ` (${s.revokedReason})` : ""}`;
+        case "expired":
+            return `expired${s.expiresAt ? ` on ${day(s.expiresAt)}` : ""}`;
+        case "unknown":
+            return "is not a key this pod issued";
+        case "inactive":
+            return s.legacy ? "is refused, and this pod is too old to say why" : `is refused by this pod${s.error ? ` (${s.error})` : ""}`;
+        case "unreachable":
+            return `could not be checked (${s.error ?? "pod unreachable"})`;
+    }
+}
+const tail = (k) => (k.length <= 8 ? "…" : `…${k.slice(-6)}`);
+function agentDiagnosis(input, surface, group) {
+    const label = (input.labelOf ?? ((x) => x))(surface);
+    const copies = group.filter((l) => l.kind !== "pending");
+    const keys = [...new Set(group.map((l) => l.key))];
+    const live = keys.filter((k) => stateOf(input, k).state === "active");
+    const primaryLoc = group.find((l) => l.kind === "agent-key-by-pod") ?? copies[0] ?? group[0];
+    const agentUserIdOf = (k) => group.find((l) => l.key === k && l.agentUserId)?.agentUserId;
+    if (live.length > 0) {
+        const liveKey = live.includes(primaryLoc.key) ? primaryLoc.key : live[0];
+        const stale = copies.filter((l) => l.key !== liveKey);
+        if (stale.length === 0)
+            return { code: "ok", severity: "ok", surface, label, title: `${label}: key works`, lines: [], action: "none", key: liveKey, locations: copies };
+        return {
+            code: "stale_copies",
+            severity: "warn",
+            surface,
+            label,
+            title: `${label}: ${stale.length} cop${stale.length === 1 ? "y holds" : "ies hold"} an old key`,
+            lines: [
+                `The working key (${tail(liveKey)}) is in ${copies.filter((l) => l.key === liveKey).map((l) => l.label).join(", ")}.`,
+                ...stale.map((l) => `${l.label} has ${tail(l.key)}, which ${describeKeyState(stateOf(input, l.key))}.`),
+            ],
+            command: "synap doctor --fix",
+            action: "rewrite",
+            key: liveKey,
+            agentUserId: agentUserIdOf(liveKey),
+            locations: stale,
+        };
+    }
+    // Nothing works. A request waiting for approval is the whole story: finish it.
+    const awaiting = keys.filter((k) => stateOf(input, k).state === "awaiting_approval");
+    if (awaiting.length > 0) {
+        const recorded = group.find((l) => l.kind === "pending" && awaiting.includes(l.key))?.key;
+        const newest = [...awaiting].sort((a, b) => String(stateOf(input, b).createdAt ?? "").localeCompare(String(stateOf(input, a).createdAt ?? "")))[0];
+        const key = recorded ?? newest;
+        const s = stateOf(input, key);
+        const holding = copies.filter((l) => l.key === key).map((l) => l.label);
+        const lines = [
+            `Key ${tail(key)} was filed${s.createdAt ? ` on ${day(s.createdAt)}` : ""} and nobody approved it yet — it was never revoked.`,
+            ...(holding.length ? [`It is already written into ${holding.join(", ")}, which is why every call says "Invalid or expired API key".`] : []),
+            ...(awaiting.length > 1 ? [`${awaiting.length - 1} other unapproved request${awaiting.length > 2 ? "s" : ""} for ${label} ${awaiting.length > 2 ? "are" : "is"} left over; approving this one is enough.`] : []),
+            `Approve it: ${s.approvalUrl ?? "(open your pod's agent approvals)"}`,
+        ];
+        return {
+            code: "awaiting_approval",
+            severity: "error",
+            surface,
+            label,
+            title: `${label} is waiting for your approval`,
+            lines,
+            command: "synap doctor --fix   (opens the link, waits, then writes the key)",
+            action: "approve_and_wait",
+            key,
+            agentUserId: agentUserIdOf(key),
+            approvalUrl: s.approvalUrl,
+            agentType: s.agentType ?? undefined,
+            locations: copies,
+        };
+    }
+    // Every copy is dead. Explain the primary one.
+    const s = stateOf(input, primaryLoc.key);
+    const base = { surface, label, locations: copies, agentType: s.agentType ?? undefined, command: "synap doctor --fix   (asks the pod for a key for THIS computer, waits for your approval, then writes it everywhere)" };
+    const where = copies.map((l) => l.label);
+    if (s.state === "revoked" && s.replacedBy !== undefined) {
+        const mine = input.instanceIdFor(surface);
+        const otherInstance = s.replacedBy?.instanceId ?? null;
+        if (otherInstance && otherInstance === mine)
+            return {
+                ...base,
+                code: "replaced_on_this_computer",
+                severity: "error",
+                title: `${label}: a newer key from this computer replaced it, and was never saved here`,
+                lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)} on THIS computer.`, `Stale copies: ${where.join(", ")}.`],
+                action: "reprovision",
+            };
+        return {
+            ...base,
+            code: "replaced_by_other_computer",
+            severity: "error",
+            title: `${label}: another computer's connection replaced this computer's key`,
+            lines: [
+                `Key ${tail(primaryLoc.key)} ${describeKeyState(s)}.`,
+                otherInstance
+                    ? `That connection belongs to another computer (${s.replacedBy?.instanceLabel ?? otherInstance}); approving it switched off every other ${label} key that shared its slot.`
+                    : `That connection carried no computer label (made by an older CLI), so approving it switched off EVERY ${label} key — this computer's included.`,
+                `Give this computer its own connection: keys made now carry this computer's label (${input.instanceIdFor(surface)}), so approving one never switches another computer off.`,
+            ],
+            action: "reprovision",
+        };
+    }
+    if (s.state === "revoked")
+        return { ...base, code: "revoked", severity: "error", title: `${label}: key was revoked`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)}.`, `Copies: ${where.join(", ")}.`], action: "reprovision" };
+    if (s.state === "expired")
+        return { ...base, code: "expired", severity: "error", title: `${label}: key expired`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)}.`, `Copies: ${where.join(", ")}.`], action: "reprovision" };
+    if (s.state === "unknown")
+        return { ...base, code: "unknown_key", severity: "error", title: `${label}: this pod does not know the key`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)} — it was made for another pod, or deleted.`, `Copies: ${where.join(", ")}.`], action: "reprovision" };
+    if (s.state === "inactive") {
+        const recorded = group.find((l) => l.kind === "pending");
+        return recorded
+            ? { ...base, code: "refused", severity: "error", title: `${label}: key is refused (older pod — likely still awaiting approval)`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)}.`, "A request from this computer is recorded; finishing it is safer than filing another."], action: "approve_and_wait", key: recorded.key, agentUserId: recorded.agentUserId, command: "synap doctor --fix" }
+            : { ...base, code: "refused", severity: "error", title: `${label}: key is refused`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)} (awaiting approval or revoked).`, `Copies: ${where.join(", ")}.`], action: "reprovision" };
+    }
+    return { ...base, key: primaryLoc.key, code: "unverifiable", severity: "warn", title: `${label}: could not check the key`, lines: [`Key ${tail(primaryLoc.key)} ${describeKeyState(s)}.`], action: "none", command: "synap doctor   (again, once the pod answers)" };
+}
+/**
+ * Why the person's key was switched off by a replacing connection. "This
+ * computer" is decided only when the pod named the key's agentType: keys are
+ * minted with the SURFACE's hash (`thisComputerInstanceIds`), and hashing ""
+ * for a missing type would call every connection "another computer".
+ */
+function personKeyReplacedLine(input, s) {
+    const other = s.replacedBy?.instanceId ?? null;
+    const name = s.replacedBy?.instanceLabel ?? other;
+    if (!other)
+        return "It was an agent key: approving a connection with no computer label switched off every key of that agent, this one included.";
+    if (!s.agentType)
+        return `It was an agent key: approving another connection (${name}) switched it off.`;
+    const mine = (input.instanceIdsForAgentType ?? ((t) => new Set([input.instanceIdFor(t)])))(s.agentType);
+    return mine.has(other)
+        ? "It was an agent key: a newer connection from THIS computer replaced it."
+        : `It was an agent key: approving another computer's connection (${name}) switched it off.`;
+}
+/** Diagnose every key for one pod: the person's own key, each agent surface, the env var. */
+export function diagnoseKeys(input) {
+    const out = [];
+    // 1. The person's / this computer's own CLI key (pod profile).
+    for (const loc of input.locations.filter((l) => l.kind === "profile")) {
+        const s = stateOf(input, loc.key);
+        if (s.state === "active" || s.state === "unreachable")
+            continue;
+        out.push({
+            code: "person_key_dead",
+            severity: "error",
+            title: `Your CLI key for this pod ${describeKeyState(s)}`,
+            lines: [
+                `${loc.label} holds ${tail(loc.key)}. Agent keys cannot be re-made without it.`,
+                ...(s.state === "revoked" && s.replacedBy !== undefined ? [personKeyReplacedLine(input, s)] : []),
+            ],
+            command: `synap login --reconnect${loc.ref ? ` ${loc.ref}` : ""}`,
+            action: "login",
+            locations: [loc],
+        });
+    }
+    // 2. One diagnosis per agent surface.
+    const bySurface = new Map();
+    for (const l of input.locations) {
+        if (l.role !== "agent" || !l.surface)
+            continue;
+        bySurface.set(l.surface, [...(bySurface.get(l.surface) ?? []), l]);
+    }
+    const surfaceDiags = new Map();
+    for (const [surface, group] of bySurface) {
+        const d = agentDiagnosis(input, surface, group);
+        surfaceDiags.set(surface, d);
+        out.push(d);
+    }
+    // 3. The ambient SYNAP_HUB_API_KEY beats the CLI profile — name who sets it
+    //    when it is not the working key it is meant to be.
+    if (input.envKey) {
+        const envState = stateOf(input, input.envKey);
+        const setBy = envKeySetBy(input.locations, input.envKey);
+        const liveAgentKeys = [...surfaceDiags.values()].filter((d) => d.code === "ok" || d.code === "stale_copies").map((d) => d.key);
+        const profileKeys = input.locations.filter((l) => l.kind === "profile").map((l) => l.key);
+        const designed = envState.state === "active" && (liveAgentKeys.includes(input.envKey) || profileKeys.includes(input.envKey));
+        if (!designed) {
+            const shell = setBy.filter((l) => l.kind === "shell-rc");
+            const fixedWithSurface = setBy.some((l) => l.kind === "claude-settings-env") && shell.length === 0;
+            const who = setBy.length ? setBy.map((l) => l.label).join(" and ") : "something outside the files the doctor reads (your terminal or launcher)";
+            out.push({
+                code: "env_shadow",
+                severity: envState.state === "active" ? "warn" : "error",
+                title: `SYNAP_HUB_API_KEY overrides your CLI profile key${envState.state === "active" ? "" : " — and it does not work"}`,
+                lines: [
+                    `It is set by ${who}.`,
+                    `Its key ${tail(input.envKey)} ${describeKeyState(envState)}; every command run with it set uses it instead of ${profileKeys.length ? "the profile key" : "any profile"}.`,
+                    ...(shell.length ? [`Edit ${shell.map((l) => l.label).join(", ")}: remove that line, or set it to the working key, then open a new shell.`] : []),
+                    ...(fixedWithSurface ? ["`synap doctor --fix` rewrites it together with the Claude Code key; restart Claude Code afterwards."] : []),
+                ],
+                command: shell.length ? `edit ${shell[0].label}` : fixedWithSurface ? "synap doctor --fix" : "unset SYNAP_HUB_API_KEY",
+                action: shell.length ? "edit_shell_rc" : "none",
+                locations: setBy,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=key-diagnosis.js.map

package/dist/lib/key-diagnosis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-diagnosis.js","sourceRoot":"","sources":["../../src/lib/key-diagnosis.ts"],"names":[],"mappings":"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"}

package/dist/lib/key-doctor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Key health for one pod: read every copy, ask the pod about each key, print
+ * one diagnosis per problem — and, with `--fix`, do the one right thing.
+ *
+ * The fix never writes a key the pod has not confirmed live (`assertKeyWritable`),
+ * and it ends with a real MCP `initialize` against `/mcp` using the key it
+ * wrote: a fix is only reported ✓ when that call succeeds AND every copy it had
+ * to rewrite was rewritten.
+ *
+ * A key is sent to this pod only when something ties it to this pod
+ * (`keysToProbe`); keys are asked about ONE AT A TIME. The pod resolves a key it
+ * does not know with a bcrypt scan of every key sharing its prefix (~12s on a
+ * 4-thread pool, measured 2026-10-12); asked all at once, four unknown keys
+ * starved each other past the timeout and read "no answer".
+ */
+import { type ClientKeyFile, type KeyLocation, type UncheckedLocation } from "./key-locations.js";
+import { type Diagnosis } from "./key-diagnosis.js";
+import { type FetchLike, type KeyState } from "./key-state.js";
+/** Per-key wait for `/auth/key-state` — an unknown key costs the pod ~12s of bcrypt. */
+export declare const KEY_STATE_TIMEOUT_MS = 30000;
+export interface KeyHealthReport {
+    podUrl: string;
+    locations: KeyLocation[];
+    states: Map<string, KeyState>;
+    diagnoses: Diagnosis[];
+    /** True when the pod answered the holder door for at least one key (vs an older pod). */
+    podDescribesKeys: boolean;
+    /** Files the doctor could not read or parse — "not checked", never ✓. */
+    unchecked?: UncheckedLocation[];
+    /** Copies whose key nothing ties to this pod: listed, never sent to it. */
+    notSent?: KeyLocation[];
+}
+export interface KeyHealthDeps {
+    home?: string;
+    envKey?: string;
+    envPodUrl?: string;
+    fetch?: FetchLike;
+    instanceIdFor?: (surface: string) => string;
+    labelOf?: (surface: string) => string;
+    /** Client config files to read. Default: derived from `TARGETS` (`clientKeyFiles`). */
+    clients?: ClientKeyFile[];
+    timeoutMs?: number;
+    /**
+     * Only this agent surface: its copies are read and its keys asked about —
+     * not the person's key, the env, or another agent's (`confirmSurfaceKey`).
+     */
+    surface?: string;
+}
+export declare function checkKeyHealth(podUrl: string, deps?: KeyHealthDeps): Promise<KeyHealthReport>;
+/** The problems only — `ok` diagnoses are summarised, not listed. */
+export declare function keyProblems(report: KeyHealthReport): Diagnosis[];
+/** A problem `--fix` can act on (not merely tell you a command). */
+export declare function isFixable(d: Diagnosis): boolean;
+/**
+ * What setup may say about one agent after writing its config:
+ *   active      — the pod confirms the key now in its files works
+ *   not-active  — the pod (or the files) SAID it does not: pending, revoked,
+ *                 expired, unknown, stale copies, no key where setup writes it —
+ *                 as the doctor's own diagnosis line + command
+ *   unconfirmed — the check itself FAILED (pod unreachable, file unreadable,
+ *                 read threw). Not a dead key — the doctor prints it "?"
+ *   unchecked   — the target keeps no key the CLI can read back (`keyStore.none`)
+ */
+export type SetupCheck = {
+    verdict: "active";
+} | {
+    verdict: "not-active";
+    title: string;
+    command?: string;
+} | {
+    verdict: "unconfirmed";
+    reason: string;
+} | {
+    verdict: "unchecked";
+    reason: string;
+};
+/**
+ * The check behind every "<Agent> connected" line: read back what setup WROTE
+ * for `surface` — the same copies `synap doctor` reads — ask the pod about each
+ * key, and pass only when the doctor would say "key works". The 2026-10-15
+ * devbox printed "✓ Claude Code connected" over a key the pod held as
+ * awaiting approval; a success line now comes from this read, never from
+ * having written the file.
+ */
+export declare function confirmSurfaceKey(podUrl: string, surface: string, deps?: KeyHealthDeps): Promise<SetupCheck>;
+/**
+ * Print what is wrong, and what could not be checked. Working keys are one
+ * line (listed with `verbose`); an unverifiable key is "?", never ✓ or ✗.
+ */
+export declare function printKeyHealth(report: KeyHealthReport, opts?: {
+    fixHint?: boolean;
+    verbose?: boolean;
+    showOk?: boolean;
+    indent?: string;
+}): void;
+export interface RewriteResult {
+    /** Every copy that now holds the live key (rewritten or already there). */
+    done: string[];
+    /** Copies that should hold it and could not be rewritten — with why. */
+    failed: string[];
+}
+/**
+ * Write `key` into every rewritable copy of `surface` for this pod — ONLY after
+ * the pod confirms it is live. A copy that cannot be rewritten is reported in
+ * `failed`, never dropped.
+ */
+export declare function rewriteSurfaceKey(report: KeyHealthReport, surface: string, key: string, agentUserId: string | undefined, deps?: {
+    fetch?: FetchLike;
+    home?: string;
+}): Promise<RewriteResult>;
+export interface FixDeps {
+    fetch?: FetchLike;
+    openUrl?: (url: string) => void;
+    /** Wait for a pending key (default `waitForKeyLive`). */
+    wait?: (args: {
+        podUrl: string;
+        pendingKey: string;
+    }) => Promise<"approved" | "rejected" | "timeout">;
+    /** Make a new key for this computer (default `provisionAgentKey`, which waits for approval). */
+    provision?: (podUrl: string, mintingKey: string, agentType: string, surface: string) => Promise<{
+        hubApiKey: string;
+        agentUserId: string;
+    }>;
+    verify?: (podUrl: string, key: string) => Promise<{
+        ok: boolean;
+        toolCount?: number;
+        error?: string;
+    }>;
+}
+export interface FixOutcome {
+    diagnosis: Diagnosis;
+    ok: boolean;
+    message: string;
+}
+/** Perform each diagnosis's one action, then verify with a real MCP initialize. */
+export declare function fixKeyHealth(report: KeyHealthReport, deps?: FixDeps): Promise<FixOutcome[]>;