glasspane-mcp 1.12.2 → 1.13.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.12.2";
+    readonly version: "1.13.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/engine-client.d.ts

@@ -140,7 +140,16 @@ export declare function isReplayUnsafeMethod(method: string): boolean;
 /** The non-replayable methods, for gates that must see the set change on purpose. */
 export declare const REPLAY_UNSAFE_METHOD_NAMES: readonly string[];
 /**
- * Methods whose re-issue writes daemon state the *caller* depends on, even though
+ * `hello.capabilities` 的第一个读者（2026-10-11）。
+ *
+ * 这份清单由 daemon 从 `EngineMethod` 派生（`FrameCodec.capabilityWireNames`），可此前
+ * **没有任何一方读它**：面板的解析器只取 version/protocolVersion/pid/identity/permissions，
+ * 这一层只比 protocolVersion。没有读者就等于没有镜像——三处真源（kernel schema、daemon 方法表、
+ * 本壳的 TOOL_SPECS）漂了也不会有人说一句，而"清单存在但没人核"正是这份代码在别处反复拒绝的
+ * 那种自证。返回 null 表示无话可说（两边一致），否则给出要说的那句话。
+ */
+export declare function describeCapabilityDrift(advertised: readonly string[] | null, forwarded: readonly string[]): string | null;
+/**
  * replaying them is not unsafe in the sense {@link REPLAY_UNSAFE_REASONS} means
  * (no operation of the user's is performed a second time). They are the other half
  * of the answer to "may this be narrowed by sending it again?", and they are kept
@@ -309,6 +318,14 @@ export declare class EngineJsonRpcClient {
     private readonly callerCeilingMs;
     /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
     private readonly surface;
+    /**
+     * The daemon methods this shell forwards, injected by the composition root
+     * from `TOOL_SPECS` (never hand-copied — a copied list is the drift this
+     * exists to catch). Empty means "no expectation was wired", and the
+     * reconciliation stays silent rather than reporting every capability as
+     * unexposed; `index.ts` supplies the real list.
+     */
+    private readonly expectedDaemonMethods;
     /**
      * Every mutable piece of this client's state, in one object that is *never*
      * reassigned through `this`.
@@ -339,7 +356,15 @@ export declare class EngineJsonRpcClient {
      */
     callerCeilingMs?: number, 
     /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
-    surface?: ShellSurface);
+    surface?: ShellSurface, 
+    /**
+     * The daemon methods this shell forwards, injected by the composition root
+     * from `TOOL_SPECS` (never hand-copied — a copied list is the drift this
+     * exists to catch). Empty means "no expectation was wired", and the
+     * reconciliation stays silent rather than reporting every capability as
+     * unexposed; `index.ts` supplies the real list.
+     */
+    expectedDaemonMethods?: readonly string[]);
     /**
      * Sink for facts that cannot be attached to any request of the caller: a
      * late reply, a frame with an id this client never issued, a daemon that
@@ -462,6 +487,8 @@ export declare function unixSocketEngineClient(socketPath: string, options?: {
     callerCeilingMs?: number;
     /** Pass `"http"` from the gateway: its callers have no operation trail. */
     surface?: ShellSurface;
