glasspane-mcp 1.10.0 → 1.12.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.10.0";
+    readonly version: "1.12.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/http-gateway-cli.js

@@ -533,8 +533,9 @@ var EngineJsonRpcClient = class {
           return;
         }
         if (frame.error) {
-          this.pending.delete(target.id);
           this.reject(target, attribute(this.engineError(frame.error), target));
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
@@ -633,8 +634,9 @@ var EngineJsonRpcClient = class {
       );
       return;
     }
+    const bodyBytes = Buffer.byteLength(jsonOrString(frame.result), "utf8");
     this.report(
-      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: ${truncate(jsonOrString(frame.result))}${byOrder}`
+      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: the engine did answer, with a ${bodyBytes}-byte body that is raw engine content (an accessibility tree whose title/value fields are on-screen data), so its text is not written to this log${byOrder}`
     );
     if (frame.result === void 0) {
       return;
@@ -817,7 +819,7 @@ var ReconnectingSocketIo = class {
     const io = new StreamLineIo(socket, socket);
     io.onMessage((line) => this.messageHandler?.(line));
     io.onError((error) => {
-      if (this.inner === io) {
+      if (!(error instanceof OversizeFrameError) && this.inner === io) {
         this.inner = null;
         io.close();
       }
@@ -1885,8 +1887,8 @@ 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(128).optional();
-var OptionalBundleIdSchema = z5.string().max(256).optional();
+var OptionalRoleSchema = z5.string().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();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
@@ -2002,7 +2004,7 @@ var TOOL_SPECS = [
       type: "object",
       additionalProperties: false,
       properties: {
-        bundleId: { type: "string", maxLength: 256 },
+        bundleId: { type: "string", maxLength: 512 },
         pid: { type: "integer", minimum: 1, maximum: PID_INT32_MAX },
         projectId: { type: "string", pattern: "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }
       },
@@ -2022,7 +2024,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: 128 }
+        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -2370,6 +2372,9 @@ var NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
   ...REPLAY_UNSAFE_METHOD_NAMES,
   ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
 ]);
+function isNarrowableByRetryMethod(method) {
+  return !NOT_NARROWABLE_BY_RETRY.has(method);
+}
 async function readTrail(session, turn, limit) {
   await turn.acquire();
   try {
@@ -2378,6 +2383,17 @@ async function readTrail(session, turn, limit) {
     turn.release();
   }
 }
+function shellFaultRemedy(engineMethod) {
+  const readRoute = "read what happened instead of performing it again: gp_recent_reports lists the operations this session recorded, gp_last_evidence {operationId} returns one in full, and gp_probe_status reads the daemon's own self-report on this same connection \u2014 all three are requests this shell does not treat as unsafe to repeat";
+  const reportRoute = "this fault was raised inside the MCP shell, so it is in no daemon log: this process's stderr belongs to whoever started this server, and that line is the only text naming the failure, so hand it to them verbatim. A daemon restart is not authorised by an answer the daemon never made";
+  if (isReplayUnsafeMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine, so it measures nothing about whether '${engineMethod}' reached the daemon or the user's screen. Do NOT re-issue ${engineMethod}: a re-issue can perform the same action a second time on the user's screen (and for attach, re-point the daemon and discard the trail an outstanding request is being recorded in), and this failure does not establish that the first copy did nothing. ${readRoute}. ${reportRoute}`;
+  }
+  if (!isNarrowableByRetryMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is a method whose re-issue writes daemon state \u2014 a fresh request appends to the bounded snapshot ring and can evict a baseline this caller already received \u2014 so treat it as a question to read around rather than one to send again: gp_snapshot lists stored ids, and ${readRoute}. ${reportRoute}`;
+  }
+  return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is not one of the methods this shell classifies as unsafe to repeat (the no-replay set is act/restore/attach, plus snapshot, whose re-issue writes daemon state), so sending this tool again is a real option rather than a side effect: do that once. If the fault repeats, ${readRoute}. ${reportRoute}`;
+}
 var EvidenceFrameShapeError = class extends Error {
   constructor(detail) {
     super(`engine returned a last_evidence frame without an evidencePack object: ${detail}`);
@@ -2433,7 +2449,17 @@ async function captureView(args, context) {
         isError: true
       };
     }
-    const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
+    if (typeof body.mimeType !== "string" || body.mimeType.length === 0) {
+      return {
+        content: [{ type: "text", text: formatToolError(
+          GP_E_INTERNAL,
+          `capture_view answered without a mimeType (got ${JSON.stringify(body.mimeType ?? null)})`,
+          "do not read this image as any particular format: the engine did not name one, and this shell will not fill the field in. This is a read-only capture, so sending it again performs nothing \u2014 if it repeats, report the frame shape, which is a protocol disagreement between two builds rather than a dead daemon"
+        ) }],
+        isError: true
+      };
+    }
+    const mimeType = body.mimeType;
     const summary = canonicalJson2({
       mimeType,
       byteCount: body.byteCount,
@@ -2465,7 +2491,7 @@ async function captureView(args, context) {
       content: [{ type: "text", text: formatToolError(
         GP_E_INTERNAL,
         `internal shell error: ${String(error)}`,
-        "see the MCP server logs and retry"
+        shellFaultRemedy("capture_view")
       ) }],
       isError: true
     };
@@ -2566,7 +2592,7 @@ function projectErrorRemedy(code) {
     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";
   }
   if (code === GP_E_INTERNAL) {
-    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`python3 -m json.tool <that path>\`, repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
+    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`/usr/bin/plutil -p <that path>\` or \`/bin/cat <that path>\` \u2014 both absolute, so they run from whatever directory the reader is in and need nothing that may be off PATH \u2014 repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
   }
   return "check the tool's input schema and retry";
 }
@@ -2641,7 +2667,7 @@ function renderTrailIds(ids, format) {
 }
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
-    return `${error.code}: ${error.message}`;
+    return formatToolErrorShape(error.toBody());
   }
   const mapped = mapEvidenceReadError(error);
   if (mapped !== void 0) {
@@ -2762,8 +2788,8 @@ async function recentReports(args, context) {
     return {
       content: [{ type: "text", text: formatToolError(
         GP_E_NO_EVIDENCE,
-        "no recent evidence is reachable in the daemon history",
-        "the engine may have restarted; re-run gp_act / gp_assert_element to regenerate evidence"
+        `no pack is reachable in the daemon history for any of the ${ids.length} ${ids.length === 1 ? "operation" : "operations"} this shell asked about: each was answered GP_E_NO_EVIDENCE (${renderTrailIds(skipped, format)})`,
+        "these operations are recorded in this session's trail, and the daemon holding no pack for them is a fact about its bounded history, not evidence that they did not run \u2014 this call measured nothing about a restart, so no cause is claimed here. Read one of them by id with gp_last_evidence {operationId} / gp_export_evidence {operationId}, or ask again with a smaller limit (gp_recent_reports advertises 1\u202620). Do not re-run gp_act to regenerate what the trail already holds"
       ) }],
       isError: true
     };
@@ -2786,7 +2812,7 @@ async function recentReports(args, context) {
   sections2.push(body);
   return { content: [{ type: "text", text: sections2.join("\n") }], isError: false };
 }
-function mapAuditError(error) {
+function mapAuditError(error, engineMethod = "last_evidence") {
   if (error instanceof EngineCallError) {
     return {
       content: [{ type: "text", text: formatToolErrorShape(error.toBody()) }],
@@ -2801,7 +2827,7 @@ function mapAuditError(error) {
     content: [{ type: "text", text: formatToolError(
       GP_E_INTERNAL,
       `internal shell error: ${String(error)}`,
-      "see the MCP server logs and retry"
+      shellFaultRemedy(engineMethod)
     ) }],
     isError: true
   };

package/dist/http-gateway.js

@@ -529,8 +529,9 @@ var EngineJsonRpcClient = class {
           return;
         }
         if (frame.error) {
-          this.pending.delete(target.id);
           this.reject(target, attribute(this.engineError(frame.error), target));
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
@@ -629,8 +630,9 @@ var EngineJsonRpcClient = class {
       );
       return;
     }
+    const bodyBytes = Buffer.byteLength(jsonOrString(frame.result), "utf8");
     this.report(
-      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: ${truncate(jsonOrString(frame.result))}${byOrder}`
+      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: the engine did answer, with a ${bodyBytes}-byte body that is raw engine content (an accessibility tree whose title/value fields are on-screen data), so its text is not written to this log${byOrder}`
     );
     if (frame.result === void 0) {
       return;
@@ -813,7 +815,7 @@ var ReconnectingSocketIo = class {
     const io = new StreamLineIo(socket, socket);
     io.onMessage((line) => this.messageHandler?.(line));
     io.onError((error) => {
-      if (this.inner === io) {
+      if (!(error instanceof OversizeFrameError) && this.inner === io) {
         this.inner = null;
         io.close();
       }
@@ -1875,8 +1877,8 @@ 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(128).optional();
-var OptionalBundleIdSchema = z5.string().max(256).optional();
+var OptionalRoleSchema = z5.string().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();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
@@ -1992,7 +1994,7 @@ var TOOL_SPECS = [
       type: "object",
       additionalProperties: false,
       properties: {
-        bundleId: { type: "string", maxLength: 256 },
+        bundleId: { type: "string", maxLength: 512 },
         pid: { type: "integer", minimum: 1, maximum: PID_INT32_MAX },
         projectId: { type: "string", pattern: "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }
       },
@@ -2012,7 +2014,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: 128 }
+        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -2360,6 +2362,9 @@ var NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
   ...REPLAY_UNSAFE_METHOD_NAMES,
   ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
 ]);
+function isNarrowableByRetryMethod(method) {
+  return !NOT_NARROWABLE_BY_RETRY.has(method);
+}
 async function readTrail(session, turn, limit) {
   await turn.acquire();
   try {
@@ -2368,6 +2373,17 @@ async function readTrail(session, turn, limit) {
     turn.release();
   }
 }
+function shellFaultRemedy(engineMethod) {
+  const readRoute = "read what happened instead of performing it again: gp_recent_reports lists the operations this session recorded, gp_last_evidence {operationId} returns one in full, and gp_probe_status reads the daemon's own self-report on this same connection \u2014 all three are requests this shell does not treat as unsafe to repeat";
+  const reportRoute = "this fault was raised inside the MCP shell, so it is in no daemon log: this process's stderr belongs to whoever started this server, and that line is the only text naming the failure, so hand it to them verbatim. A daemon restart is not authorised by an answer the daemon never made";
+  if (isReplayUnsafeMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine, so it measures nothing about whether '${engineMethod}' reached the daemon or the user's screen. Do NOT re-issue ${engineMethod}: a re-issue can perform the same action a second time on the user's screen (and for attach, re-point the daemon and discard the trail an outstanding request is being recorded in), and this failure does not establish that the first copy did nothing. ${readRoute}. ${reportRoute}`;
+  }
+  if (!isNarrowableByRetryMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is a method whose re-issue writes daemon state \u2014 a fresh request appends to the bounded snapshot ring and can evict a baseline this caller already received \u2014 so treat it as a question to read around rather than one to send again: gp_snapshot lists stored ids, and ${readRoute}. ${reportRoute}`;
+  }
+  return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is not one of the methods this shell classifies as unsafe to repeat (the no-replay set is act/restore/attach, plus snapshot, whose re-issue writes daemon state), so sending this tool again is a real option rather than a side effect: do that once. If the fault repeats, ${readRoute}. ${reportRoute}`;
+}
 var EvidenceFrameShapeError = class extends Error {
   constructor(detail) {
     super(`engine returned a last_evidence frame without an evidencePack object: ${detail}`);
@@ -2423,7 +2439,17 @@ async function captureView(args, context) {
         isError: true
       };
     }
-    const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
+    if (typeof body.mimeType !== "string" || body.mimeType.length === 0) {
+      return {
+        content: [{ type: "text", text: formatToolError(
+          GP_E_INTERNAL,
+          `capture_view answered without a mimeType (got ${JSON.stringify(body.mimeType ?? null)})`,
+          "do not read this image as any particular format: the engine did not name one, and this shell will not fill the field in. This is a read-only capture, so sending it again performs nothing \u2014 if it repeats, report the frame shape, which is a protocol disagreement between two builds rather than a dead daemon"
+        ) }],
+        isError: true
+      };
+    }
+    const mimeType = body.mimeType;
     const summary = canonicalJson2({
       mimeType,
       byteCount: body.byteCount,
@@ -2455,7 +2481,7 @@ async function captureView(args, context) {
       content: [{ type: "text", text: formatToolError(
         GP_E_INTERNAL,
         `internal shell error: ${String(error)}`,
-        "see the MCP server logs and retry"
+        shellFaultRemedy("capture_view")
       ) }],
       isError: true
     };
@@ -2556,7 +2582,7 @@ function projectErrorRemedy(code) {
     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";
   }
   if (code === GP_E_INTERNAL) {
-    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`python3 -m json.tool <that path>\`, repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
+    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`/usr/bin/plutil -p <that path>\` or \`/bin/cat <that path>\` \u2014 both absolute, so they run from whatever directory the reader is in and need nothing that may be off PATH \u2014 repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
   }
   return "check the tool's input schema and retry";
 }
@@ -2631,7 +2657,7 @@ function renderTrailIds(ids, format) {
 }
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
-    return `${error.code}: ${error.message}`;
+    return formatToolErrorShape(error.toBody());
   }
   const mapped = mapEvidenceReadError(error);
   if (mapped !== void 0) {
@@ -2752,8 +2778,8 @@ async function recentReports(args, context) {
     return {
       content: [{ type: "text", text: formatToolError(
         GP_E_NO_EVIDENCE,
-        "no recent evidence is reachable in the daemon history",
-        "the engine may have restarted; re-run gp_act / gp_assert_element to regenerate evidence"
+        `no pack is reachable in the daemon history for any of the ${ids.length} ${ids.length === 1 ? "operation" : "operations"} this shell asked about: each was answered GP_E_NO_EVIDENCE (${renderTrailIds(skipped, format)})`,
+        "these operations are recorded in this session's trail, and the daemon holding no pack for them is a fact about its bounded history, not evidence that they did not run \u2014 this call measured nothing about a restart, so no cause is claimed here. Read one of them by id with gp_last_evidence {operationId} / gp_export_evidence {operationId}, or ask again with a smaller limit (gp_recent_reports advertises 1\u202620). Do not re-run gp_act to regenerate what the trail already holds"
       ) }],
       isError: true
     };
@@ -2776,7 +2802,7 @@ async function recentReports(args, context) {
   sections2.push(body);
   return { content: [{ type: "text", text: sections2.join("\n") }], isError: false };
 }
-function mapAuditError(error) {
+function mapAuditError(error, engineMethod = "last_evidence") {
   if (error instanceof EngineCallError) {
     return {
       content: [{ type: "text", text: formatToolErrorShape(error.toBody()) }],
@@ -2791,7 +2817,7 @@ function mapAuditError(error) {
     content: [{ type: "text", text: formatToolError(
       GP_E_INTERNAL,
       `internal shell error: ${String(error)}`,
-      "see the MCP server logs and retry"
+      shellFaultRemedy(engineMethod)
     ) }],
     isError: true
   };

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import fs5 from "node:fs";
 import process2 from "node:process";
 
 // src/canonical.ts
@@ -24,6 +25,9 @@ function sortKeys(value) {
 
 // src/tools.ts
 import { z as z5 } from "zod";
+import fs4 from "node:fs";
+import path4 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../kernel/dist/schemas.js
 import { createRequire } from "node:module";
@@ -1189,8 +1193,9 @@ var EngineJsonRpcClient = class {
           return;
         }
         if (frame.error) {
-          this.pending.delete(target.id);
           this.reject(target, attribute(this.engineError(frame.error), target));
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         this.report(`engine sent an id-less frame with a result while '${target.method}' (id ${target.id}) is still waiting for its answer; an id-less answer from this daemon is an error frame, so this one was not delivered to any caller: ${truncate(line)}`);
@@ -1289,8 +1294,9 @@ var EngineJsonRpcClient = class {
       );
       return;
     }
+    const bodyBytes = Buffer.byteLength(jsonOrString(frame.result), "utf8");
     this.report(
-      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: ${truncate(jsonOrString(frame.result))}${byOrder}`
+      `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: the engine did answer, with a ${bodyBytes}-byte body that is raw engine content (an accessibility tree whose title/value fields are on-screen data), so its text is not written to this log${byOrder}`
     );
     if (frame.result === void 0) {
       return;
@@ -1473,7 +1479,7 @@ var ReconnectingSocketIo = class {
     const io = new StreamLineIo(socket, socket);
     io.onMessage((line) => this.messageHandler?.(line));
     io.onError((error) => {
-      if (this.inner === io) {
+      if (!(error instanceof OversizeFrameError) && this.inner === io) {
         this.inner = null;
         io.close();
       }
@@ -1505,243 +1511,6 @@ function unixSocketEngineClient(socketPath, options = {}) {
   );
 }
 
-// src/audit-session.ts
-var AUDIT_HISTORY_LIMIT = 20;
-var UNKNOWN_GENERATION = -1;
-function openTrailGate() {
-  let settle;
-  const settled = new Promise((resolve) => {
-    settle = () => resolve(void 0);
-  });
-  return { settled, settle };
-}
-var EvidenceAuditSession = class {
-  ids = [];
-  epoch = 0;
-  attachedAppKey = null;
-  /**
-   * Turns claimed but not released. This, not a "latest gate", is what a new
-   * claim waits for: a turn that abandons the trail (its engine call failed
-   * before any mutation) releases *out of order*, and a chain that only looked
-   * at the immediately preceding turn would let everything behind it run while
-   * an older, still-outstanding act had not written yet — the exact completion
-   * order the turn machinery exists to remove.
-   */
-  openGates = /* @__PURE__ */ new Set();
-  /**
-   * How each id in {@link ids} got here. Keyed by the id, because that is what a
-   * reader holds; the map is trimmed with the list and cleared when the trail
-   * restarts, so an id can never outlive the provenance that describes it.
-   */
-  provenance = /* @__PURE__ */ new Map();
-  /**
-   * Non-null while {@link recordLateArrival} holds the trail, and says how the
-   * frame being written was attributed. This is what lets a plain
-   * `trail.record(result)` inside that callback be filed as a late arrival without
-   * the caller having to remember to say so: the write happens inside a window only
-   * that method opens, so the mechanism is visible here rather than being a claim
-   * somebody must repeat at every call site.
-   */
-  lateWindow = null;
-  /**
-   * Record every operationId/evidenceId found in an engine result frame, tagged
-   * with the provenance of the path that is recording it (see
-   * {@link TrailProvenance}): `in-order` from a call that held its own trail turn,
-   * `late`/`late-inferred` from inside {@link recordLateArrival}.
-   */
-  record(result) {
-    const source = this.lateWindow === null ? "in-order" : this.lateWindow === "arrival-order" ? "late-inferred" : "late";
-    for (const id of collectOperationIds(result)) {
-      if (!this.ids.includes(id)) {
-        this.ids.push(id);
-        this.provenance.set(id, source);
-        if (this.ids.length > AUDIT_HISTORY_LIMIT) {
-          const evicted = this.ids.splice(0, this.ids.length - AUDIT_HISTORY_LIMIT);
-          for (const gone of evicted) {
-            this.provenance.delete(gone);
-          }
-        }
-      }
-    }
-  }
-  /**
-   * How one id in this trail got recorded, or null when the trail does not hold
-   * it — never recorded, evicted past {@link AUDIT_HISTORY_LIMIT}, or cleared by a
-   * {@link restart}. A reader that lists ids for an agent renders
-   * {@link TRAIL_PROVENANCE_NOTES} for anything that is not `in-order`: an id
-   * pulled from a frame this shell only *guessed* an owner for must not appear
-   * beside one it matched by id (R10-中2).
-   *
-   * Read off the map alone, so the map *is* the record of what the trail holds: an
-   * id whose provenance outlives its own entry would come back labelled as if it
-   * were still listed, and the eviction and the restart are the two places that
-   * would have to remember to delete. `test/engine-client.test.mjs` pins both.
-   */
-  provenanceOf(id) {
-    return this.provenance.get(id) ?? null;
-  }
-  /** The ids currently filed as inferred; see {@link TrailProvenance}. */
-  inferredIds() {
-    return this.ids.filter((id) => this.provenance.get(id) === "late-inferred");
-  }
-  /**
-   * The trail's generation number. Every {@link restart} bumps it.
-   *
-   * It exists so a reply that arrives *after* its caller was already answered
-   * can be judged against the trail it was written into: {@link recordLateArrival}
-   * takes the epoch the request was admitted under, and a mismatch means a
-   * re-attach happened in between. Without it, a late write lands in a *new*
-   * session's trail — an operationId from the previous app that
-   * `gp_recent_reports` then fetches and renders as if it belonged to this one
-   * (R8b-高1, measured: `['op_OLDAPP']` in the trail after attaching a second
-   * app).
-   */
-  get generation() {
-    return this.epoch;
-  }
-  /** The app the trail currently belongs to, or null before the first attach. */
-  get attachedApp() {
-    return this.attachedAppKey;
-  }
-  /**
-   * A successful attach: the trail restarts **only when the attached app
-   * changed**, because that is the daemon's own rule —
-   * `EngineCore.attach` clears `history` under
-   * `if attachedApp != app`, and its comment says re-attach to the same app is
-   * idempotent. Clearing on *every* attach (what this used to do) is strictly
-   * worse in two directions: an idempotent re-attach wiped operations that were
-   * really in the trail (including one recorded by a late reply, which put
-   * `gp_recent_reports` back to "run gp_act first"), and — because the clear
-   * happens whenever the reply lands — it could also drop the record of an act
-   * the daemon still has.
-   *
-   * `appKey` must be built from every stored property of Swift's `AttachedApp`
-   * (`pid`, `bundleId`, `appName`); a key that ignored `pid` would keep the
-   * trail across an app restart whose history the daemon did clear. The gate
-   * that pins this to the Swift struct is
-   * `test/attach-identity.test.mjs`.
-   *
-   * Returns whether the trail was restarted. A null `appKey` means the attach
-   * result did not identify the app at all, which is treated as a change: an
-   * unknown identity cannot be *shown* to be the same app, and a stale trail is
-   * the failure that misattributes evidence.
-   */
-  restart(appKey) {
-    if (appKey !== null && appKey === this.attachedAppKey) {
-      return false;
-    }
-    this.attachedAppKey = appKey;
-    this.ids = [];
-    this.provenance.clear();
-    this.epoch += 1;
-    return true;
-  }
-  /** The most recent `limit` recorded operationIds, oldest first. */
-  recentIds(limit) {
-    return this.ids.slice(-limit);
-  }
-  /**
-   * Record a frame that arrives with **no request of the caller still holding a
-   * turn**: a late engine reply (R8-高3, `EngineJsonRpcClient.onLateReply`). Its
-   * own turn was released the moment the timeout was reported to the agent, so
-   * there is no request-order position left to write at.
-   *
-   * It still goes through the turn machinery rather than a bare `record()`,
-   * because a direct write could land *between* two admitted calls and reorder
-   * the trail against the requests the agent made — the exact thing the turns
-   * exist to prevent. Claiming on arrival gives the only honest position left:
-   * behind whatever is still outstanding, and ordered among late arrivals by
-   * when they arrived.
-   *
-   * `admittedUnderGeneration` is compared **inside** that wait (see the body):
-   * the position and the epoch can only be judged at the moment the write
-   * actually happens. A reply whose request carried no generation cannot be
-   * placed either — so it is passed as {@link UNKNOWN_GENERATION} and the caller
-   * decides whether that is acceptable; this method refuses it by default, because
-   * "we do not know which attach this belongs to" is not a reason to write into
-   * somebody else's trail.
-   *
-   * `attribution` is how the transport matched that frame to a request, and it is
-   * the difference between `late` and `late-inferred` below: a frame that echoed
-   * the id the client sent is confirmed, one with no id is filed against the
-   * oldest tracked request by the daemon's in-order scheduling (R10-中2). Anything
-   * this method writes is a late arrival by construction, so the window opens
-   * whether or not the caller can say more — the default `unknown` is what the
-   * session can see on its own, and it is *not* `in-order`: an unconfirmed
-   * attribution must not read as a verified one.
-   */
-  recordLateArrival(apply, admittedUnderGeneration, attribution = "unknown") {
-    const turn = this.claimTrailTurn();
-    return turn.acquire().then(() => {
-      try {
-        if (admittedUnderGeneration !== this.epoch) {
-          return { written: false, generationAtWrite: this.epoch };
-        }
-        this.lateWindow = attribution;
-        apply(this);
-        return { written: true, generationAtWrite: this.epoch };
-      } finally {
-        this.lateWindow = null;
-        turn.release();
-      }
-    });
-  }
-  /**
-   * Claim the next position in this session's trail request order, so that
-   * overlapping calls mutate and read `ids` in the order they were admitted
-   * rather than in the order the daemon answered.
-   *
-   * Synchronous on purpose — a claim made after an `await` would itself be
-   * ordered by completion. Callers hold a turn only across a `record()` /
-   * `reset()` / `recentIds()`, never across an engine round trip, so the queue
-   * can delay the moment a reply is built but never a request at the daemon.
-   */
-  claimTrailTurn() {
-    const ahead = [...this.openGates];
-    const mine = openTrailGate();
-    this.openGates.add(mine);
-    let released = false;
-    return {
-      acquire: async () => {
-        await Promise.all(ahead.map((gate) => gate.settled));
-      },
-      release: () => {
-        if (released) {
-          return;
-        }
-        released = true;
-        this.openGates.delete(mine);
-        mine.settle();
-      }
-    };
-  }
-};
-function operationIds(value) {
-  return collectOperationIds(value);
-}
-function collectOperationIds(value, depth = 0) {
-  const out = [];
-  if (depth > 3 || value === null || typeof value !== "object") {
-    return out;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      out.push(...collectOperationIds(item, depth + 1));
-    }
-    return out;
-  }
-  const record = value;
-  for (const key of Object.keys(record)) {
-    const entry = record[key];
-    if ((key === "operationId" || key === "evidenceId") && typeof entry === "string") {
-      out.push(entry);
-    } else {
-      out.push(...collectOperationIds(entry, depth + 1));
-    }
-  }
-  return out;
-}
-
 // src/evidence-report.ts
 var PLACEHOLDER = "\u2014";
 function reportTitle(pack) {
@@ -2494,8 +2263,8 @@ 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(128).optional();
-var OptionalBundleIdSchema = z5.string().max(256).optional();
+var OptionalRoleSchema = z5.string().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();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
@@ -2611,7 +2380,7 @@ var TOOL_SPECS = [
       type: "object",
       additionalProperties: false,
       properties: {
-        bundleId: { type: "string", maxLength: 256 },
+        bundleId: { type: "string", maxLength: 512 },
         pid: { type: "integer", minimum: 1, maximum: PID_INT32_MAX },
         projectId: { type: "string", pattern: "^prj_[0-9A-HJKMNP-TV-Z]{26}$" }
       },
@@ -2631,7 +2400,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: 128 }
+        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -3047,7 +2816,28 @@ async function readTrail(session, turn, limit) {
     turn.release();
   }
 }
-async function executeTool(spec, args, engine, session = new EvidenceAuditSession()) {
+function shellFaultRemedy(engineMethod) {
+  const readRoute = "read what happened instead of performing it again: gp_recent_reports lists the operations this session recorded, gp_last_evidence {operationId} returns one in full, and gp_probe_status reads the daemon's own self-report on this same connection \u2014 all three are requests this shell does not treat as unsafe to repeat";
+  const reportRoute = "this fault was raised inside the MCP shell, so it is in no daemon log: this process's stderr belongs to whoever started this server, and that line is the only text naming the failure, so hand it to them verbatim. A daemon restart is not authorised by an answer the daemon never made";
+  if (isReplayUnsafeMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine, so it measures nothing about whether '${engineMethod}' reached the daemon or the user's screen. Do NOT re-issue ${engineMethod}: a re-issue can perform the same action a second time on the user's screen (and for attach, re-point the daemon and discard the trail an outstanding request is being recorded in), and this failure does not establish that the first copy did nothing. ${readRoute}. ${reportRoute}`;
+  }
+  if (!isNarrowableByRetryMethod(engineMethod)) {
+    return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is a method whose re-issue writes daemon state \u2014 a fresh request appends to the bounded snapshot ring and can evict a baseline this caller already received \u2014 so treat it as a question to read around rather than one to send again: gp_snapshot lists stored ids, and ${readRoute}. ${reportRoute}`;
+  }
+  return `this is a defect in this shell, not an answer from the engine. '${engineMethod}' is not one of the methods this shell classifies as unsafe to repeat (the no-replay set is act/restore/attach, plus snapshot, whose re-issue writes daemon state), so sending this tool again is a real option rather than a side effect: do that once. If the fault repeats, ${readRoute}. ${reportRoute}`;
+}
+async function executeTool(spec, args, engine, session) {
+  if (!session) {
+    return {
+      content: [{ type: "text", text: formatToolError(
+        GP_E_INTERNAL,
+        `executeTool was called for ${spec.name} without the session's trail`,
+        "this shell recorded nothing for this call: executeTool requires the shared EvidenceAuditSession the server was built with (dispatch.ts's createTrackedMcpServer), because a trail handed to one call only is invisible to gp_recent_reports. Pass the server's session rather than omitting it"
+      ) }],
+      isError: true
+    };
+  }
   const checked = spec.validate(args);
   if (!checked.ok) {
     return {
@@ -3094,7 +2884,7 @@ async function runValidatedTool(spec, value, engine, session, turn) {
       content.push({
         type: "text",
         text: reading.kind === "read" ? `${reading.summary}
-${caBundleDiagnosis(reading.ca)}
+${caBundleDiagnosis(reading.ca, updaterEnableCommand(reading.runtime))}
 ${runtimeSelfDiagnosis(reading.runtime, reading.stateFile)}` : reading.summary
       });
     }
@@ -3117,14 +2907,32 @@ ${runtimeSelfDiagnosis(reading.runtime, reading.stateFile)}` : reading.summary
       content: [{ type: "text", text: formatToolError(
         GP_E_INTERNAL,
         `internal shell error: ${String(error)}`,
-        "see the MCP server logs and retry"
+        shellFaultRemedy(spec.engineMethod)
       ) }],
       isError: true
     };
   }
 }
-function caBundleDiagnosis(ca) {
-  const enableCmd = "`node updater/cli.js enable`";
+function shellPath(text) {
+  return /[\s"'`\\]/.test(text) ? JSON.stringify(text) : text;
+}
+function absoluteNodeCommand(cliPath, suffix) {
+  if (cliPath === null || !path4.isAbsolute(cliPath)) {
+    return null;
+  }
+  return `node ${shellPath(cliPath)}${suffix}`;
+}
+function repoScript(name) {
+  const here = path4.dirname(fileURLToPath2(import.meta.url));
+  const candidate = path4.resolve(here, "..", "..", name);
+  return fs4.existsSync(candidate) ? candidate : null;
+}
+function updaterEnableCommand(runtime) {
+  const named2 = runtime.recorded ? runtime.cliPath : null;
+  const command = absoluteNodeCommand(named2, " enable") ?? absoluteNodeCommand(repoScript(path4.join("updater", "cli.js")), " enable");
+  return command === null ? "the `enable` step of this install's updater copy \u2014 its path is the `runtime.cliPath` the record names (printed on the line below, when the record carries one), and neither that record nor this build's own location gives an absolute path, so this remedy prints no command rather than one that resolves against a directory you are not standing in" : `\`${command}\``;
+}
+function caBundleDiagnosis(ca, enableCmd) {
   if (!ca.recorded) {
     return `ca trust bundle: this install has never recorded exporting the machine's trusted roots (the state file carries no caRoots), which is NOT the same as "the bundle is fine" \u2014 an install predating the export step looks exactly like this. node then verifies only against the CA list inside its own binary, so on a machine whose HTTPS is re-signed locally every auto-update run fails certificate verification and nothing on the surface says so. Remedy: re-run the GlassPane installer, or ${enableCmd}, either of which writes the roots to ${ca.bundlePath} and points the launchd agent and the panel at it. For a check run by hand in a terminal: export NODE_EXTRA_CA_CERTS=${ca.bundlePath} \u2014 but only once that file exists, and set before node starts, because a running process never picks the variable up.`;
   }
@@ -3161,8 +2969,10 @@ function caBundleDiagnosis(ca) {
   return provenance.length === 0 ? diagnosis : `${diagnosis} The record itself says: ${provenance.join("; ")}.`;
 }
 function runtimeSelfDiagnosis(runtime, stateFile) {
-  const installerCmd = "`node installer/cli.js` (or the `install.sh` this machine was installed with)";
-  const enableCmd = (cliPath) => cliPath === null ? null : `node ${cliPath} enable --state-dir ${stateRootOf(stateFile)} --json`;
+  const installerCommand = absoluteNodeCommand(repoScript("installer/cli.js"), "");
+  const installScript = repoScript("install.sh");
+  const installerCmd = installerCommand === null ? "the installer of the GlassPane checkout this machine was installed from \u2014 this build is not shipped beside it, so no absolute path can be named from here, and every command in that tree has to be run from inside it" : installScript === null ? `\`${installerCommand}\`` : `\`${installerCommand}\` (or \`${shellPath(installScript)}\`)`;
+  const enableCmd = (cliPath) => absoluteNodeCommand(cliPath, ` enable --state-dir ${shellPath(stateRootOf(stateFile))} --json`);
   const copy = (version, cliPath) => {
     if (cliPath === null) {
       return version === null ? "the record names neither a version nor a path for it" : `version ${version}, and the record names no path for it`;
@@ -3260,7 +3070,17 @@ async function captureView(args, context) {
         isError: true
       };
     }
-    const mimeType = typeof body.mimeType === "string" && body.mimeType.length > 0 ? body.mimeType : "image/png";
+    if (typeof body.mimeType !== "string" || body.mimeType.length === 0) {
+      return {
+        content: [{ type: "text", text: formatToolError(
+          GP_E_INTERNAL,
+          `capture_view answered without a mimeType (got ${JSON.stringify(body.mimeType ?? null)})`,
+          "do not read this image as any particular format: the engine did not name one, and this shell will not fill the field in. This is a read-only capture, so sending it again performs nothing \u2014 if it repeats, report the frame shape, which is a protocol disagreement between two builds rather than a dead daemon"
+        ) }],
+        isError: true
+      };
+    }
+    const mimeType = body.mimeType;
     const summary = canonicalJson({
       mimeType,
       byteCount: body.byteCount,
@@ -3292,7 +3112,7 @@ async function captureView(args, context) {
       content: [{ type: "text", text: formatToolError(
         GP_E_INTERNAL,
         `internal shell error: ${String(error)}`,
-        "see the MCP server logs and retry"
+        shellFaultRemedy("capture_view")
       ) }],
       isError: true
     };
@@ -3393,7 +3213,7 @@ function projectErrorRemedy(code) {
     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";
   }
   if (code === GP_E_INTERNAL) {
-    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`python3 -m json.tool <that path>\`, repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
+    return `the projects file is the problem, not your arguments: the message above names its path, so read it with \`/usr/bin/plutil -p <that path>\` or \`/bin/cat <that path>\` \u2014 both absolute, so they run from whatever directory the reader is in and need nothing that may be off PATH \u2014 repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
   }
   return "check the tool's input schema and retry";
 }
@@ -3468,7 +3288,7 @@ function renderTrailIds(ids, format) {
 }
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
-    return `${error.code}: ${error.message}`;
+    return formatToolErrorShape(error.toBody());
   }
   const mapped = mapEvidenceReadError(error);
   if (mapped !== void 0) {
@@ -3589,8 +3409,8 @@ async function recentReports(args, context) {
     return {
       content: [{ type: "text", text: formatToolError(
         GP_E_NO_EVIDENCE,
-        "no recent evidence is reachable in the daemon history",
-        "the engine may have restarted; re-run gp_act / gp_assert_element to regenerate evidence"
+        `no pack is reachable in the daemon history for any of the ${ids.length} ${ids.length === 1 ? "operation" : "operations"} this shell asked about: each was answered GP_E_NO_EVIDENCE (${renderTrailIds(skipped, format)})`,
+        "these operations are recorded in this session's trail, and the daemon holding no pack for them is a fact about its bounded history, not evidence that they did not run \u2014 this call measured nothing about a restart, so no cause is claimed here. Read one of them by id with gp_last_evidence {operationId} / gp_export_evidence {operationId}, or ask again with a smaller limit (gp_recent_reports advertises 1\u202620). Do not re-run gp_act to regenerate what the trail already holds"
       ) }],
       isError: true
     };
@@ -3613,7 +3433,7 @@ async function recentReports(args, context) {
   sections2.push(body);
   return { content: [{ type: "text", text: sections2.join("\n") }], isError: false };
 }
-function mapAuditError(error) {
+function mapAuditError(error, engineMethod = "last_evidence") {
   if (error instanceof EngineCallError) {
     return {
       content: [{ type: "text", text: formatToolErrorShape(error.toBody()) }],
@@ -3628,7 +3448,7 @@ function mapAuditError(error) {
     content: [{ type: "text", text: formatToolError(
       GP_E_INTERNAL,
       `internal shell error: ${String(error)}`,
-      "see the MCP server logs and retry"
+      shellFaultRemedy(engineMethod)
     ) }],
     isError: true
   };
@@ -3657,6 +3477,243 @@ function engineWithPayloadAdvice(engine, spec, toolArgs = {}) {
   return wrapped;
 }
 
+// src/audit-session.ts
+var AUDIT_HISTORY_LIMIT = 20;
+var UNKNOWN_GENERATION = -1;
+function openTrailGate() {
+  let settle;
+  const settled = new Promise((resolve) => {
+    settle = () => resolve(void 0);
+  });
+  return { settled, settle };
+}
+var EvidenceAuditSession = class {
+  ids = [];
+  epoch = 0;
+  attachedAppKey = null;
+  /**
+   * Turns claimed but not released. This, not a "latest gate", is what a new
+   * claim waits for: a turn that abandons the trail (its engine call failed
+   * before any mutation) releases *out of order*, and a chain that only looked
+   * at the immediately preceding turn would let everything behind it run while
+   * an older, still-outstanding act had not written yet — the exact completion
+   * order the turn machinery exists to remove.
+   */
+  openGates = /* @__PURE__ */ new Set();
+  /**
+   * How each id in {@link ids} got here. Keyed by the id, because that is what a
+   * reader holds; the map is trimmed with the list and cleared when the trail
+   * restarts, so an id can never outlive the provenance that describes it.
+   */
+  provenance = /* @__PURE__ */ new Map();
+  /**
+   * Non-null while {@link recordLateArrival} holds the trail, and says how the
+   * frame being written was attributed. This is what lets a plain
+   * `trail.record(result)` inside that callback be filed as a late arrival without
+   * the caller having to remember to say so: the write happens inside a window only
+   * that method opens, so the mechanism is visible here rather than being a claim
+   * somebody must repeat at every call site.
+   */
+  lateWindow = null;
+  /**
+   * Record every operationId/evidenceId found in an engine result frame, tagged
+   * with the provenance of the path that is recording it (see
+   * {@link TrailProvenance}): `in-order` from a call that held its own trail turn,
+   * `late`/`late-inferred` from inside {@link recordLateArrival}.
+   */
+  record(result) {
+    const source = this.lateWindow === null ? "in-order" : this.lateWindow === "arrival-order" ? "late-inferred" : "late";
+    for (const id of collectOperationIds(result)) {
+      if (!this.ids.includes(id)) {
+        this.ids.push(id);
+        this.provenance.set(id, source);
+        if (this.ids.length > AUDIT_HISTORY_LIMIT) {
+          const evicted = this.ids.splice(0, this.ids.length - AUDIT_HISTORY_LIMIT);
+          for (const gone of evicted) {
+            this.provenance.delete(gone);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * How one id in this trail got recorded, or null when the trail does not hold
+   * it — never recorded, evicted past {@link AUDIT_HISTORY_LIMIT}, or cleared by a
+   * {@link restart}. A reader that lists ids for an agent renders
+   * {@link TRAIL_PROVENANCE_NOTES} for anything that is not `in-order`: an id
+   * pulled from a frame this shell only *guessed* an owner for must not appear
+   * beside one it matched by id (R10-中2).
+   *
+   * Read off the map alone, so the map *is* the record of what the trail holds: an
+   * id whose provenance outlives its own entry would come back labelled as if it
+   * were still listed, and the eviction and the restart are the two places that
+   * would have to remember to delete. `test/engine-client.test.mjs` pins both.
+   */
+  provenanceOf(id) {
+    return this.provenance.get(id) ?? null;
+  }
+  /** The ids currently filed as inferred; see {@link TrailProvenance}. */
+  inferredIds() {
+    return this.ids.filter((id) => this.provenance.get(id) === "late-inferred");
+  }
+  /**
+   * The trail's generation number. Every {@link restart} bumps it.
+   *
+   * It exists so a reply that arrives *after* its caller was already answered
+   * can be judged against the trail it was written into: {@link recordLateArrival}
+   * takes the epoch the request was admitted under, and a mismatch means a
+   * re-attach happened in between. Without it, a late write lands in a *new*
+   * session's trail — an operationId from the previous app that
+   * `gp_recent_reports` then fetches and renders as if it belonged to this one
+   * (R8b-高1, measured: `['op_OLDAPP']` in the trail after attaching a second
+   * app).
+   */
+  get generation() {
+    return this.epoch;
+  }
+  /** The app the trail currently belongs to, or null before the first attach. */
+  get attachedApp() {
+    return this.attachedAppKey;
+  }
+  /**
+   * A successful attach: the trail restarts **only when the attached app
+   * changed**, because that is the daemon's own rule —
+   * `EngineCore.attach` clears `history` under
+   * `if attachedApp != app`, and its comment says re-attach to the same app is
+   * idempotent. Clearing on *every* attach (what this used to do) is strictly
+   * worse in two directions: an idempotent re-attach wiped operations that were
+   * really in the trail (including one recorded by a late reply, which put
+   * `gp_recent_reports` back to "run gp_act first"), and — because the clear
+   * happens whenever the reply lands — it could also drop the record of an act
+   * the daemon still has.
+   *
+   * `appKey` must be built from every stored property of Swift's `AttachedApp`
+   * (`pid`, `bundleId`, `appName`); a key that ignored `pid` would keep the
+   * trail across an app restart whose history the daemon did clear. The gate
+   * that pins this to the Swift struct is
+   * `test/attach-identity.test.mjs`.
+   *
+   * Returns whether the trail was restarted. A null `appKey` means the attach
+   * result did not identify the app at all, which is treated as a change: an
+   * unknown identity cannot be *shown* to be the same app, and a stale trail is
+   * the failure that misattributes evidence.
+   */
+  restart(appKey) {
+    if (appKey !== null && appKey === this.attachedAppKey) {
+      return false;
+    }
+    this.attachedAppKey = appKey;
+    this.ids = [];
+    this.provenance.clear();
+    this.epoch += 1;
+    return true;
+  }
+  /** The most recent `limit` recorded operationIds, oldest first. */
+  recentIds(limit) {
+    return this.ids.slice(-limit);
+  }
+  /**
+   * Record a frame that arrives with **no request of the caller still holding a
+   * turn**: a late engine reply (R8-高3, `EngineJsonRpcClient.onLateReply`). Its
+   * own turn was released the moment the timeout was reported to the agent, so
+   * there is no request-order position left to write at.
+   *
+   * It still goes through the turn machinery rather than a bare `record()`,
+   * because a direct write could land *between* two admitted calls and reorder
+   * the trail against the requests the agent made — the exact thing the turns
+   * exist to prevent. Claiming on arrival gives the only honest position left:
+   * behind whatever is still outstanding, and ordered among late arrivals by
+   * when they arrived.
+   *
+   * `admittedUnderGeneration` is compared **inside** that wait (see the body):
+   * the position and the epoch can only be judged at the moment the write
+   * actually happens. A reply whose request carried no generation cannot be
+   * placed either — so it is passed as {@link UNKNOWN_GENERATION} and the caller
+   * decides whether that is acceptable; this method refuses it by default, because
+   * "we do not know which attach this belongs to" is not a reason to write into
+   * somebody else's trail.
+   *
+   * `attribution` is how the transport matched that frame to a request, and it is
+   * the difference between `late` and `late-inferred` below: a frame that echoed
+   * the id the client sent is confirmed, one with no id is filed against the
+   * oldest tracked request by the daemon's in-order scheduling (R10-中2). Anything
+   * this method writes is a late arrival by construction, so the window opens
+   * whether or not the caller can say more — the default `unknown` is what the
+   * session can see on its own, and it is *not* `in-order`: an unconfirmed
+   * attribution must not read as a verified one.
+   */
+  recordLateArrival(apply, admittedUnderGeneration, attribution = "unknown") {
+    const turn = this.claimTrailTurn();
+    return turn.acquire().then(() => {
+      try {
+        if (admittedUnderGeneration !== this.epoch) {
+          return { written: false, generationAtWrite: this.epoch };
+        }
+        this.lateWindow = attribution;
+        apply(this);
+        return { written: true, generationAtWrite: this.epoch };
+      } finally {
+        this.lateWindow = null;
+        turn.release();
+      }
+    });
+  }
+  /**
+   * Claim the next position in this session's trail request order, so that
+   * overlapping calls mutate and read `ids` in the order they were admitted
+   * rather than in the order the daemon answered.
+   *
+   * Synchronous on purpose — a claim made after an `await` would itself be
+   * ordered by completion. Callers hold a turn only across a `record()` /
+   * `reset()` / `recentIds()`, never across an engine round trip, so the queue
+   * can delay the moment a reply is built but never a request at the daemon.
+   */
+  claimTrailTurn() {
+    const ahead = [...this.openGates];
+    const mine = openTrailGate();
+    this.openGates.add(mine);
+    let released = false;
+    return {
+      acquire: async () => {
+        await Promise.all(ahead.map((gate) => gate.settled));
+      },
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        this.openGates.delete(mine);
+        mine.settle();
+      }
+    };
+  }
+};
+function operationIds(value) {
+  return collectOperationIds(value);
+}
+function collectOperationIds(value, depth = 0) {
+  const out = [];
+  if (depth > 3 || value === null || typeof value !== "object") {
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      out.push(...collectOperationIds(item, depth + 1));
+    }
+    return out;
+  }
+  const record = value;
+  for (const key of Object.keys(record)) {
+    const entry = record[key];
+    if ((key === "operationId" || key === "evidenceId") && typeof entry === "string") {
+      out.push(entry);
+    } else {
+      out.push(...collectOperationIds(entry, depth + 1));
+    }
+  }
+  return out;
+}
+
 // src/dispatch.ts
 var JSONRPC = "2.0";
 var MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -3665,7 +3722,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.10.0" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.12.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -3900,6 +3957,32 @@ A daemon started by hand with --state-dir has no launchd job to read: pass it
 <state-dir>/daemon.sock.
 `;
 var DRAIN_WAIT_MS = 3e4;
+var WRITE_STALL_MS = 10;
+var WRITE_STALL_LIMIT = 1e3;
+function writeDescriptor(fd, text) {
+  const buffer = Buffer.from(text, "utf8");
+  let offset = 0;
+  let stalls = 0;
+  while (offset < buffer.length) {
+    let written;
+    try {
+      written = fs5.writeSync(fd, buffer, offset, buffer.length - offset);
+    } catch (error) {
+      const code = error.code;
+      if (code === "EAGAIN" && stalls < WRITE_STALL_LIMIT) {
+        stalls++;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, WRITE_STALL_MS);
+        continue;
+      }
+      return;
+    }
+    if (written <= 0) {
+      return;
+    }
+    offset += written;
+    stalls = 0;
+  }
+}
 function logNote(text) {
   try {
     process2.stderr.write(`[glasspane-mcp] ${text}
@@ -3922,11 +4005,11 @@ function main() {
   try {
     options = parseArgs(process2.argv.slice(2));
   } catch (error) {
-    process2.stderr.write(String(error) + "\n\n" + USAGE);
+    writeDescriptor(2, String(error) + "\n\n" + USAGE);
     process2.exit(2);
   }
   if (options.help) {
-    process2.stdout.write(USAGE);
+    writeDescriptor(1, USAGE);
     process2.exit(0);
   }
   process2.stdin.setEncoding("utf8");
@@ -3936,7 +4019,8 @@ function main() {
       identity: { version: SERVER_INFO.version }
     });
   } catch (error) {
-    process2.stderr.write(
+    writeDescriptor(
+      2,
       `failed to create engine client on ${options.socketPath}: ${String(error)}
 `
     );
@@ -3977,7 +4061,7 @@ function main() {
   process2.stdin.on("data", (chunk) => reader.push(chunk));
   process2.stdin.on("error", (error) => {
     logNote(`stdin failed: ${error.message}`);
-    shutdown();
+    queue.push(async () => shutdown());
   });
   process2.stdin.on("close", () => queue.push(async () => shutdown()));
   process2.on("SIGINT", shutdown);

package/dist/tools.d.ts

@@ -373,6 +373,24 @@ export declare function isNarrowableByRetryMethod(method: string): boolean;
  * is the transport's, which orders no re-send.
  */
 export declare function toolAuthorsTimeoutAdvice(spec: ToolSpec, method: string, params: Record<string, unknown>): boolean;
+/**
+ * The remedy for a fault raised by *this shell*, on a call to `engineMethod`.
+ *
+ * This replaced "see the MCP server logs and retry" at all three internal-fault
+ * sites, and both halves of that sentence were wrong (review 2026-10-09 finding
+ * 8). "See the MCP server logs" is not something the caller can do: this process's
+ * stderr is held by whoever started the server, and a fault raised here is in no
+ * daemon log either, so the instruction sent the agent to look at a file that
+ * cannot contain the answer. And "retry" is an order to put a second copy of the
+ * request on the wire for methods whose re-issue this shell already refuses to
+ * endorse — `act`/`restore`/`attach` may still be performing their change on the
+ * user's screen, and a shell-side fault says nothing about whether the first copy
+ * went out. The classification is read from the transport's own lists
+ * ({@link isReplayUnsafeMethod}, {@link isNarrowableByRetryMethod}) rather than a
+ * third copy of the names, which is what keeps this answer from drifting back into
+ * "just retry the click".
+ */
+export declare function shellFaultRemedy(engineMethod: string): string;
 /**
  * Execute a tool against the engine client. Validates arguments against
  * the tool's zod schema (isError + GP_E_BAD_PARAMS on failure), then either
@@ -383,7 +401,20 @@ export declare function toolAuthorsTimeoutAdvice(spec: ToolSpec, method: string,
  * before it does (see the trail-ordering block above); the engine call that
  * precedes that wait stays concurrent with every other outstanding request.
  */
-export declare function executeTool(spec: ToolSpec, args: unknown, engine: EngineJsonRpcClient, session?: EvidenceAuditSession): Promise<ToolResult>;
+export declare function executeTool(spec: ToolSpec, args: unknown, engine: EngineJsonRpcClient, 
+/**
+ * The session whose trail this call records into and reads back. **Required**,
+ * and it used to be `= new EvidenceAuditSession()`: a caller that omitted the
+ * argument then recorded its `operationId` into a trail nobody else held a
+ * reference to, so the next `gp_recent_reports` answered
+ * `GP_E_NO_EVIDENCE … no operations recorded in this session` for an `act` that
+ * had really run — the reading that makes an agent press it a second time on the
+ * user's screen. That is the same defect `dispatch.ts`'s `McpServerDeps.session`
+ * documents as removed, and it is checked at runtime for the same reason: every
+ * meaningful caller here is JavaScript (`dist` consumers, the smoke scripts, the
+ * tests), where an omitted argument compiles forever and fails silently.
+ */
+session: EvidenceAuditSession): Promise<ToolResult>;
 /**
  * Strongly validates the engine's last_evidence result (§6.3) and returns the
  * parsed pack together with the schema label the archive *carried*. The engine

package/package.json

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