glasspane-mcp 1.6.2 → 1.7.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.6.2";
+    readonly version: "1.7.0";
 };
 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 {
     /**

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;
   }
@@ -233,6 +236,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;
@@ -418,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_UNREACHABLE,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          `the background service is accepting the connection but not reading it \u2014 it is wedged, not busy. Check it with gp_probe_status; if it stays like this, restart it with the command in \`glasspaned --help\` (or the panel's \u91CD\u542F\u540E\u53F0\u670D\u52A1 button). Do not retry this call in a loop: every retry only deepens the queue it is refusing to drain.`
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -474,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);
@@ -525,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
@@ -754,6 +781,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -893,7 +923,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 +948,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 +1278,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 +1318,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 +1545,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 +1612,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 +1638,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -2364,7 +2430,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 +2494,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 +2504,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 +2526,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);
   }

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;
   }
@@ -229,6 +232,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;
@@ -414,6 +418,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_UNREACHABLE,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          `the background service is accepting the connection but not reading it \u2014 it is wedged, not busy. Check it with gp_probe_status; if it stays like this, restart it with the command in \`glasspaned --help\` (or the panel's \u91CD\u542F\u540E\u53F0\u670D\u52A1 button). Do not retry this call in a loop: every retry only deepens the queue it is refusing to drain.`
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -470,13 +484,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 +540,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 +777,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -883,7 +913,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 +938,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 +1268,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 +1308,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 +1535,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 +1602,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 +1628,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -2354,7 +2420,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 +2484,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 +2494,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 +2516,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);
   }

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;
   }
@@ -874,6 +892,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;
@@ -1059,6 +1078,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_UNREACHABLE,
+          `not sending '${method}': ${backlog} bytes are already queued for the engine socket and it has not read them`,
+          `the background service is accepting the connection but not reading it \u2014 it is wedged, not busy. Check it with gp_probe_status; if it stays like this, restart it with the command in \`glasspaned --help\` (or the panel's \u91CD\u542F\u540E\u53F0\u670D\u52A1 button). Do not retry this call in a loop: every retry only deepens the queue it is refusing to drain.`
+        ));
+        return;
+      }
       this.pending.set(id, entry);
       try {
         this.io.writeLine(JSON.stringify(frame));
@@ -1115,13 +1144,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 +1200,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 +1437,9 @@ var ReconnectingSocketIo = class {
   writeLine(line) {
     this.connect().writeLine(line);
   }
+  bufferedBytes() {
+    return this.inner?.bufferedBytes() ?? 0;
+  }
   onMessage(handler) {
     this.messageHandler = handler;
   }
@@ -1765,7 +1810,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 +1835,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 +2154,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 +2221,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 +2247,7 @@ function projectSet(args) {
     assertSingleIdentity(entry);
     projects.push(entry);
   }
+  assertNoConcurrentWrite(filePath, openedAs);
   saveProjects(filePath, projects);
   return {
     ...entry,
@@ -3590,7 +3661,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.7.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -3793,6 +3864,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.7.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",