glasspane-mcp 1.5.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.5.0";
+    readonly version: "1.6.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/http-gateway-cli.js

@@ -1303,6 +1303,8 @@ function sortKeys(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";

package/dist/http-gateway.js

@@ -1293,6 +1293,8 @@ function sortKeys(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";

package/dist/index.js

@@ -367,6 +367,104 @@ function decodeCaRoots(value, bundlePath) {
     }
   };
 }
+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) {
@@ -419,6 +517,14 @@ function readUpdateState(env = process.env, stateRootOverride) {
       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")}`,
@@ -434,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("; ")}`, ca: ca.ca };
+  return { kind: "read", stateFile, summary: `update state: ${bits.join("; ")}`, ca: ca.ca, runtime: runtime.runtime };
 }
 
 // src/io.ts
@@ -2913,7 +3019,8 @@ async function runValidatedTool(spec, value, engine, session, turn) {
       content.push({
         type: "text",
         text: reading.kind === "read" ? `${reading.summary}
-${caBundleDiagnosis(reading.ca)}` : reading.summary
+${caBundleDiagnosis(reading.ca)}
+${runtimeSelfDiagnosis(reading.runtime, reading.stateFile)}` : reading.summary
       });
     }
     return {
@@ -2978,6 +3085,51 @@ function caBundleDiagnosis(ca) {
   ].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}`);
@@ -3438,7 +3590,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.5.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

@@ -17,6 +17,8 @@ export type UpdateStateReading = {
     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;
@@ -51,6 +53,59 @@ export type CaRootsReading = {
     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.5.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",