+    /** Daemon methods this shell forwards; see {@link EngineJsonRpcClient}'s last parameter. */
+    expectedDaemonMethods?: readonly string[];
 }): EngineJsonRpcClient;
 /**
  * Build a client over an existing LineIo (used by tests with a fake

package/dist/errors.d.ts

@@ -9,6 +9,12 @@ export declare const GP_E_NO_EVIDENCE = "GP_E_NO_EVIDENCE";
 export declare const GP_E_INTERNAL = "GP_E_INTERNAL";
 export declare const GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 export declare const GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
+/** Shell-only: the table changed between our read and our write, so we refused
+ * to overwrite. The daemon has no such code (it owns one writer), and every other
+ * code this shell raises for itself is listed with it in
+ * `test/remedy-surface.test.mjs`'s SHELL_ONLY set — a code outside the vocabulary
+ * with no remedy arm reads to an agent as "retry the same write". */
+export declare const GP_E_REGISTRY_DRIFT = "GP_E_REGISTRY_DRIFT";
 /**
  * Codes this shell raises for itself, in one place so a string literal cannot
  * exist twice with different spellings (X-15).

package/dist/http-gateway-cli.js

@@ -141,6 +141,7 @@ var StreamLineIo = class {
     this.input.destroy();
   }
 };
+var STDIO_WRITE_BACKLOG_BYTES = 32 * 1024 * 1024;
 
 // src/errors.ts
 var GP_E_ENGINE_UNREACHABLE = "GP_E_ENGINE_UNREACHABLE";
@@ -149,6 +150,7 @@ var GP_E_NO_EVIDENCE = "GP_E_NO_EVIDENCE";
 var GP_E_INTERNAL = "GP_E_INTERNAL";
 var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
+var GP_E_REGISTRY_DRIFT = "GP_E_REGISTRY_DRIFT";
 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";
@@ -223,6 +225,24 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+function describeCapabilityDrift(advertised, forwarded) {
+  if (advertised === null) {
+    return "engine self-report carries no capabilities list, so this shell cannot say which daemon methods it measured; every tool result in this session is unverified against the daemon's own method table (an engine older than the capability list, or a hello that was cut short)";
+  }
+  const missing = forwarded.filter((method) => !advertised.includes(method));
+  const unexposed = advertised.filter((method) => !forwarded.includes(method));
+  if (missing.length === 0 && unexposed.length === 0) {
+    return null;
+  }
+  const parts = [];
+  if (missing.length > 0) {
+    parts.push(`this shell forwards ${missing.join(", ")} but the daemon's hello does not list it/them \u2014 that call will be answered methodNotFound, so the tool surface and the engine method table have drifted`);
+  }
+  if (unexposed.length > 0) {
+    parts.push(`the daemon offers ${unexposed.join(", ")} which this shell does not expose as a tool \u2014 not an error, but the agent cannot reach it from MCP`);
+  }
+  return `capability reconciliation: ${parts.join("; ")}`;
+}
 var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
@@ -307,12 +327,13 @@ function slowEngineRemedy(method, surface = "mcp") {
 var LATE_REPLY_RETENTION = 16;
 var LOG_BODY_CHARS = 64 * 1024;
 var EngineJsonRpcClient = class {
-  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp") {
+  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
     this.io = io;
     this.timeoutMs = timeoutMs;
     this.identity = identity;
     this.callerCeilingMs = callerCeilingMs;
     this.surface = surface;
+    this.expectedDaemonMethods = expectedDaemonMethods;
     this.io.onMessage((line) => this.handleMessage(line));
     this.io.onError((error) => {
       if (error instanceof OversizeFrameError) {
@@ -337,6 +358,7 @@ var EngineJsonRpcClient = class {
   identity;
   callerCeilingMs;
   surface;
+  expectedDaemonMethods;
   /**
    * Every mutable piece of this client's state, in one object that is *never*
    * reassigned through `this`.
@@ -753,6 +775,13 @@ var EngineJsonRpcClient = class {
     if (version !== null && wantVersion !== void 0 && version !== wantVersion) {
       this.report(`version mismatch: engine self-reports '${version}', this MCP shell ships '${wantVersion}' (single version line) \u2014 one side is stale`);
     }
+    if (this.expectedDaemonMethods.length > 0) {
+      const advertised = Array.isArray(report.capabilities) ? report.capabilities.filter((item) => typeof item === "string") : null;
+      const drift = describeCapabilityDrift(advertised, this.expectedDaemonMethods);
+      if (drift !== null) {
+        this.report(drift);
+      }
+    }
   }
 };
 function attribute(error, entry, inferred = true) {
@@ -847,7 +876,8 @@ function unixSocketEngineClient(socketPath, options = {}) {
     void 0,
     options.identity ?? null,
     options.callerCeilingMs ?? CALLER_VISIBLE_CEILING_MS,
-    options.surface ?? "mcp"
+    options.surface ?? "mcp",
+    options.expectedDaemonMethods ?? []
   );
 }
 
@@ -1569,7 +1599,7 @@ function registryDriftReason(filePath, openedAs, now) {
 function assertNoConcurrentWrite(filePath, openedAs) {
   const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
   if (reason !== null) {
-    throw new ProjectRegistryError("registry-changed-underneath", reason);
+    throw new ProjectRegistryError(GP_E_REGISTRY_DRIFT, reason);
   }
 }
 function saveProjects(filePath, entries) {
@@ -1887,7 +1917,7 @@ var ProjectRegistryError = class extends Error {
 var PID_INT32_MAX = 2147483647;
 var OptionalPidSchema = z5.number().int().min(1).max(PID_INT32_MAX).optional();
 var OptionalDepthSchema = z5.number().int().min(1).max(10).optional();
-var OptionalRoleSchema = z5.string().max(SELECTOR_MAX_LENGTH).optional();
+var OptionalRoleSchema = z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional();
 var OptionalBundleIdSchema = z5.string().max(512).optional();
 var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
@@ -2269,6 +2299,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -2588,6 +2619,9 @@ function projectErrorRemedy(code) {
   if (code === GP_E_NOT_FOUND) {
     return "check the projectId; use gp_project_list to view available projects";
   }
+  if (code === GP_E_REGISTRY_DRIFT) {
+    return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
+  }
   if (code === GP_E_NO_USER_RECORD) {
     return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
   }
@@ -3433,6 +3467,8 @@ function httpStatusForEngineCode(code) {
       return 503;
     case GP_E_ENGINE_TIMEOUT:
       return 504;
+    case GP_E_REGISTRY_DRIFT:
+      return 503;
     case GP_E_PAYLOAD_TOO_LARGE:
       return 502;
     case GP_E_INTERNAL:

package/dist/http-gateway.js

@@ -141,6 +141,7 @@ var StreamLineIo = class {
     this.input.destroy();
   }
 };
+var STDIO_WRITE_BACKLOG_BYTES = 32 * 1024 * 1024;
 
 // src/errors.ts
 var GP_E_ENGINE_UNREACHABLE = "GP_E_ENGINE_UNREACHABLE";
@@ -149,6 +150,7 @@ var GP_E_NO_EVIDENCE = "GP_E_NO_EVIDENCE";
 var GP_E_INTERNAL = "GP_E_INTERNAL";
 var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
+var GP_E_REGISTRY_DRIFT = "GP_E_REGISTRY_DRIFT";
 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";
@@ -219,6 +221,24 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+function describeCapabilityDrift(advertised, forwarded) {
+  if (advertised === null) {
+    return "engine self-report carries no capabilities list, so this shell cannot say which daemon methods it measured; every tool result in this session is unverified against the daemon's own method table (an engine older than the capability list, or a hello that was cut short)";
+  }
+  const missing = forwarded.filter((method) => !advertised.includes(method));
+  const unexposed = advertised.filter((method) => !forwarded.includes(method));
+  if (missing.length === 0 && unexposed.length === 0) {
+    return null;
+  }
+  const parts = [];
+  if (missing.length > 0) {
+    parts.push(`this shell forwards ${missing.join(", ")} but the daemon's hello does not list it/them \u2014 that call will be answered methodNotFound, so the tool surface and the engine method table have drifted`);
+  }
+  if (unexposed.length > 0) {
+    parts.push(`the daemon offers ${unexposed.join(", ")} which this shell does not expose as a tool \u2014 not an error, but the agent cannot reach it from MCP`);
+  }
+  return `capability reconciliation: ${parts.join("; ")}`;
+}
 var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
@@ -303,12 +323,13 @@ function slowEngineRemedy(method, surface = "mcp") {
 var LATE_REPLY_RETENTION = 16;
 var LOG_BODY_CHARS = 64 * 1024;
 var EngineJsonRpcClient = class {
-  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp") {
+  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
     this.io = io;
     this.timeoutMs = timeoutMs;
     this.identity = identity;
     this.callerCeilingMs = callerCeilingMs;
     this.surface = surface;
+    this.expectedDaemonMethods = expectedDaemonMethods;
     this.io.onMessage((line) => this.handleMessage(line));
     this.io.onError((error) => {
       if (error instanceof OversizeFrameError) {
@@ -333,6 +354,7 @@ var EngineJsonRpcClient = class {
   identity;
   callerCeilingMs;
   surface;
+  expectedDaemonMethods;
   /**
    * Every mutable piece of this client's state, in one object that is *never*
    * reassigned through `this`.
@@ -749,6 +771,13 @@ var EngineJsonRpcClient = class {
     if (version !== null && wantVersion !== void 0 && version !== wantVersion) {
       this.report(`version mismatch: engine self-reports '${version}', this MCP shell ships '${wantVersion}' (single version line) \u2014 one side is stale`);
     }
+    if (this.expectedDaemonMethods.length > 0) {
+      const advertised = Array.isArray(report.capabilities) ? report.capabilities.filter((item) => typeof item === "string") : null;
+      const drift = describeCapabilityDrift(advertised, this.expectedDaemonMethods);
+      if (drift !== null) {
+        this.report(drift);
+      }
+    }
   }
 };
 function attribute(error, entry, inferred = true) {
@@ -843,7 +872,8 @@ function unixSocketEngineClient(socketPath, options = {}) {
     void 0,
     options.identity ?? null,
     options.callerCeilingMs ?? CALLER_VISIBLE_CEILING_MS,
-    options.surface ?? "mcp"
+    options.surface ?? "mcp",
+    options.expectedDaemonMethods ?? []
   );
 }
 
@@ -1559,7 +1589,7 @@ function registryDriftReason(filePath, openedAs, now) {
 function assertNoConcurrentWrite(filePath, openedAs) {
   const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
   if (reason !== null) {
-    throw new ProjectRegistryError("registry-changed-underneath", reason);
+    throw new ProjectRegistryError(GP_E_REGISTRY_DRIFT, reason);
   }
 }
 function saveProjects(filePath, entries) {
@@ -1877,7 +1907,7 @@ var ProjectRegistryError = class extends Error {
 var PID_INT32_MAX = 2147483647;
 var OptionalPidSchema = z5.number().int().min(1).max(PID_INT32_MAX).optional();
 var OptionalDepthSchema = z5.number().int().min(1).max(10).optional();
-var OptionalRoleSchema = z5.string().max(SELECTOR_MAX_LENGTH).optional();
+var OptionalRoleSchema = z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional();
 var OptionalBundleIdSchema = z5.string().max(512).optional();
 var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
@@ -2259,6 +2289,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -2578,6 +2609,9 @@ function projectErrorRemedy(code) {
   if (code === GP_E_NOT_FOUND) {
     return "check the projectId; use gp_project_list to view available projects";
   }
+  if (code === GP_E_REGISTRY_DRIFT) {
+    return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
+  }
   if (code === GP_E_NO_USER_RECORD) {
     return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
   }
@@ -3423,6 +3457,8 @@ function httpStatusForEngineCode(code) {
       return 503;
     case GP_E_ENGINE_TIMEOUT:
       return 504;
+    case GP_E_REGISTRY_DRIFT:
+      return 503;
     case GP_E_PAYLOAD_TOO_LARGE:
       return 502;
     case GP_E_INTERNAL:

package/dist/index.js

@@ -495,6 +495,30 @@ function readUpdateState(env = process.env, stateRootOverride) {
       summary: `update state: no ${stateFile} \u2014 auto-update has never run on this machine, so nothing here says the installed GlassPane is current; run \`node updater/cli.js check\` (or use the settings panel) to find out`
     };
   }
+  let stat;
+  try {
+    stat = fs.statSync(stateFile);
+  } catch (error) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} exists but could not be stat-ed (${String(error)}); freshness is unknown, which is not the same as up to date`
+    };
+  }
+  if (!stat.isFile()) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} is not a regular file (mode ${(stat.mode & 511).toString(8)}), so nothing was parsed from it; freshness is unknown, which is not the same as up to date`
+    };
+  }
+  if ((stat.mode & 63) !== 0) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} is mode ${(stat.mode & 511).toString(8)} \u2014 group/world readable, so this reader will not present it as the owner-only document it claims to be. Run \`chmod 600 ${stateFile}\` (the updater writes it 0600) and read again; freshness stays unknown, which is not the same as up to date`
+    };
+  }
   let text;
   try {
     text = fs.readFileSync(stateFile, "utf8");
@@ -729,12 +753,14 @@ var OrderedReplyQueue = class {
     return this.tail;
   }
 };
+var STDIO_WRITE_BACKLOG_BYTES = 32 * 1024 * 1024;
 var DrainAwareWriter = class {
-  constructor(sink, report, drainWaitMs, onDead) {
+  constructor(sink, report, drainWaitMs, onDead, backlogLimitBytes = STDIO_WRITE_BACKLOG_BYTES) {
     this.sink = sink;
     this.report = report;
     this.drainWaitMs = drainWaitMs;
     this.onDead = onDead;
+    this.backlogLimitBytes = backlogLimitBytes;
     sink.on("error", (error) => {
       if (this.dead) {
         return;
@@ -748,15 +774,27 @@ var DrainAwareWriter = class {
   report;
   drainWaitMs;
   onDead;
+  backlogLimitBytes;
   dead = null;
+  dropped = 0;
   get failed() {
     return this.dead !== null;
   }
+  /** How many replies this writer refused to queue. `gp_diagnose` reads it: a
+   * silently-shrinking answer is the failure mode this ceiling replaces. */
+  get droppedFrames() {
+    return this.dropped;
+  }
   /** @param text already framed, including its trailing newline. */
   async write(text) {
     if (this.failed) {
       return false;
     }
+    if (this.sink.writableLength >= this.backlogLimitBytes) {
+      this.dropped += 1;
+      this.report(`reply dropped, not queued: stdout already holds ${this.sink.writableLength} bytes past the ${this.backlogLimitBytes} ceiling \u2014 the reader on the other end stopped consuming, so this frame (and ${this.dropped - 1} earlier one(s)) will not be delivered`);
+      return false;
+    }
     let flowing = true;
     try {
       flowing = this.sink.write(text);
@@ -809,6 +847,7 @@ var GP_E_NO_EVIDENCE = "GP_E_NO_EVIDENCE";
 var GP_E_INTERNAL = "GP_E_INTERNAL";
 var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
+var GP_E_REGISTRY_DRIFT = "GP_E_REGISTRY_DRIFT";
 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";
@@ -883,6 +922,24 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+function describeCapabilityDrift(advertised, forwarded) {
+  if (advertised === null) {
+    return "engine self-report carries no capabilities list, so this shell cannot say which daemon methods it measured; every tool result in this session is unverified against the daemon's own method table (an engine older than the capability list, or a hello that was cut short)";
+  }
+  const missing = forwarded.filter((method) => !advertised.includes(method));
+  const unexposed = advertised.filter((method) => !forwarded.includes(method));
+  if (missing.length === 0 && unexposed.length === 0) {
+    return null;
+  }
+  const parts = [];
+  if (missing.length > 0) {
+    parts.push(`this shell forwards ${missing.join(", ")} but the daemon's hello does not list it/them \u2014 that call will be answered methodNotFound, so the tool surface and the engine method table have drifted`);
+  }
+  if (unexposed.length > 0) {
+    parts.push(`the daemon offers ${unexposed.join(", ")} which this shell does not expose as a tool \u2014 not an error, but the agent cannot reach it from MCP`);
+  }
+  return `capability reconciliation: ${parts.join("; ")}`;
+}
 var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
@@ -967,12 +1024,13 @@ function slowEngineRemedy(method, surface = "mcp") {
 var LATE_REPLY_RETENTION = 16;
 var LOG_BODY_CHARS = 64 * 1024;
 var EngineJsonRpcClient = class {
-  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp") {
+  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp", expectedDaemonMethods = []) {
     this.io = io;
     this.timeoutMs = timeoutMs;
     this.identity = identity;
     this.callerCeilingMs = callerCeilingMs;
     this.surface = surface;
+    this.expectedDaemonMethods = expectedDaemonMethods;
     this.io.onMessage((line) => this.handleMessage(line));
     this.io.onError((error) => {
       if (error instanceof OversizeFrameError) {
@@ -997,6 +1055,7 @@ var EngineJsonRpcClient = class {
   identity;
   callerCeilingMs;
   surface;
+  expectedDaemonMethods;
   /**
    * Every mutable piece of this client's state, in one object that is *never*
    * reassigned through `this`.
@@ -1413,6 +1472,13 @@ var EngineJsonRpcClient = class {
     if (version !== null && wantVersion !== void 0 && version !== wantVersion) {
       this.report(`version mismatch: engine self-reports '${version}', this MCP shell ships '${wantVersion}' (single version line) \u2014 one side is stale`);
     }
+    if (this.expectedDaemonMethods.length > 0) {
+      const advertised = Array.isArray(report.capabilities) ? report.capabilities.filter((item) => typeof item === "string") : null;
+      const drift = describeCapabilityDrift(advertised, this.expectedDaemonMethods);
+      if (drift !== null) {
+        this.report(drift);
+      }
+    }
   }
 };
 function attribute(error, entry, inferred = true) {
@@ -1507,7 +1573,8 @@ function unixSocketEngineClient(socketPath, options = {}) {
     void 0,
     options.identity ?? null,
     options.callerCeilingMs ?? CALLER_VISIBLE_CEILING_MS,
-    options.surface ?? "mcp"
+    options.surface ?? "mcp",
+    options.expectedDaemonMethods ?? []
   );
 }
 
@@ -1945,7 +2012,7 @@ function registryDriftReason(filePath, openedAs, now) {
 function assertNoConcurrentWrite(filePath, openedAs) {
   const reason = registryDriftReason(filePath, openedAs, fileIdentity(filePath));
   if (reason !== null) {
-    throw new ProjectRegistryError("registry-changed-underneath", reason);
+    throw new ProjectRegistryError(GP_E_REGISTRY_DRIFT, reason);
   }
 }
 function saveProjects(filePath, entries) {
@@ -2263,7 +2330,7 @@ var ProjectRegistryError = class extends Error {
 var PID_INT32_MAX = 2147483647;
 var OptionalPidSchema = z5.number().int().min(1).max(PID_INT32_MAX).optional();
 var OptionalDepthSchema = z5.number().int().min(1).max(10).optional();
-var OptionalRoleSchema = z5.string().max(SELECTOR_MAX_LENGTH).optional();
+var OptionalRoleSchema = z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional();
 var OptionalBundleIdSchema = z5.string().max(512).optional();
 var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
@@ -2645,6 +2712,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -3209,6 +3277,9 @@ function projectErrorRemedy(code) {
   if (code === GP_E_NOT_FOUND) {
     return "check the projectId; use gp_project_list to view available projects";
   }
+  if (code === GP_E_REGISTRY_DRIFT) {
+    return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
+  }
   if (code === GP_E_NO_USER_RECORD) {
     return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
   }
@@ -3722,7 +3793,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.12.2" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.13.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -4016,7 +4087,10 @@ function main() {
   let engine;
   try {
     engine = unixSocketEngineClient(options.socketPath, {
-      identity: { version: SERVER_INFO.version }
+      identity: { version: SERVER_INFO.version },
+      // `hello.capabilities` 的读者在这一层接线：清单由 daemon 派生、由这里与 TOOL_SPECS
+      // 对账，两边谁漂了都会有人说，而不是各自安静地活着。
+      expectedDaemonMethods: DAEMON_FORWARDED_METHODS
     });
   } catch (error) {
     writeDescriptor(

package/dist/io.d.ts

@@ -131,6 +131,15 @@ export declare class OrderedReplyQueue {
     /** Resolves once everything queued so far has been attempted. */
     drained(): Promise<void>;
 }
+/**
+ * 回包在 stdout 队列里允许的积压上限。镜像方向的同一件事早就有闸（`engine-client.ts` 的
+ * `ENGINE_WRITE_BACKLOG_BYTES` + 自己的错误码），stdio 这一侧却只说过"有 DrainAwareWriter
+ * 管背压"——串行化不等于**有界**：30s 的 drain 看门狗一响，后面的 `write()` 照样继续往
+ * Node 的队列里塞，一个不读了客户端就能把 `gp_recent_reports`（20 × 4 MiB，且这层没有
+ * 出站帧长上限）变成无界内存。到线就丢这一帧、点名丢了谁、说清为什么，比让进程被 OOM
+ * 杀掉后再也答不出第 21 条更好。
+ */
+export declare const STDIO_WRITE_BACKLOG_BYTES: number;
 /**
  * Writes with backpressure honoured and a dead pipe survived: an ignored
  * `write()` return lets replies pile up in memory, and an unlistened `error`
@@ -141,9 +150,14 @@ export declare class DrainAwareWriter {
     private readonly report;
     private readonly drainWaitMs;
     private readonly onDead;
+    private readonly backlogLimitBytes;
     private dead;
-    constructor(sink: Writable, report: (note: string) => void, drainWaitMs: number, onDead: (error: Error) => void);
+    private dropped;
+    constructor(sink: Writable, report: (note: string) => void, drainWaitMs: number, onDead: (error: Error) => void, backlogLimitBytes?: number);
     get failed(): boolean;
+    /** How many replies this writer refused to queue. `gp_diagnose` reads it: a
+     * silently-shrinking answer is the failure mode this ceiling replaces. */
+    get droppedFrames(): number;
     /** @param text already framed, including its trailing newline. */
     write(text: string): Promise<boolean>;
     private waitForDrain;

package/dist/tools.d.ts

@@ -288,6 +288,14 @@ export interface ToolResult {
     isError: boolean;
 }
 export declare const TOOL_SPECS: readonly ToolSpec[];
+/**
+ * The daemon methods this shell forwards, derived from {@link TOOL_SPECS} rather
+ * than written out. This is the list `hello.capabilities` is reconciled against
+ * (`engine-client.describeCapabilityDrift`): a hand-copied second truth is the
+ * exact drift the reader exists to catch, and the gateway already derives its own
+ * forwardable set from `execute === undefined` for the same reason.
+ */
+export declare const DAEMON_FORWARDED_METHODS: readonly string[];
 export declare const TOOL_BY_NAME: ReadonlyMap<string, ToolSpec>;
 /** Does this tool read or write `EvidenceAuditSession`? */
 export declare function trailScopedTool(spec: ToolSpec): boolean;

package/package.json

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