glasspane-mcp 1.4.0 → 1.6.0

package/dist/dispatch.d.ts

@@ -26,7 +26,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
 export declare const SERVER_INFO: {
     readonly name: "glasspane-mcp";
-    readonly version: "1.4.0";
+    readonly version: "1.6.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/http-gateway-cli.js

@@ -1300,6 +1300,12 @@ function sortKeys(value) {
   return value;
 }
 
+// src/update-state.ts
+var CA_ROOTS_STATUSES = ["ok", "probe-failed", "empty", "unavailable", "write-unverified"];
+var KNOWN_CA_ROOTS_STATUSES = new Set(CA_ROOTS_STATUSES);
+var RUNTIME_STATUSES = ["refreshed", "failed", "kept", "skipped"];
+var KNOWN_RUNTIME_STATUSES = new Set(RUNTIME_STATUSES);
+
 // src/project-registry.ts
 import fs2 from "node:fs";
 import os2 from "node:os";

package/dist/http-gateway.js

@@ -1290,6 +1290,12 @@ function sortKeys(value) {
   return value;
 }
 
+// src/update-state.ts
+var CA_ROOTS_STATUSES = ["ok", "probe-failed", "empty", "unavailable", "write-unverified"];
+var KNOWN_CA_ROOTS_STATUSES = new Set(CA_ROOTS_STATUSES);
+var RUNTIME_STATUSES = ["refreshed", "failed", "kept", "skipped"];
+var KNOWN_RUNTIME_STATUSES = new Set(RUNTIME_STATUSES);
+
 // src/project-registry.ts
 import fs2 from "node:fs";
 import os from "node:os";

package/dist/index.js

@@ -304,6 +304,167 @@ var KNOWN_STATUSES = /* @__PURE__ */ new Set([
   "disabled",
   "installer-pointer-stale"
 ]);
+var CA_ROOTS_STATUSES = ["ok", "probe-failed", "empty", "unavailable", "write-unverified"];
+var KNOWN_CA_ROOTS_STATUSES = new Set(CA_ROOTS_STATUSES);
+function isCaRootsStatus(value) {
+  return KNOWN_CA_ROOTS_STATUSES.has(value);
+}
+var CA_BUNDLE_FILE_NAME = "ca-roots.pem";
+function decodeCaRoots(value, bundlePath) {
+  if (value === void 0 || value === null) {
+    return { ok: true, ca: { recorded: false, bundlePath } };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      reason: `caRoots is ${Array.isArray(value) ? "an array" : typeof value} instead of the object the exporter writes`
+    };
+  }
+  const record = value;
+  const rawStatus = record.status;
+  if (typeof rawStatus !== "string" || !isCaRootsStatus(rawStatus)) {
+    return {
+      ok: false,
+      reason: `caRoots.status ${JSON.stringify(rawStatus ?? null)} is not one of ${CA_ROOTS_STATUSES.join(", ")}`
+    };
+  }
+  const rawCerts = record.certs;
+  let certs = null;
+  if (typeof rawCerts === "number") {
+    if (!Number.isInteger(rawCerts) || rawCerts < 0) {
+      return { ok: false, reason: `caRoots.certs ${JSON.stringify(rawCerts)} is not a certificate count` };
+    }
+    certs = rawCerts;
+  } else if (rawCerts !== void 0 && rawCerts !== null) {
+    return { ok: false, reason: `caRoots.certs is ${typeof rawCerts} instead of a count or null` };
+  }
+  if (rawStatus === "ok" && (certs === null || certs < 1)) {
+    return {
+      ok: false,
+      reason: `caRoots.status says ok but it records ${JSON.stringify(rawCerts ?? null)} certificates`
+    };
+  }
+  const rawPath = record.path;
+  let recordedPath = null;
+  if (typeof rawPath === "string") {
+    if (rawPath.trim() === "") {
+      return { ok: false, reason: "caRoots.path is blank, so the bundle it points at cannot be named" };
+    }
+    recordedPath = rawPath;
+  } else if (rawPath !== void 0 && rawPath !== null) {
+    return { ok: false, reason: `caRoots.path is ${typeof rawPath} instead of a path or null` };
+  }
+  return {
+    ok: true,
+    ca: {
+      recorded: true,
+      status: rawStatus,
+      certs,
+      exportedAt: typeof record.exportedAt === "string" ? record.exportedAt : null,
+      detail: typeof record.detail === "string" && record.detail.trim() !== "" ? record.detail : null,
+      bundlePath,
+      recordedPath
+    }
+  };
+}
+var RUNTIME_STATUSES = ["refreshed", "failed", "kept", "skipped"];
+var KNOWN_RUNTIME_STATUSES = new Set(RUNTIME_STATUSES);
+function isRuntimeStatus(value) {
+  return KNOWN_RUNTIME_STATUSES.has(value);
+}
+var RUNTIME_KEYS = [
+  "status",
+  "version",
+  "cliPath",
+  "previousCliPath",
+  "agentVerified",
+  "at",
+  "code",
+  "detail"
+];
+var RUNTIME_VERSION_RE = /^\d+\.\d+\.\d+$/;
+var RUNTIME_CODE_RE = /^[a-z0-9][a-z0-9.-]*$/;
+function runtimeTextSlot(record, field, purpose) {
+  const raw = record[field];
+  if (raw === void 0 || raw === null) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: `runtime.${field} is ${typeof raw} instead of ${purpose} or null` };
+  }
+  if (raw.trim() === "") {
+    return { ok: false, reason: `runtime.${field} is blank, so ${purpose} cannot be named` };
+  }
+  return { ok: true, value: raw };
+}
+function decodeRuntime(value) {
+  if (value === void 0 || value === null) {
+    return { ok: true, runtime: { recorded: false, writtenAsNull: value === null } };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      reason: `runtime is ${Array.isArray(value) ? "an array" : typeof value} instead of the object the updater writes`
+    };
+  }
+  const record = value;
+  const stray = Object.keys(record).filter((key) => !RUNTIME_KEYS.includes(key));
+  if (stray.length > 0) {
+    return {
+      ok: false,
+      reason: `runtime carries ${stray.map((key) => JSON.stringify(key)).join(", ")}, a key the state schema does not declare (the object is closed with additionalProperties: false)`
+    };
+  }
+  const rawStatus = record.status;
+  if (typeof rawStatus !== "string" || !isRuntimeStatus(rawStatus)) {
+    return {
+      ok: false,
+      reason: `runtime.status ${JSON.stringify(rawStatus ?? null)} is not one of ${RUNTIME_STATUSES.join(", ")}`
+    };
+  }
+  const version = runtimeTextSlot(record, "version", "a version");
+  if (!version.ok) return version;
+  if (version.value !== null && !RUNTIME_VERSION_RE.test(version.value)) {
+    return { ok: false, reason: `runtime.version ${JSON.stringify(version.value)} is not a version this shell can name` };
+  }
+  const cliPath = runtimeTextSlot(record, "cliPath", "the installed copy");
+  if (!cliPath.ok) return cliPath;
+  const previousCliPath = runtimeTextSlot(record, "previousCliPath", "the copy it came from");
+  if (!previousCliPath.ok) return previousCliPath;
+  const at = runtimeTextSlot(record, "at", "an instant");
+  if (!at.ok) return at;
+  const code = runtimeTextSlot(record, "code", "a gate code");
+  if (!code.ok) return code;
+  if (code.value !== null && !RUNTIME_CODE_RE.test(code.value)) {
+    return { ok: false, reason: `runtime.code ${JSON.stringify(code.value)} is not a gate code this shell can quote` };
+  }
+  const rawAgent = record.agentVerified;
+  let agentVerified = null;
+  if (typeof rawAgent === "boolean") {
+    agentVerified = rawAgent;
+  } else if (rawAgent !== void 0 && rawAgent !== null) {
+    return { ok: false, reason: `runtime.agentVerified is ${typeof rawAgent} instead of true, false or null` };
+  }
+  const rawDetail = record.detail;
+  return {
+    ok: true,
+    runtime: {
+      recorded: true,
+      status: rawStatus,
+      version: version.value,
+      cliPath: cliPath.value,
+      previousCliPath: previousCliPath.value,
+      agentVerified,
+      at: at.value,
+      code: code.value,
+      detail: typeof rawDetail === "string" && rawDetail.trim() !== "" ? rawDetail : null
+    }
+  };
+}
+function runtimeIsUsable(runtime) {
+  return runtime.recorded && runtime.status === "refreshed" && runtime.agentVerified === true;
+}
+function stateRootOf(stateFile) {
+  return path.dirname(stateFile);
+}
 function readUpdateState(env = process.env, stateRootOverride) {
   const stateFile = updateStateFile(env, stateRootOverride);
   if (stateFile === null) {
@@ -348,6 +509,22 @@ function readUpdateState(env = process.env, stateRootOverride) {
       summary: `update state: ${stateFile} carries status ${JSON.stringify(parsed.status ?? null)}, which is not a status this shell knows; the updater and this shell disagree about the contract, so freshness is unknown`
     };
   }
+  const ca = decodeCaRoots(parsed.caRoots, path.join(path.dirname(stateFile), CA_BUNDLE_FILE_NAME));
+  if (!ca.ok) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} carries a CA trust bundle record this shell cannot read (${ca.reason}); whether this install can reach the release endpoint at all is unknown, so nothing below it is trusted either \u2014 re-run the installer or \`node updater/cli.js enable\` to write the record again`
+    };
+  }
+  const runtime = decodeRuntime(parsed.runtime);
+  if (!runtime.ok) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} carries an updater self-update record this shell cannot read (${runtime.reason}); which copy of the updater this machine's daily job will run next is unknown, so nothing below it is trusted either \u2014 re-run the GlassPane installer, or \`node updater/cli.js enable\`, to write the record again`
+    };
+  }
   const bits = [
     `status=${status}`,
     `current=${String(parsed.current ?? "unknown")}`,
@@ -363,7 +540,7 @@ function readUpdateState(env = process.env, stateRootOverride) {
   if (staged && typeof staged.version === "string") {
     bits.push(`staged=${staged.version}${staged.digest ? ` (${String(staged.digest).slice(0, 12)}\u2026)` : ""}`);
   }
-  return { kind: "read", stateFile, summary: `update state: ${bits.join("; ")}` };
+  return { kind: "read", stateFile, summary: `update state: ${bits.join("; ")}`, ca: ca.ca, runtime: runtime.runtime };
 }
 
 // src/io.ts
@@ -2838,7 +3015,13 @@ async function runValidatedTool(spec, value, engine, session, turn) {
     }
     const content = [{ type: "text", text: canonicalJson(raw) }];
     if (spec.name === "gp_diagnose") {
-      content.push({ type: "text", text: readUpdateState().summary });
+      const reading = readUpdateState();
+      content.push({
+        type: "text",
+        text: reading.kind === "read" ? `${reading.summary}
+${caBundleDiagnosis(reading.ca)}
+${runtimeSelfDiagnosis(reading.runtime, reading.stateFile)}` : reading.summary
+      });
     }
     return {
       content,
@@ -2865,6 +3048,88 @@ async function runValidatedTool(spec, value, engine, session, turn) {
     };
   }
 }
