@bli-cockpit/cli 0.2.72 → 0.2.74

package/dist/commands/doctor-mcp.js

@@ -0,0 +1,98 @@
+/**
+ * The `mcp-answers` check (BLI-3804): does the `bli-tower` server this machine
+ * REGISTERED actually answer?
+ *
+ * `memory-registered` (`doctor-registration.ts`) proves the registration —
+ * the entry is in `~/.claude.json` and `~/.codex/config.toml` and the bin it
+ * names is on this machine. That is a file-contents check, and it stayed green
+ * for the whole life of a server that exited 1 on startup on every machine
+ * outside the bli-cockpit repo. Nothing on a laptop ever ASKED the server a
+ * question, so nothing could tell the difference between registered and
+ * working; five QA ticks recorded "no `mcp__bli-tower__*` in this session" as
+ * a client-side mystery.
+ *
+ * This row asks. It spawns the registered server the way an agent host does
+ * and calls the cheapest read on it — `docs_list` with `limit: 1`, the same
+ * first call `packages/bli-cockpit-mcp/scripts/smoke.ts` makes — and reports
+ * what came back.
+ *
+ * The three outcomes, and why each is spelled the way it is:
+ *
+ *   ok        the door answered. The server starts, speaks the protocol, and
+ *             reaches Tower with this machine's device token.
+ *   needs_fix the server answered and the DOOR refused, in its own words. The
+ *             MCP half is alive; the refusal belongs to Tower and is named
+ *             verbatim. No fix runs from here — the row reports, and `authed`
+ *             above it already owns the pairing.
+ *   fail      nothing answered: no process, no protocol, no reply. This is the
+ *             state that hid for five ticks, so it is a `fail` rather than a
+ *             `needs_fix` — only a `fail` travels to the fleet's install-event
+ *             ledger with its reason label (`doctor-report.ts`'s `doctorEvent`
+ *             maps every other status to `ok`).
+ *
+ * `skipped` when the bin is not on this machine at all, for the same reason
+ * `memory-registered` skips: nothing to probe is not a broken machine.
+ */
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+import { fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { resolveMcpBin } from "./mcp-bin-resolve.js";
+import { probeMcpTool, resolveServerEntry } from "./mcp-stdio-probe.js";
+import { TOWER_DASHBOARD_URL_ENV, TOWER_MCP_BIN } from "./tower-mcp-contract.js";
+/** The cheapest read on the server, and the smoke's own first call. */
+export const MCP_ANSWERS_TOOL = "docs_list";
+const MCP_ANSWERS_ARGUMENTS = { limit: 1 };
+/** Where the server's JS lives behind a Windows `.cmd` shim, relative to `.bin`. */
+const WINDOWS_ENTRY_FROM_BIN = ["..", "@bli-cockpit", "mcp", "dist", "index.js"];
+export async function checkMcpAnswersState(context, deps = {}) {
+    const resolveBin = deps.resolveBin ?? resolveMcpBin;
+    const resolveEntry = deps.resolveEntry ?? resolveServerEntry;
+    const probe = deps.probe ?? probeMcpTool;
+    const bin = await resolveBin({
+        binName: TOWER_MCP_BIN,
+        env: envWithNodeRuntimeOnPath(process.env),
+        platform: process.platform,
+    });
+    if (!bin) {
+        return skipped("mcp-answers", "bin_missing", `${TOWER_MCP_BIN} is not installed beside this CLI or on PATH; nothing was asked, and the next daily run will try again`);
+    }
+    const entry = resolveEntry(bin.path, WINDOWS_ENTRY_FROM_BIN);
+    if (!entry) {
+        return skipped("mcp-answers", "server_entry_not_found", `${TOWER_MCP_BIN} is registered but its server file could not be found behind the shim; nothing was asked`);
+    }
+    const outcome = await probe({
+        entry,
+        toolName: MCP_ANSWERS_TOOL,
+        toolArguments: MCP_ANSWERS_ARGUMENTS,
+        env: probeEnv(context),
+        ...(deps.timeoutMs === undefined ? {} : { timeoutMs: deps.timeoutMs }),
+    });
+    return mcpAnswersRow(outcome);
+}
+export function mcpAnswersRow(outcome) {
+    if (outcome.status === "answered") {
+        return ok("mcp-answers", "answered", `bli-tower answered ${MCP_ANSWERS_TOOL} in ${outcome.ms} ms`);
+    }
+    if (outcome.status === "refused") {
+        return needsFix("mcp-answers", outcome.reason, `bli-tower is alive (it answered in ${outcome.ms} ms) and Tower refused ${MCP_ANSWERS_TOOL}`
+            + ` (${outcome.reason}): ${outcome.said}`);
+    }
+    return fail("mcp-answers", outcome.reason, `bli-tower is registered but did not answer ${MCP_ANSWERS_TOOL} (${outcome.reason}): ${outcome.said}.`
+        + " No agent session on this machine can reach Tower's tools until it does."
+        + " Take the newest CLI with `cockpit update` (the server ships with it), then"
+        + " re-register with `cockpit memory install`.");
+}
+/**
+ * The child gets a URL and a HOME, never a token: the server reads this
+ * machine's device token itself, from the same session file `cockpit login`
+ * wrote, which is what makes this a probe of the REAL auth path.
+ */
+function probeEnv(context) {
+    const base = { ...process.env };
+    if (context.command.homeDir) {
+        base.HOME = context.command.homeDir;
+        base.USERPROFILE = context.command.homeDir;
+    }
+    if (context.command.dashboardUrl)
+        base[TOWER_DASHBOARD_URL_ENV] = context.command.dashboardUrl;
+    return base;
+}

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
 import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
+import { checkMcpAnswersState } from "./doctor-mcp.js";
 import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
 import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, } from "./doctor-report.js";
 import { refreshSetupReceipt } from "./setup-receipt.js";
