glasspane-mcp 1.6.2 → 1.8.1

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.6.2";
+    readonly version: "1.8.1";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/engine-client.d.ts

@@ -167,6 +167,7 @@ export declare function engineDeadlineMs(method: string, params?: Record<string,
 export declare function callerDeadlineMs(method: string, params?: Record<string, unknown>, ceilingMs?: number): number;
 /** Engine protocol version this shell speaks (daemon `hello.protocolVersion`). */
 export declare const ENGINE_PROTOCOL_VERSION = "0";
+export declare const ENGINE_WRITE_BACKLOG_BYTES: number;
 /** Daemon self-report the shell compares a fresh connection against. */
 export interface EngineIdentityExpectation {
     /**
@@ -242,6 +243,15 @@ export declare function livenessProbeDecision(outcome: LivenessProbeOutcome): st
 export type ShellSurface = "mcp" | "http";
 /** Where the answer to a timed-out request can be found, per surface. */
 export declare function lateReplyRoute(surface: ShellSurface): string;
+/**
+ * 背压闸的出路。两条禁令各由一条现场证据撑着：探针本身也要过一次 `call()`，会被
+ * 同一道测量原地拒掉，所以旧文本那句"先用 gp_probe_status 查一下"是一件此刻做不到
+ * 第二次的事；这里唯一测到的是**本进程**的字节水位，不是 daemon 的状态，而旧文本
+ * 却挂了 GP_E_ENGINE_UNREACHABLE 那条重启命令——`livenessProbeDecision` 把点名生命
+ * 周期命令的权力只留给 `unreachable`，换一个可能正跑着 act 的 service 会回滚用户屏
+ * 幕上的动作。"每次重试都只会把队列堆得更深"同样不成立：拒绝发生在 `writeLine` 之前。
+ */
+export declare function writeBacklogRemedy(backlogBytes: number, limitBytes: number): string;
 /**
  * Remedy for a deadline overrun: wait and measure, never restart on a probe that
  * merely went unanswered, and never replay a request whose re-issue has a side

package/dist/errors.d.ts

@@ -32,6 +32,20 @@ export declare const GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
  */
 export declare const GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 export declare const GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+/**
+ * Shell-only: this process refused to *write* a request, because the bytes it had
+ * already handed the daemon's socket were not being read
+ * (`ENGINE_WRITE_BACKLOG_BYTES` in `engine-client.ts`).
+ *
+ * It is deliberately not `GP_E_ENGINE_UNREACHABLE`, which is what this refusal
+ * used to answer with: that code's remedy orders a daemon restart, and a backlog
+ * measures a memory watermark in *this* process, not the service's state — the
+ * daemon may be mid-`act` on the user's screen, where a SIGTERM cancels and rolls
+ * the action back. The two answers also have different next moves, which is the
+ * real reason to split the code: the unread bytes may drain on their own, while a
+ * socket nobody is listening on never does.
+ */
+export declare const GP_E_ENGINE_BACKLOG = "GP_E_ENGINE_BACKLOG";
 /**
  * Shell-only, and deliberately *not* a daemon code: this is what the shell
  * answers when a daemon error frame arrives with no `code` at all. Naming it

package/dist/evidence-report.d.ts

@@ -37,6 +37,19 @@ export declare function evidenceSummaryLines(pack: EvidencePackReportView): stri
 export declare function renderMarkdown(pack: EvidencePackReportView, diagnostics: string | undefined): string;
 /** Full HTML view with an operationId anchor; all values escaped. */
 export declare function renderHTML(pack: EvidencePackReportView, diagnostics: string | undefined): string;
+/**
+ * 终端控制字符一律转成可见的 `\uXXXX`。
+ *
+ * markdown 这一路从前是原文输出的：`escapeHTML` 只护住了 HTML 那半，而
+ * `gp_export_evidence` 与报告导出默认交回的就是 markdown——代理会把它直接打到
+ * 终端上。报告里的标题、selector 标题、stateDiff 的键值、探针的文件路径全是
+ * app 自己写的字符串：一个窗口标题里塞一段 OSC-52 就能改写用户的剪贴板，
+ * 一段 ANSI 能把光标移走覆盖掉它说过的话。daemon 那一侧为这件事立过规矩
+ * （R5-03：`<0x20` 控制字符一律转义），这里补齐壳这一侧。
+ *
+ * `\t`(0x09) 与 `\n`(0x0a) 保留——它们是这份报告自己的排版，不是外来字符。
+ */
+export declare function escapeTerminalControl(value: string): string;
 /**
  * Escape HTML metacharacters in values that cross into a report (spec v1.3
  * §13.4, the five-character escape set, no injection). Shared so aggregation

package/dist/http-gateway-cli.js

@@ -125,6 +125,9 @@ var StreamLineIo = class {
   writeLine(line) {
     this.output.write(line + "\n");
   }
+  bufferedBytes() {
+    return this.output.writableLength;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -148,6 +151,7 @@ var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
 var GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 var GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+var GP_E_ENGINE_BACKLOG = "GP_E_ENGINE_BACKLOG";
 var GP_E_UNKNOWN = "GP_E_UNKNOWN";
 var GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
 function formatToolError(code, message, remedy) {
@@ -233,6 +237,7 @@ function callerDeadlineMs(method, params, ceilingMs = CALLER_VISIBLE_CEILING_MS)
   return Math.min(engineDeadlineMs(method, params), ceilingMs);
 }
 var ENGINE_PROTOCOL_VERSION = "0";
+var ENGINE_WRITE_BACKLOG_BYTES = 8 * 1024 * 1024;
 var EngineCallError = class extends Error {
   code;
   message;
@@ -276,6 +281,9 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function writeBacklogRemedy(backlogBytes, limitBytes) {
+  return `this shell wrote nothing: ${backlogBytes} bytes \u2014 over this gate's ${limitBytes} \u2014 are queued in THIS process for the engine socket, and the service accepted the connection and is not reading it. That is a fact about this shell's buffer, not a diagnosis of why: one long operation and a service wedged solid look identical from here, which is why this answer orders neither a restart nor a probe. Stop sending. Do not retry this call in a loop: every attempt is refused by this same measurement, and a refusal writes no bytes, so a loop moves only the clock, not the queue. What is already queued is the service's to read, so wait for the backlog to drain and send again after that \u2014 this gate is re-measured per call, so the first call accepted after the wait is the proof that it drained, and it is a first send rather than a second copy of an action, because nothing went out the first time. While waiting, read the daemon's own log: it is the only side that can say what it is stuck on, and this shell cannot see past its own buffer. For the service installed by this repo's installer that log is \`~/.glasspane/installer-daemon.log\`, the file its stderr is redirected into, in the same directory as the default socket; a daemon started by hand writes wherever its operator pointed its stderr.`;
+}
 function clientClosingRemedy(surface) {
   const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
   return `this shell's own engine client is ending, which measures nothing about the daemon: nothing here authorises touching the daemon's lifecycle, and no restart is authorised by this answer. What is unknown stays unknown: whether the daemon finished this request cannot be told from a client that stopped asking. The reply may still land, under the bound this shell already states \u2014 ${lateReplyRoute(surface)} \u2014 and this shutdown is one of the endings that bound names: the server log line written at this moment lists the requests this client stopped tracking. Read what happened rather than performing it a second time: ${readRoute}. Ask through a server process that still has a live engine client.`;
@@ -418,6 +426,16 @@ var EngineJsonRpcClient = class {
         fail: reject
       };
       entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
+      const backlog = this.io.bufferedBytes?.() ?? 0;
+      if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
+        this.pending.delete(id);
+        this.reject(entry, new EngineCallError(
+          GP_E_ENGINE_BACKLOG,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          writeBacklogRemedy(backlog, ENGINE_WRITE_BACKLOG_BYTES)
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -474,13 +492,18 @@ var EngineJsonRpcClient = class {
     this.report(`dropped late-reply tracking for '${evicted.method}' (id ${evicted.id}): retention cap ${LATE_REPLY_RETENTION} reached`);
   }
   handleMessage(line) {
-    let frame;
+    let parsed;
     try {
-      frame = JSON.parse(line);
+      parsed = JSON.parse(line);
     } catch {
       this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
       return;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
+      return;
+    }
+    const frame = parsed;
     const id = frame.id;
     if (typeof id === "number") {
       const entry = this.pending.get(id);
@@ -525,9 +548,17 @@ var EngineJsonRpcClient = class {
   settleFromFrame(entry, frame) {
     if (frame.error) {
       this.reject(entry, this.engineError(frame.error));
-    } else {
-      this.resolve(entry, frame.result);
+      return;
+    }
+    if (!("result" in frame)) {
+      this.reject(entry, new EngineCallError(
+        GP_E_INTERNAL,
+        `engine answered '${entry.method}' with a frame carrying neither result nor error`,
+        "do not read this call as successful: the engine answered nothing. Retry once, then check the daemon log (stderr) for what it died before answering"
+      ));
+      return;
     }
+    this.resolve(entry, frame.result);
   }
   /**
    * A frame over the cap: attribute it to the request it belonged to — from
@@ -754,6 +785,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -893,7 +927,7 @@ function renderMarkdown(pack, diagnostics) {
     out.push(section.body);
     out.push("");
   }
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
 }
 function renderHTML(pack, diagnostics) {
   const out = [];
@@ -918,7 +952,10 @@ function renderHTML(pack, diagnostics) {
     out.push(`</section>`);
   }
   out.push(`</div>`);
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
+}
+function escapeTerminalControl(value) {
+  return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
 function escapeHTML(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
@@ -1245,7 +1282,11 @@ var RECIPE_MAX_STEPS = 64;
 var RecipeStepKindSchema = z3.enum(["act", "observe", "assert", "diagnose"]);
 var RecipeStepSchema = z3.strictObject({
   kind: RecipeStepKindSchema,
-  params: z3.record(z3.unknown())
+  // Two-argument `z.record`: valid on the zod 3 this package pins *and* on zod 4,
+  // which made the key type mandatory. The fork of opencode runs zod 4, and its
+  // typecheck caught this as `TS2554: Expected 2-3 arguments, but got 1` — a
+  // latent break waiting for the day this package's zod is bumped.
+  params: z3.record(z3.string(), z3.unknown())
 });
 var RecipeConfigSchema = z3.strictObject({
   schemaVersion: z3.literal(RECIPE_SCHEMA_VERSION),
@@ -1281,8 +1322,14 @@ function parseEvidencePackRead(input) {
   throw schemaError("evidence pack", result.error);
 }
 
+// ../kernel/dist/decision-log.js
+var DecisionLogDraftSchema = DecisionLogEntrySchema.omit({
+  sequence: true,
+  prevEntryHash: true
+});
+
 // src/canonical.ts
-function canonicalJson(value) {
+function canonicalJson2(value) {
   return JSON.stringify(sortKeys(value));
 }
 function sortKeys(value) {
@@ -1502,6 +1549,27 @@ function tightenMode(target, want, kind) {
     );
   }
 }
+function fileIdentity(filePath) {
+  try {
+    const stat = fs2.statSync(filePath);
+    return `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+  } catch (error) {
+    if (nodeErrorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+}
+function registryDriftReason(filePath, openedAs, now) {
+  if (now === openedAs) {
+    return null;
+  }
+  return `projects.json at ${filePath} changed between the read that produced this edit and the write that would have published it (was ${openedAs ?? "absent"}, now ${now ?? "absent"}), so this call wrote nothing. Another process \u2014 the background service, its CLI, or the settings panel \u2014 holds a newer version of this table, and renaming ours over theirs would drop their entry while reporting success. Repeat gp_project_set: it reads the file again, so the second attempt carries what the other writer landed. If it keeps failing, something is writing this registry on a timer \u2014 read the file to see what appeared, and do not force the write.`;
+}
+function assertNoConcurrentWrite(filePath, openedAs) {
+  const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
+  if (reason !== null) {
+    throw new ProjectRegistryError("registry-changed-underneath", reason);
+  }
+}
 function saveProjects(filePath, entries) {
   const dir = path2.dirname(filePath);
   const tmpPath = `${filePath}.tmp-${uniqueToken()}`;
@@ -1548,6 +1616,7 @@ function projectSet(args) {
   assertStorablePid(args.pid);
   const snapshot = loadRegistry(filePath);
   const { projects, discarded } = requireUsableRegistry(filePath, snapshot);
+  const openedAs = fileIdentity(filePath);
   let entry;
   const projectId = args.projectId;
   if (projectId) {
@@ -1573,6 +1642,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -2364,7 +2434,7 @@ async function captureView(args, context) {
       };
     }
     const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
-    const summary = canonicalJson({
+    const summary = canonicalJson2({
       mimeType,
       byteCount: body.byteCount,
       pixelWidth: body.pixelWidth,
@@ -2428,7 +2498,7 @@ async function projectListTool() {
   try {
     const projects = projectList();
     return {
-      content: [{ type: "text", text: canonicalJson({ projects }) }],
+      content: [{ type: "text", text: canonicalJson2({ projects }) }],
       isError: false
     };
   } catch (error) {
@@ -2438,7 +2508,7 @@ async function projectListTool() {
 async function projectSetTool(args) {
   try {
     const entry = projectSet(args);
-    return { content: [{ type: "text", text: canonicalJson({ project: entry }) }], isError: false };
+    return { content: [{ type: "text", text: canonicalJson2({ project: entry }) }], isError: false };
   } catch (error) {
     return mapProjectError(error);
   }
@@ -2460,7 +2530,7 @@ async function projectGetTool(args) {
         isError: true
       };
     }
-    return { content: [{ type: "text", text: canonicalJson({ project: entry }) }], isError: false };
+    return { content: [{ type: "text", text: canonicalJson2({ project: entry }) }], isError: false };
   } catch (error) {
     return mapProjectError(error);
   }
@@ -3324,6 +3394,8 @@ function httpStatusForEngineCode(code) {
       return 409;
     case GP_E_ENGINE_UNREACHABLE:
       return 503;
+    case GP_E_ENGINE_BACKLOG:
+      return 503;
     case GP_E_ENGINE_TIMEOUT:
       return 504;
     case GP_E_PAYLOAD_TOO_LARGE:

package/dist/http-gateway.js

@@ -125,6 +125,9 @@ var StreamLineIo = class {
   writeLine(line) {
     this.output.write(line + "\n");
   }
+  bufferedBytes() {
+    return this.output.writableLength;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -148,6 +151,7 @@ var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
 var GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 var GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+var GP_E_ENGINE_BACKLOG = "GP_E_ENGINE_BACKLOG";
 var GP_E_UNKNOWN = "GP_E_UNKNOWN";
 var GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
 function formatToolError(code, message, remedy) {
@@ -229,6 +233,7 @@ function callerDeadlineMs(method, params, ceilingMs = CALLER_VISIBLE_CEILING_MS)
   return Math.min(engineDeadlineMs(method, params), ceilingMs);
 }
 var ENGINE_PROTOCOL_VERSION = "0";
+var ENGINE_WRITE_BACKLOG_BYTES = 8 * 1024 * 1024;
 var EngineCallError = class extends Error {
   code;
   message;
@@ -272,6 +277,9 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function writeBacklogRemedy(backlogBytes, limitBytes) {
+  return `this shell wrote nothing: ${backlogBytes} bytes \u2014 over this gate's ${limitBytes} \u2014 are queued in THIS process for the engine socket, and the service accepted the connection and is not reading it. That is a fact about this shell's buffer, not a diagnosis of why: one long operation and a service wedged solid look identical from here, which is why this answer orders neither a restart nor a probe. Stop sending. Do not retry this call in a loop: every attempt is refused by this same measurement, and a refusal writes no bytes, so a loop moves only the clock, not the queue. What is already queued is the service's to read, so wait for the backlog to drain and send again after that \u2014 this gate is re-measured per call, so the first call accepted after the wait is the proof that it drained, and it is a first send rather than a second copy of an action, because nothing went out the first time. While waiting, read the daemon's own log: it is the only side that can say what it is stuck on, and this shell cannot see past its own buffer. For the service installed by this repo's installer that log is \`~/.glasspane/installer-daemon.log\`, the file its stderr is redirected into, in the same directory as the default socket; a daemon started by hand writes wherever its operator pointed its stderr.`;
+}
 function clientClosingRemedy(surface) {
   const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
   return `this shell's own engine client is ending, which measures nothing about the daemon: nothing here authorises touching the daemon's lifecycle, and no restart is authorised by this answer. What is unknown stays unknown: whether the daemon finished this request cannot be told from a client that stopped asking. The reply may still land, under the bound this shell already states \u2014 ${lateReplyRoute(surface)} \u2014 and this shutdown is one of the endings that bound names: the server log line written at this moment lists the requests this client stopped tracking. Read what happened rather than performing it a second time: ${readRoute}. Ask through a server process that still has a live engine client.`;
@@ -414,6 +422,16 @@ var EngineJsonRpcClient = class {
         fail: reject
       };
       entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
+      const backlog = this.io.bufferedBytes?.() ?? 0;
+      if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
+        this.pending.delete(id);
+        this.reject(entry, new EngineCallError(
+          GP_E_ENGINE_BACKLOG,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          writeBacklogRemedy(backlog, ENGINE_WRITE_BACKLOG_BYTES)
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -470,13 +488,18 @@ var EngineJsonRpcClient = class {
     this.report(`dropped late-reply tracking for '${evicted.method}' (id ${evicted.id}): retention cap ${LATE_REPLY_RETENTION} reached`);
   }
   handleMessage(line) {
-    let frame;
+    let parsed;
     try {
-      frame = JSON.parse(line);
+      parsed = JSON.parse(line);
     } catch {
       this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
       return;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
+      return;
+    }
+    const frame = parsed;
     const id = frame.id;
     if (typeof id === "number") {
       const entry = this.pending.get(id);
@@ -521,9 +544,17 @@ var EngineJsonRpcClient = class {
   settleFromFrame(entry, frame) {
     if (frame.error) {
       this.reject(entry, this.engineError(frame.error));
-    } else {
-      this.resolve(entry, frame.result);
+      return;
+    }
+    if (!("result" in frame)) {
+      this.reject(entry, new EngineCallError(
+        GP_E_INTERNAL,
+        `engine answered '${entry.method}' with a frame carrying neither result nor error`,
+        "do not read this call as successful: the engine answered nothing. Retry once, then check the daemon log (stderr) for what it died before answering"
+      ));
+      return;
     }
+    this.resolve(entry, frame.result);
   }
   /**
    * A frame over the cap: attribute it to the request it belonged to — from
@@ -750,6 +781,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -883,7 +917,7 @@ function renderMarkdown(pack, diagnostics) {
     out.push(section.body);
     out.push("");
   }
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
 }
 function renderHTML(pack, diagnostics) {
   const out = [];
@@ -908,7 +942,10 @@ function renderHTML(pack, diagnostics) {
     out.push(`</section>`);
   }
   out.push(`</div>`);
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
+}
+function escapeTerminalControl(value) {
+  return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
 function escapeHTML(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
@@ -1235,7 +1272,11 @@ var RECIPE_MAX_STEPS = 64;
 var RecipeStepKindSchema = z3.enum(["act", "observe", "assert", "diagnose"]);
 var RecipeStepSchema = z3.strictObject({
   kind: RecipeStepKindSchema,
-  params: z3.record(z3.unknown())
+  // Two-argument `z.record`: valid on the zod 3 this package pins *and* on zod 4,
+  // which made the key type mandatory. The fork of opencode runs zod 4, and its
+  // typecheck caught this as `TS2554: Expected 2-3 arguments, but got 1` — a
+  // latent break waiting for the day this package's zod is bumped.
+  params: z3.record(z3.string(), z3.unknown())
 });
 var RecipeConfigSchema = z3.strictObject({
   schemaVersion: z3.literal(RECIPE_SCHEMA_VERSION),
@@ -1271,8 +1312,14 @@ function parseEvidencePackRead(input) {
   throw schemaError("evidence pack", result.error);
 }
 
+// ../kernel/dist/decision-log.js
+var DecisionLogDraftSchema = DecisionLogEntrySchema.omit({
+  sequence: true,
+  prevEntryHash: true
+});
+
 // src/canonical.ts
-function canonicalJson(value) {
+function canonicalJson2(value) {
   return JSON.stringify(sortKeys(value));
 }
 function sortKeys(value) {
@@ -1492,6 +1539,27 @@ function tightenMode(target, want, kind) {
     );
   }
 }
+function fileIdentity(filePath) {
+  try {
+    const stat = fs2.statSync(filePath);
+    return `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+  } catch (error) {
+    if (nodeErrorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+}
+function registryDriftReason(filePath, openedAs, now) {
+  if (now === openedAs) {
+    return null;
+  }
+  return `projects.json at ${filePath} changed between the read that produced this edit and the write that would have published it (was ${openedAs ?? "absent"}, now ${now ?? "absent"}), so this call wrote nothing. Another process \u2014 the background service, its CLI, or the settings panel \u2014 holds a newer version of this table, and renaming ours over theirs would drop their entry while reporting success. Repeat gp_project_set: it reads the file again, so the second attempt carries what the other writer landed. If it keeps failing, something is writing this registry on a timer \u2014 read the file to see what appeared, and do not force the write.`;
+}
+function assertNoConcurrentWrite(filePath, openedAs) {
+  const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
+  if (reason !== null) {
+    throw new ProjectRegistryError("registry-changed-underneath", reason);
+  }
+}
 function saveProjects(filePath, entries) {
   const dir = path2.dirname(filePath);
   const tmpPath = `${filePath}.tmp-${uniqueToken()}`;
@@ -1538,6 +1606,7 @@ function projectSet(args) {
   assertStorablePid(args.pid);
   const snapshot = loadRegistry(filePath);
   const { projects, discarded } = requireUsableRegistry(filePath, snapshot);
+  const openedAs = fileIdentity(filePath);
   let entry;
   const projectId = args.projectId;
   if (projectId) {
@@ -1563,6 +1632,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -2354,7 +2424,7 @@ async function captureView(args, context) {
       };
     }
     const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
-    const summary = canonicalJson({
+    const summary = canonicalJson2({
       mimeType,
       byteCount: body.byteCount,
       pixelWidth: body.pixelWidth,
@@ -2418,7 +2488,7 @@ async function projectListTool() {
   try {
     const projects = projectList();
     return {
-      content: [{ type: "text", text: canonicalJson({ projects }) }],
+      content: [{ type: "text", text: canonicalJson2({ projects }) }],
       isError: false
     };
   } catch (error) {
@@ -2428,7 +2498,7 @@ async function projectListTool() {
 async function projectSetTool(args) {
   try {
     const entry = projectSet(args);
-    return { content: [{ type: "text", text: canonicalJson({ project: entry }) }], isError: false };
+    return { content: [{ type: "text", text: canonicalJson2({ project: entry }) }], isError: false };
   } catch (error) {
     return mapProjectError(error);
   }
@@ -2450,7 +2520,7 @@ async function projectGetTool(args) {
         isError: true
       };
     }
-    return { content: [{ type: "text", text: canonicalJson({ project: entry }) }], isError: false };
+    return { content: [{ type: "text", text: canonicalJson2({ project: entry }) }], isError: false };
   } catch (error) {
     return mapProjectError(error);
   }
@@ -3314,6 +3384,8 @@ function httpStatusForEngineCode(code) {
       return 409;
     case GP_E_ENGINE_UNREACHABLE:
       return 503;
+    case GP_E_ENGINE_BACKLOG:
+      return 503;
     case GP_E_ENGINE_TIMEOUT:
       return 504;
     case GP_E_PAYLOAD_TOO_LARGE:

package/dist/index.js

@@ -229,7 +229,11 @@ var RECIPE_MAX_STEPS = 64;
 var RecipeStepKindSchema = z3.enum(["act", "observe", "assert", "diagnose"]);
 var RecipeStepSchema = z3.strictObject({
   kind: RecipeStepKindSchema,
-  params: z3.record(z3.unknown())
+  // Two-argument `z.record`: valid on the zod 3 this package pins *and* on zod 4,
+  // which made the key type mandatory. The fork of opencode runs zod 4, and its
+  // typecheck caught this as `TS2554: Expected 2-3 arguments, but got 1` — a
+  // latent break waiting for the day this package's zod is bumped.
+  params: z3.record(z3.string(), z3.unknown())
 });
 var RecipeConfigSchema = z3.strictObject({
   schemaVersion: z3.literal(RECIPE_SCHEMA_VERSION),
@@ -265,6 +269,12 @@ function parseEvidencePackRead(input) {
   throw schemaError("evidence pack", result.error);
 }
 
+// ../kernel/dist/decision-log.js
+var DecisionLogDraftSchema = DecisionLogEntrySchema.omit({
+  sequence: true,
+  prevEntryHash: true
+});
+
 // src/update-state.ts
 import fs from "node:fs";
 import os from "node:os";
@@ -530,11 +540,16 @@ function readUpdateState(env = process.env, stateRootOverride) {
     `current=${String(parsed.current ?? "unknown")}`,
     `latest=${String(parsed.latest ?? "none-seen")}`,
     `lastCheckAt=${String(parsed.updatedAt ?? "never")}`,
-    `autoUpdate=${parsed.disabled === true ? "off" : parsed.autoApply === true ? "on" : "on-by-default"}`
+    // `disabled` 缺失与 `disabled: false` 不是一件事：前者是"这份记录没说"，后者是
+    // "记录说了：没关"。从前两者都掉进 `on-by-default`，等于替这台机器宣布自动更新
+    // 开着——而本文件开头立的规矩恰恰是 absent 不许读成友好态。
+    `autoUpdate=${parsed.disabled === true ? "off" : parsed.disabled === false ? "on" : parsed.autoApply === true ? "on" : "unknown(neither disabled nor autoApply is recorded)"}`
   ];
   const lastError = parsed.lastError;
-  if (lastError && typeof lastError.message === "string") {
-    bits.push(`lastError=${lastError.code ?? "no-code"}: ${lastError.message}`);
+  if (lastError && (typeof lastError.code === "string" || typeof lastError.message === "string")) {
+    const code = typeof lastError.code === "string" && lastError.code !== "" ? lastError.code : "no-code";
+    const message = typeof lastError.message === "string" && lastError.message !== "" ? lastError.message : "(the record carries a code with no message: the code is all this shell can honestly say)";
+    bits.push(`lastError=${code}: ${message}`);
   }
   const staged = parsed.staged;
   if (staged && typeof staged.version === "string") {
@@ -658,6 +673,9 @@ var StreamLineIo = class {
   writeLine(line) {
     this.output.write(line + "\n");
   }
+  bufferedBytes() {
+    return this.output.writableLength;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -789,6 +807,7 @@ var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
 var GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 var GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+var GP_E_ENGINE_BACKLOG = "GP_E_ENGINE_BACKLOG";
 var GP_E_UNKNOWN = "GP_E_UNKNOWN";
 var GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
 function formatToolError(code, message, remedy) {
@@ -874,6 +893,7 @@ function callerDeadlineMs(method, params, ceilingMs = CALLER_VISIBLE_CEILING_MS)
   return Math.min(engineDeadlineMs(method, params), ceilingMs);
 }
 var ENGINE_PROTOCOL_VERSION = "0";
+var ENGINE_WRITE_BACKLOG_BYTES = 8 * 1024 * 1024;
 var EngineCallError = class extends Error {
   code;
   message;
@@ -917,6 +937,9 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function writeBacklogRemedy(backlogBytes, limitBytes) {
+  return `this shell wrote nothing: ${backlogBytes} bytes \u2014 over this gate's ${limitBytes} \u2014 are queued in THIS process for the engine socket, and the service accepted the connection and is not reading it. That is a fact about this shell's buffer, not a diagnosis of why: one long operation and a service wedged solid look identical from here, which is why this answer orders neither a restart nor a probe. Stop sending. Do not retry this call in a loop: every attempt is refused by this same measurement, and a refusal writes no bytes, so a loop moves only the clock, not the queue. What is already queued is the service's to read, so wait for the backlog to drain and send again after that \u2014 this gate is re-measured per call, so the first call accepted after the wait is the proof that it drained, and it is a first send rather than a second copy of an action, because nothing went out the first time. While waiting, read the daemon's own log: it is the only side that can say what it is stuck on, and this shell cannot see past its own buffer. For the service installed by this repo's installer that log is \`~/.glasspane/installer-daemon.log\`, the file its stderr is redirected into, in the same directory as the default socket; a daemon started by hand writes wherever its operator pointed its stderr.`;
+}
 function clientClosingRemedy(surface) {
   const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
   return `this shell's own engine client is ending, which measures nothing about the daemon: nothing here authorises touching the daemon's lifecycle, and no restart is authorised by this answer. What is unknown stays unknown: whether the daemon finished this request cannot be told from a client that stopped asking. The reply may still land, under the bound this shell already states \u2014 ${lateReplyRoute(surface)} \u2014 and this shutdown is one of the endings that bound names: the server log line written at this moment lists the requests this client stopped tracking. Read what happened rather than performing it a second time: ${readRoute}. Ask through a server process that still has a live engine client.`;
@@ -1059,6 +1082,16 @@ var EngineJsonRpcClient = class {
         fail: reject
       };
       entry.timer = setTimeout(() => this.onDeadline(entry), deadlineMs);
+      const backlog = this.io.bufferedBytes?.() ?? 0;
+      if (backlog > ENGINE_WRITE_BACKLOG_BYTES) {
+        this.pending.delete(id);
+        this.reject(entry, new EngineCallError(
+          GP_E_ENGINE_BACKLOG,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          writeBacklogRemedy(backlog, ENGINE_WRITE_BACKLOG_BYTES)
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -1115,13 +1148,18 @@ var EngineJsonRpcClient = class {
     this.report(`dropped late-reply tracking for '${evicted.method}' (id ${evicted.id}): retention cap ${LATE_REPLY_RETENTION} reached`);
   }
   handleMessage(line) {
-    let frame;
+    let parsed;
     try {
-      frame = JSON.parse(line);
+      parsed = JSON.parse(line);
     } catch {
       this.report(`engine sent a non-JSON frame, dropped: ${truncate(line)}`);
       return;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      this.report(`engine sent a frame that is not a JSON object, dropped: ${truncate(line)}`);
+      return;
+    }
+    const frame = parsed;
     const id = frame.id;
     if (typeof id === "number") {
       const entry = this.pending.get(id);
@@ -1166,9 +1204,17 @@ var EngineJsonRpcClient = class {
   settleFromFrame(entry, frame) {
     if (frame.error) {
       this.reject(entry, this.engineError(frame.error));
-    } else {
-      this.resolve(entry, frame.result);
+      return;
+    }
+    if (!("result" in frame)) {
+      this.reject(entry, new EngineCallError(
+        GP_E_INTERNAL,
+        `engine answered '${entry.method}' with a frame carrying neither result nor error`,
+        "do not read this call as successful: the engine answered nothing. Retry once, then check the daemon log (stderr) for what it died before answering"
+      ));
+      return;
     }
+    this.resolve(entry, frame.result);
   }
   /**
    * A frame over the cap: attribute it to the request it belonged to — from
@@ -1395,6 +1441,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -1765,7 +1814,7 @@ function renderMarkdown(pack, diagnostics) {
     out.push(section.body);
     out.push("");
   }
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
 }
 function renderHTML(pack, diagnostics) {
   const out = [];
@@ -1790,7 +1839,10 @@ function renderHTML(pack, diagnostics) {
     out.push(`</section>`);
   }
   out.push(`</div>`);
-  return out.join("\n");
+  return escapeTerminalControl(out.join("\n"));
+}
+function escapeTerminalControl(value) {
+  return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
 function escapeHTML(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
@@ -2106,6 +2158,27 @@ function tightenMode(target, want, kind) {
     );
   }
 }
+function fileIdentity(filePath) {
+  try {
+    const stat = fs3.statSync(filePath);
+    return `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+  } catch (error) {
+    if (nodeErrorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+}
+function registryDriftReason(filePath, openedAs, now) {
+  if (now === openedAs) {
+    return null;
+  }
+  return `projects.json at ${filePath} changed between the read that produced this edit and the write that would have published it (was ${openedAs ?? "absent"}, now ${now ?? "absent"}), so this call wrote nothing. Another process \u2014 the background service, its CLI, or the settings panel \u2014 holds a newer version of this table, and renaming ours over theirs would drop their entry while reporting success. Repeat gp_project_set: it reads the file again, so the second attempt carries what the other writer landed. If it keeps failing, something is writing this registry on a timer \u2014 read the file to see what appeared, and do not force the write.`;
+}
+function assertNoConcurrentWrite(filePath, openedAs) {
+  const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
+  if (reason !== null) {
+    throw new ProjectRegistryError("registry-changed-underneath", reason);
+  }
+}
 function saveProjects(filePath, entries) {
   const dir = path3.dirname(filePath);
   const tmpPath = `${filePath}.tmp-${uniqueToken()}`;
@@ -2152,6 +2225,7 @@ function projectSet(args) {
   assertStorablePid(args.pid);
   const snapshot = loadRegistry(filePath);
   const { projects, discarded } = requireUsableRegistry(filePath, snapshot);
+  const openedAs = fileIdentity(filePath);
   let entry;
   const projectId = args.projectId;
   if (projectId) {
@@ -2177,6 +2251,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -3590,7 +3665,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.6.2" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.8.1" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -3793,6 +3868,12 @@ function parseArgs(argv) {
       i += 1;
     } else if (arg.startsWith("--socket-path=")) {
       options.socketPath = arg.slice("--socket-path=".length);
+    } else {
+      throw new Error(
+        `unknown argument: ${arg}
+${USAGE}
+This shell accepts only --help/-h and --socket-path/-s <path>. A flag spelled wrong here is not an error the daemon will ever report.`
+      );
     }
   }
   return options;

package/dist/io.d.ts

@@ -62,6 +62,16 @@ export declare function recoverFrameId(prefix: string): number | string | null;
  */
 export interface LineIo {
     writeLine(line: string): void;
+    /**
+     * 已经交给内核、还没被对端读走的字节数。可选：只有真的接在一条 socket/pipe 上
+     * 的传输量得出这个数。
+     *
+     * 它存在的理由是 `writeLine` 不看 `output.write()` 的返回值（stdio 那一侧有
+     * `DrainAwareWriter` 管背压，引擎这一侧从前没有）：daemon 停止读 socket 时，
+     * Node 会把写进去的帧无上限地堆在进程内存里，调用方只看到"还没回"，
+     * 而这一面已经悄悄替它攒了几百 MB。有了这个数，客户端可以选择**不再接活**。
+     */
+    bufferedBytes?(): number;
     onMessage(handler: (line: string) => void): void;
     onClose(handler: () => void): void;
     onError(handler: (error: Error) => void): void;
@@ -86,6 +96,7 @@ export declare class StreamLineIo implements LineIo {
     private errorHandler;
     constructor(input: Readable, output: Writable);
     writeLine(line: string): void;
+    bufferedBytes(): number;
     onMessage(handler: (line: string) => void): void;
     onClose(handler: () => void): void;
     onError(handler: (error: Error) => void): void;

package/dist/project-registry.d.ts

@@ -112,6 +112,13 @@ export declare const ProjectSetArgs: z.ZodObject<{
     pid?: number | null | undefined;
 }>;
 export type ProjectSetArgs = z.infer<typeof ProjectSetArgs>;
+/**
+ * 读—改—写之间盘上换了哪一份：给出这一句拒绝的理由，没换则 null。
+ *
+ * 单独抽成纯函数是为了能被验红——`projectSet` 是同步的，测试没法在它读到盘与
+ * 写回盘之间插进另一次写，所以"守卫真的会拦"这件事只能把判据本身拿出来测。
+ */
+export declare function registryDriftReason(filePath: string, openedAs: string | null, now: string | null): string | null;
 export declare function projectList(): ProjectEntry[];
 export declare function projectGet(projectId: string): ProjectEntry | undefined;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glasspane-mcp",
-  "version": "1.6.2",
+  "version": "1.8.1",
   "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",