+function caBundleDiagnosis(ca) {
+  const enableCmd = "`node updater/cli.js enable`";
+  if (!ca.recorded) {
+    return `ca trust bundle: this install has never recorded exporting the machine's trusted roots (the state file carries no caRoots), which is NOT the same as "the bundle is fine" \u2014 an install predating the export step looks exactly like this. node then verifies only against the CA list inside its own binary, so on a machine whose HTTPS is re-signed locally every auto-update run fails certificate verification and nothing on the surface says so. Remedy: re-run the GlassPane installer, or ${enableCmd}, either of which writes the roots to ${ca.bundlePath} and points the launchd agent and the panel at it. For a check run by hand in a terminal: export NODE_EXTRA_CA_CERTS=${ca.bundlePath} \u2014 but only once that file exists, and set before node starts, because a running process never picks the variable up.`;
+  }
+  const target = ca.recordedPath ?? ca.bundlePath;
+  const countClause = ca.certs === null ? "an unrecorded number of certificates" : `${ca.certs} certificates`;
+  let diagnosis;
+  switch (ca.status) {
+    case "ok":
+      diagnosis = `ca trust bundle: ok \u2014 node will use this exported root bundle (${countClause} at ${target}) for the updater's HTTPS, so a locally re-signed certificate chain on this machine does not stop a check. Nothing to do; the bundle is refreshed by the installer, by ${enableCmd}, and after every successful apply.`;
+      break;
+    case "probe-failed":
+      diagnosis = `ca trust bundle: probe-failed \u2014 ${countClause} were written to ${target}, and reaching the release endpoint through them still failed. This is the machine-still-intercepted case: the exported bundle does not contain the root that re-signs this network's TLS, so the scheduled updater is dead on every run exactly as it was before the bundle existed. Remedy: get that root into the System keychain (/Library/Keychains/System.keychain), then refresh the export with ${enableCmd} or a re-run of the installer. Pointing NODE_EXTRA_CA_CERTS at ${target} changes nothing while the signing root is missing.`;
+      break;
+    case "empty": {
+      const kept = ca.recordedPath !== null;
+      diagnosis = `ca trust bundle: empty \u2014 "security find-certificate" ran and produced ${countClause}, so this export published nothing new` + (kept ? `; the bundle already at ${target} was kept and is still what the agent and the panel hand to node, so a check can pass today while this machine's current roots go unrecorded.` : `; nothing is at ${target} either, so on a machine whose HTTPS is re-signed locally every check fails certificate verification from here.`) + ` Remedy: check that both keychains are readable (\`security dump-keychain\` lists them), then re-run the GlassPane installer or ${enableCmd} to export again.`;
+      break;
+    }
+    case "unavailable":
+      diagnosis = `ca trust bundle: unavailable \u2014 the \`security\` tool was not found on this host, so this machine's trusted roots could not be read and no bundle was written or refreshed at ${target}. Unless something else already put a bundle there, the updater carries only node's built-in list, so on a re-signing network it cannot reach a release at all. Remedy: place a root bundle you trust at a path of your choosing and give that same path to both consumers \u2014 \`export NODE_EXTRA_CA_CERTS=<that path>\` for runs from this terminal, the launchd environment for the scheduled one \u2014 then re-run the GlassPane installer so the agent and the panel record it.`;
+      break;
+    case "write-unverified":
+      diagnosis = `ca trust bundle: write-unverified \u2014 the bytes read back from ${target} were not the bytes the exporter wrote, and the export counted ${countClause}, so whatever sits at that path is not the bundle this install believes in. Verification can fail at any point, including after a partial write. Remedy: re-run the GlassPane installer or ${enableCmd}, which exports again and reads the file back; if it repeats, ${target} sits on a volume that will not hold a private regular file, and auto-update must stay off until that is fixed.`;
+      break;
+    default: {
+      const unhandled = ca.status;
+      diagnosis = `ca trust bundle: the state file records ${JSON.stringify(unhandled)}, a state this shell has no sentence for; treat the CA trust bundle as unverified and re-run the GlassPane installer`;
+    }
+  }
+  const provenance = [
+    ca.exportedAt === null ? null : `exported ${ca.exportedAt}`,
+    ca.detail === null ? null : `recorded reason: ${ca.detail}`
+  ].filter((part) => part !== null);
+  return provenance.length === 0 ? diagnosis : `${diagnosis} The record itself says: ${provenance.join("; ")}.`;
+}
+function runtimeSelfDiagnosis(runtime, stateFile) {
+  const installerCmd = "`node installer/cli.js` (or the `install.sh` this machine was installed with)";
+  const enableCmd = (cliPath) => cliPath === null ? null : `node ${cliPath} enable --state-dir ${stateRootOf(stateFile)} --json`;
+  const copy = (version, cliPath) => {
+    if (cliPath === null) {
+      return version === null ? "the record names neither a version nor a path for it" : `version ${version}, and the record names no path for it`;
+    }
+    return version === null ? `${cliPath} (no version recorded)` : `${version} at ${cliPath}`;
+  };
+  if (!runtime.recorded) {
+    return `updater self-update: this install has never recorded moving the updater's own copy \u2014 the state file ${runtime.writtenAsNull ? 'carries "runtime": null' : 'carries no "runtime" record at all'}, which is NOT the same as "the installed updater is current". An install that predates the self-swap looks exactly like this, and its daily job still runs the copy the installer first cloned: a release whose content is "fix the updater" can never reach this machine by itself. Remedy: re-run the GlassPane installer once, ${installerCmd}. That is a manual step this install needs before self-updating is possible; after it, a successful apply records this line as refreshed.`;
+  }
+  const location = copy(runtime.version, runtime.cliPath);
+  let diagnosis;
+  switch (runtime.status) {
+    case "refreshed": {
+      if (!runtimeIsUsable(runtime)) {
+        diagnosis = `updater self-update: refreshed, but not confirmed \u2014 the record claims the updater's own copy (${location}) is installed, yet the loaded launchd job was never read back going through that entry, so this is not evidence the new copy runs: tomorrow's check may still execute the previous one. Remedy: ` + (enableCmd(runtime.cliPath) === null ? `the record names no script to register, so re-run the GlassPane installer, ${installerCmd}` : `have that copy register itself and read the job back with \`${enableCmd(runtime.cliPath)}\`, or re-run the GlassPane installer, ${installerCmd}`) + ". Until this line says refreshed with the job read back, do not treat a release that fixes the updater as delivered here.";
+        break;
+      }
+      diagnosis = `updater self-update: refreshed \u2014 the updater's own installed copy (${location}) is in place and the loaded launchd job was read back and seen to go through the stable entry that resolves this pointer, so this machine's daily check runs the same code the last release shipped. Nothing to do: a future release that changes the updater reaches this install without anyone reinstalling.`;
+      break;
+    }
+    case "failed":
+      diagnosis = `updater self-update: failed \u2014 the update itself installed (the .app bundles and the npm packages did change), but the updater's own copy did not move: the copy this swap tried to install (${location}) is not what the job runs, and the previous copy still does. This is NOT "the update failed", and it is not harmless either: the scheduled job keeps running the previous updater with that version's gates, so a release that fixes the updater cannot land here while the line above still reads up-to-date. Remedy: re-run the GlassPane installer, ${installerCmd}, which rewrites the installer pointer and puts a current copy in place` + (enableCmd(runtime.cliPath) === null ? " \u2014 this record names no new copy at all, so the installer is the only way out" : `; if the tree already on disk is the one you want running, \`${enableCmd(runtime.cliPath)}\` registers that copy directly`) + ". Do not count the next check as running new code until this line says refreshed.";
+      break;
+    case "kept":
+      diagnosis = `updater self-update: kept \u2014 automatic update is switched off on this machine, so the updater's code and the installer pointer moved (${location}) but no launchd job was registered. This is the switch doing what it was set to, not a failure, and not a self-updating install either: nothing will move here by itself, so the settings panel and a hand-run check are the only ways this copy advances. Remedy: switch automatic ` + (enableCmd(runtime.cliPath) === null ? `update back on in the settings panel, or re-run the GlassPane installer, ${installerCmd}, which registers the job as it installs` : `update back on in the settings panel, or let that copy register itself with \`${enableCmd(runtime.cliPath)}\`; the installer, ${installerCmd}, does the same as it installs`) + ".";
+      break;
+    case "skipped":
+      diagnosis = "updater self-update: skipped \u2014 the updater's code, the installer pointer and the stable agent entry all moved, but the registered launchd job still names a versioned script instead of that entry, so this machine owes one migration. Every scheduled apply stops here until it is done, because re-registering from inside the daily job would unregister the job that is running it" + (runtime.cliPath === null ? "" : `; the copy that would run next is ${location}`) + `. So treat the updater as whatever the loaded job actually runs, rather than as current. Remedy (one time): switch automatic update off and on again in the settings panel, or run \`updater enable\` from a terminal \u2014 after that a version move is a single file write and no future release will ask for this step; if a machine has only ever shown skipped, re-run the GlassPane installer, ${installerCmd}, once to put a self-updating copy down.`;
+      break;
+    default: {
+      const unhandled = runtime.status;
+      diagnosis = `updater self-update: the state file records ${JSON.stringify(unhandled)}, a state this shell has no sentence for; treat the updater's own copy as unverified and re-run the GlassPane installer`;
+    }
+  }
+  const provenance = [
+    runtime.at === null ? null : `recorded at ${runtime.at}`,
+    runtime.code === null ? null : `gate code: ${runtime.code}`,
+    runtime.previousCliPath === null ? null : `previous copy: ${runtime.previousCliPath}`,
+    runtime.detail === null ? null : `recorded reason: ${runtime.detail}`
+  ].filter((part) => part !== null);
+  return provenance.length === 0 ? diagnosis : `${diagnosis} The record itself says: ${provenance.join("; ")}.`;
+}
 var EvidenceFrameShapeError = class extends Error {
   constructor(detail) {
     super(`engine returned a last_evidence frame without an evidencePack object: ${detail}`);
@@ -3325,7 +3590,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.4.0" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.6.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;

package/dist/update-state.d.ts

@@ -11,11 +11,101 @@ export declare const STATE_DIR_ENV = "GLASSPANE_STATE_DIR";
 export declare function recordHome(): string | null;
 /** Where `update-state.json` lives for this process, or null when it cannot be named. */
 export declare function updateStateFile(env?: NodeJS.ProcessEnv, stateRootOverride?: string): string | null;
-export interface UpdateStateReading {
-    kind: "read" | "absent" | "unreadable" | "unresolvable";
+export type UpdateStateReading = {
+    kind: "read";
+    stateFile: string;
+    summary: string;
+    /** Decoded `caRoots`, present exactly when the file was read and understood. */
+    ca: CaRootsReading;
+    /** Decoded `runtime`, present exactly when the file was read and understood. */
+    runtime: RuntimeReading;
+} | {
+    kind: "absent" | "unreadable" | "unresolvable";
     stateFile: string | null;
     summary: string;
-}
+};
+/**
+ * The five states the exporter can record for the machine's root bundle, as a closed
+ * set: `ok` (a non-empty bundle landed and a probe through it reached the release
+ * endpoint), `probe-failed` (bundle landed, endpoint still unreachable with it),
+ * `empty` (the keychain dump produced no certificates), `unavailable` (no keychain
+ * tool on this host), `write-unverified` (the file read back different from what was
+ * written). Only `ok` means usable; the other four each fail in their own way, so
+ * collapsing any of them into `ok` hands an agent a false all-clear.
+ */
+export declare const CA_ROOTS_STATUSES: readonly ["ok", "probe-failed", "empty", "unavailable", "write-unverified"];
+export type CaRootsStatus = (typeof CA_ROOTS_STATUSES)[number];
+/** Name the exporter gives the bundle inside the state root; used to name it when the record does not. */
+export declare const CA_BUNDLE_FILE_NAME = "ca-roots.pem";
+export type CaRootsReading = {
+    recorded: true;
+    status: CaRootsStatus;
+    /** Certificate count as recorded; `null` only for the non-`ok` states, which may not have one. */
+    certs: number | null;
+    exportedAt: string | null;
+    /** The exporter's own reason text, when it wrote one. */
+    detail: string | null;
+    /** Where this state root's bundle lives, resolved the same way the state file was. */
+    bundlePath: string;
+    /** The path the exporter recorded, when it recorded one. */
+    recordedPath: string | null;
+} | {
+    recorded: false;
+    bundlePath: string;
+};
+/**
+ * The four states the updater can record for **its own installed copy**, as a closed set:
+ * `refreshed` (the new copy landed, the pointer names it, and the loaded launchd job was read back and
+ * seen to go through the stable agent entry that resolves that pointer — with the entry in place the job
+ * no longer names a version, so `agentVerified` is a claim about the entry, not about this version),
+ * `failed` (the updater's own copy did not move — the `.app`/npm swap may still have
+ * succeeded, so this is a stated degradation and emphatically not "the update failed"),
+ * `kept` (automatic update is switched off on this machine, so the code and the pointer
+ * moved but no job was registered: neither a failure nor something to brag about),
+ * `skipped` (the code, the pointer and the entry all moved, but the registered job still names a
+ * versioned script, so this machine owes the one migration that puts it on the entry — after which no
+ * version asks again). Only `refreshed` with `agentVerified === true` is
+ * usable; folding any other state into it is how a machine that has run the same stale
+ * updater since install reads as one that fixes itself.
+ */
+export declare const RUNTIME_STATUSES: readonly ["refreshed", "failed", "kept", "skipped"];
+export type RuntimeStatus = (typeof RUNTIME_STATUSES)[number];
+export type RuntimeReading = {
+    recorded: true;
+    status: RuntimeStatus;
+    /** Version the updater's own copy was moved to; `null` when the record did not say. */
+    version: string | null;
+    /** The installed copy this record is about — a real path, never a template. */
+    cliPath: string | null;
+    /** The copy it came from, when the record kept one (what a rollback points back at). */
+    previousCliPath: string | null;
+    /** `true` only after the loaded job was read back and names `cliPath`. */
+    agentVerified: boolean | null;
+    at: string | null;
+    /** Stable code of the gate that refused (`runtime-stale`, `auto-disabled`, …), or null. */
+    code: string | null;
+    /** The updater's own reason text, when it wrote one. */
+    detail: string | null;
+} | {
+    recorded: false;
+    /**
+     * Which route left nothing recorded: `true` is a file that carries `runtime: null`,
+     * `false` is a file with no such key at all — the shape an install predating the
+     * feature has. Both mean "this swap never tried", and they stay apart because a
+     * reader says them differently.
+     */
+    writtenAsNull: boolean;
+};
+/**
+ * Does this record say the updater's own copy is current? Only `refreshed` *with*
+ * `agentVerified === true` qualifies — that pair is the one moment where the code on disk
+ * and the code launchd has loaded were both looked at. `kept` is deliberately not usable:
+ * the machine is switched off for automatic updates, so nothing was registered and nothing
+ * will move by itself.
+ */
+export declare function runtimeIsUsable(runtime: RuntimeReading): boolean;
+/** The state root a state file lives in: one author, so a remedy command never names a directory that is not the root. */
+export declare function stateRootOf(stateFile: string): string;
 /**
  * Read and render. Never throws: `gp_diagnose` answers about an operation, and a
  * missing or broken update file is a fact about the machine, not a reason to fail

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glasspane-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "GlassPane MCP stdio shell: JSON-RPC 2.0 over stdio bridging an AI agent to the glasspane engine daemon",
   "type": "module",
   "main": "./dist/index.js",