@@ -23,14 +24,8 @@ export async function runDoctorWithDeps(command, io, deps) {
         }
         const canFix = Boolean(invariant.fix) &&
             (!invariant.requiresInteractiveFix || isInteractiveDoctorFix(context));
-        if (!canFix) {
-            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
-            if (checked.hardStop)
-                break;
-            continue;
-        }
-        if (!invariant.fix) {
-            rows.push(checked.hardStop ? checked : { ...checked, status: "needs_fix" });
+        if (!canFix || !invariant.fix) {
+            rows.push(withoutAFix(checked));
             if (checked.hardStop)
                 break;
             continue;
@@ -52,6 +47,21 @@ export async function runDoctorWithDeps(command, io, deps) {
     writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
     return rows.some((row) => row.status === "fail" || row.hardStop) ? 1 : 0;
 }
+/**
+ * What a broken row looks like when nothing can repair it from here.
+ *
+ * A check that says `needs_fix` and has no fix is still `needs_fix` — the
+ * person is being told what to do. A check that says `fail` KEEPS that word
+ * (BLI-3804): it used to be quietly rewritten to `needs_fix`, which turned the
+ * run green and, because `doctor-report.ts` maps every non-`fail` row to `ok`
+ * in the install-event ledger, threw the reason label away on the way to the
+ * fleet as well. `hardStop` is untouched and still ends the walk.
+ */
+function withoutAFix(checked) {
+    if (checked.hardStop || checked.status === "fail")
+        return checked;
+    return { ...checked, status: "needs_fix" };
+}
 function doctorInvariants() {
     return [
         { id: "cli-latest", check: checkCliLatest, fix: fixCliLatest },
@@ -84,6 +94,16 @@ function doctorInvariants() {
             check: (context) => context.deps.checkMemory(context),
             fix: (context, _state) => context.deps.fixMemory(context),
         },
+        // BLI-3804. Right after the registration row, because it asks the second
+        // half of the same question: `memory-registered` proves the entry exists
+        // and names a bin, this one proves the server behind it starts, speaks the
+        // protocol and reaches Tower. Deliberately has NO fix — re-registering a
+        // server that is already registered repairs nothing, and the row names the
+        // command a person should run instead (`doctor-mcp.ts`).
+        {
+            id: "mcp-answers",
+            check: (context) => context.deps.checkMcpAnswers(context),
+        },
         {
             id: "backfill-complete",
             check: (context) => context.deps.checkBackfill(context),
@@ -125,6 +145,7 @@ function defaultDoctorDeps(hooks) {
         fixAutostart: fixAutostartState,
         checkMemory: checkMemoryState,
         fixMemory: fixMemoryState,
+        checkMcpAnswers: (context) => checkMcpAnswersState(context),
         checkBackfill: checkBackfillState,
         fixBackfill: fixBackfillState,
         checkGc: checkGcState,

package/dist/commands/mcp-stdio-probe.js

@@ -0,0 +1,267 @@
+/**
+ * Ask an MCP server one question over stdio and see whether it answers
+ * (BLI-3804).
+ *
+ * `cockpit doctor`'s `memory-registered` row proves a server is REGISTERED —
+ * that the entry exists in `~/.claude.json` and `~/.codex/config.toml` and
+ * points at a bin that is on this machine. It cannot prove the server starts,
+ * speaks the protocol, or reaches Tower, and for five QA ticks
+ * (`docs/reports/jarvis-qa-loop/tick15.md` … `tick19.md`) nothing else did
+ * either: the `bli-tower` tools were shipped, published, and never executed
+ * end to end. This module is the missing half — it spawns the server the way
+ * an agent host does and calls one cheap read.
+ *
+ * ## Why a hand-written client
+ *
+ * MCP's stdio transport is newline-delimited JSON-RPC 2.0 and nothing more:
+ * `initialize`, `notifications/initialized`, `tools/call`. Writing those three
+ * messages costs ~60 lines here, against pulling
+ * `@modelcontextprotocol/sdk` into the collector — the package every intern
+ * machine installs — for one diagnostic. The collector already declines a
+ * dependency for exactly this reason in `agent-door-session.ts`'s sibling on
+ * the MCP side.
+ *
+ * ## Never a shell
+ *
+ * The registered bin is an npm shim: a symlink to the server's own JS on
+ * POSIX, a `.cmd` on Windows. This module spawns `process.execPath` with the
+ * server's JS ENTRY — resolved from the shim, never run through it — so no
+ * `cmd.exe`, no quoting hazard, and the same code path on both required host
+ * families (`commands/editor.ts` refuses a Windows shim for the same reason).
+ * When the entry cannot be found behind the shim the probe says so by name
+ * rather than guessing.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+const DEFAULT_TIMEOUT_MS = 25_000;
+/**
+ * The server's JS entry behind an npm bin shim.
+ *
+ * POSIX: `node_modules/.bin/<name>` is a symlink to the file itself, so one
+ * realpath is the whole answer. Windows: the shim is a `.cmd` and the entry
+ * lives at `<.bin>/../<scope>/<pkg>/dist/index.js`, which the caller names.
+ */
+export function resolveServerEntry(binPath, windowsFallbackRelative, deps = {}) {
+    const realpath = deps.realpath ?? defaultRealpath;
+    const exists = deps.exists ?? defaultExists;
+    const resolved = realpath(binPath);
+    if (resolved.endsWith(".js") || resolved.endsWith(".mjs"))
+        return resolved;
+    const beside = path.resolve(path.dirname(binPath), ...windowsFallbackRelative);
+    return exists(beside) ? beside : null;
+}
+/** One `initialize` + one `tools/call`, then the child is killed. */
+export async function probeMcpTool(request) {
+    const now = request.now ?? Date.now;
+    const started = now();
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const spawnProcess = request.spawnProcess ?? defaultSpawn;
+    const elapsed = () => now() - started;
+    let child;
+    try {
+        child = spawnProcess(process.execPath, [request.entry], { env: request.env });
+    }
+    catch (error) {
+        return { status: "no_answer", ms: elapsed(), reason: "spawn_failed", said: firstLine(errorText(error)) };
+    }
+    const pending = new Map();
+    /**
+     * A reply that arrived before anyone asked for it. Nothing in the protocol
+     * forbids it and a stream can deliver one synchronously with the write that
+     * provoked it, so the answer is held rather than dropped — a dropped reply
+     * would read as a silent server, which is the exact verdict this module
+     * exists to make trustworthy.
+     */
+    const early = new Map();
+    let ended = null;
+    const endWaiters = [];
+    const end = (reason, said) => {
+        if (!ended)
+            ended = { reason, said };
+        for (const wake of endWaiters.splice(0))
+            wake();
+    };
+    child.on("error", ((error) => end("spawn_failed", firstLine(errorText(error)))));
+    child.on("exit", ((code) => end("server_exited", `the server exited with code ${code ?? "null"} before answering`)));
+    let buffer = "";
+    child.stdout?.on("data", (chunk) => {
+        buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let newline = buffer.indexOf("\n");
+        while (newline !== -1) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf("\n");
+            if (line === "")
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Not our protocol. A server that writes prose to stdout has already
+                // broken the transport for every real client too, so it is named.
+                end("protocol_error", "the server wrote something to stdout that is not JSON-RPC");
+                return;
+            }
+            const message = parsed;
+            const id = typeof message["id"] === "number" ? message["id"] : null;
+            if (id === null)
+                continue;
+            const waiter = pending.get(id);
+            if (!waiter) {
+                early.set(id, message);
+                continue;
+            }
+            pending.delete(id);
+            waiter(message);
+        }
+    });
+    const send = (message) => {
+        child.stdin?.write(`${JSON.stringify(message)}\n`);
+    };
+    const awaitReply = (id) => new Promise((resolve) => {
+        const alreadyHere = early.get(id);
+        if (alreadyHere) {
+            early.delete(id);
+            resolve(alreadyHere);
+            return;
+        }
+        if (ended) {
+            resolve(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            pending.delete(id);
+            end("timed_out", `the server did not answer within ${timeoutMs} ms`);
+            resolve(null);
+        }, timeoutMs);
+        timer.unref?.();
+        endWaiters.push(() => {
+            clearTimeout(timer);
+            pending.delete(id);
+            resolve(null);
+        });
+        pending.set(id, (message) => {
+            clearTimeout(timer);
+            resolve(message);
+        });
+    });
+    try {
+        send({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-06-18",
+                capabilities: {},
+                clientInfo: { name: "cockpit-doctor", version: "1" },
+            },
+        });
+        const initialized = await awaitReply(1);
+        if (!initialized)
+            return { status: "no_answer", ms: elapsed(), ...endedDetail(ended) };
+        if (initialized["error"]) {
+            return {
+                status: "no_answer",
+                ms: elapsed(),
+                reason: "protocol_error",
+                said: firstLine(rpcErrorMessage(initialized)),
+            };
+        }
+        send({ jsonrpc: "2.0", method: "notifications/initialized" });
+        send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "tools/call",
+            params: { name: request.toolName, arguments: request.toolArguments },
+        });
+        const called = await awaitReply(2);
+        if (!called)
+            return { status: "no_answer", ms: elapsed(), ...endedDetail(ended) };
+        if (called["error"]) {
+            return {
+                status: "no_answer",
+                ms: elapsed(),
+                reason: "protocol_error",
+                said: firstLine(rpcErrorMessage(called)),
+            };
+        }
+        const result = (called["result"] ?? {});
+        const said = firstLine((result.content ?? []).find((part) => part.type === "text")?.text ?? "");
+        if (result.isError !== true)
+            return { status: "answered", ms: elapsed(), said };
+        return { status: "refused", ms: elapsed(), reason: refusalReason(said), said };
+    }
+    finally {
+        try {
+            child.stdin?.end();
+            child.kill();
+        }
+        catch (error) {
+            // The verdict is already decided; a child that will not close changes
+            // none of it. Not silent: the reason travels in the caller's log.
+            void error;
+        }
+    }
+}
+/**
+ * The DOOR's own reason label, lifted from the sentence the MCP server's
+ * `tool-result.ts` built. Deliberately not rephrased — that file's header is
+ * explicit that a second wording in a second place is a second thing to keep
+ * in step. `packages/bli-cockpit-mcp/scripts/smoke.ts` reads the same shapes
+ * for the same reason; the two live in packages that do not depend on each
+ * other, which is why the reading exists twice and nothing else does.
+ */
+export function refusalReason(said) {
+    if (/could not be reached for [^(]*\(/u.test(said))
+        return "door_unreachable";
+    const refused = /refused [^(]*\(([^)]+)\)/u.exec(said);
+    if (refused?.[1])
+        return refused[1];
+    const unpaired = /not paired with Tower \(([^)]+)\)/u.exec(said);
+    if (unpaired?.[1])
+        return unpaired[1];
+    return "unlabelled_refusal";
+}
+function endedDetail(ended) {
+    return ended ?? { reason: "protocol_error", said: "the server stopped answering for an unnamed reason" };
+}
+function rpcErrorMessage(message) {
+    const error = message["error"];
+    if (error && typeof error === "object") {
+        const detail = error;
+        if (typeof detail.message === "string")
+            return detail.message;
+        return `JSON-RPC error ${String(detail.code ?? "?")}`;
+    }
+    return "JSON-RPC error";
+}
+function defaultSpawn(command, args, options) {
+    return spawn(command, args, {
+        env: options.env,
+        stdio: ["pipe", "pipe", "ignore"],
+    });
+}
+function defaultRealpath(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return value;
+    }
+}
+function defaultExists(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstLine(value) {
+    return (value.split("\n")[0] ?? value).slice(0, 240);
+}

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.72");
+    writeLine(io?.stdout ?? process.stdout, "0.2.74");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.72",
+  "version": "0.2.74",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,11 +24,11 @@
     "pretypecheck": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.11",
-    "@bli-cockpit/mcp": "0.1.12",
+    "@bli-cockpit/mcp": "0.1.13",
     "@bli-cockpit/telemetry-core": "0.1.32"
   }
 }