glasspane-mcp 1.20.2 → 1.21.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.20.2";
+    readonly version: "1.21.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/errors.d.ts

@@ -76,6 +76,16 @@ export declare const GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
  * the filesystem root, the account's home directory itself, or a value that is not
  * an absolute path at all.
  *
+ * Since 1.20.1 this code also answers the *other* un-checked root in this shell: a
+ * `GLASSPANE_PROJECTS_FILE` override that names a directory `gp_project_set` would
+ * otherwise create and bring to 0700 before publishing the registry into it
+ * (`project-registry.ts`'s `overrideProjectsPath`). Same authority, same consequence, and
+ * no new vocabulary: both are "a root this process was told to write into, judged and
+ * refused before the first syscall". The two differ in who said it — one is the service's
+ * self-report, the other this process's own environment — and each frame carries its own
+ * remedy (`ProjectRegistryError.remedy`) so the reader is never told to restart the daemon
+ * for a variable it exported, or to edit a file for a refusal that names a directory.
+ *
  * The daemon refuses the same shapes for its own `--state-dir` (`StateRoot.classify`
  * → `StateRoot.notADedicatedRoot`) and then `tightenPermissions` that root to 0700,
  * so the argument parse is the only thing standing between `--state-dir ~` and a

package/dist/http-gateway-cli.js

@@ -378,8 +378,12 @@ function clientClosingRemedy(surface) {
   const readRoute = readInsteadRoute(surface);
   return `this shell's own engine client is ending, which measures nothing about the daemon: nothing here authorises touching the daemon's lifecycle, and no restart is authorised by this answer. What is unknown stays unknown: whether the daemon finished this request cannot be told from a client that stopped asking. The reply may still land, under the bound this shell already states \u2014 ${lateReplyRoute(surface)} \u2014 and this shutdown is one of the endings that bound names: the server log line written at this moment lists the requests this client stopped tracking. Read what happened rather than performing it a second time: ${readRoute}. Ask through a server process that still has a live engine client.`;
 }
-function transportDeathRemedy(method, surface) {
+var NEVER_LEFT_TRANSPORT = "the frame this request wrote never left this process \u2014 its bytes were still in this client's own write queue when the transport went, so nothing reached the daemon and nothing was performed there";
+function transportDeathRemedy(method, surface, handedOff) {
   const restore = daemonRestoreCommand();
+  if (!handedOff) {
+    return daemonUnreachableRemedy();
+  }
   const unsafe = REPLAY_UNSAFE_REASONS[method];
   if (unsafe !== void 0) {
     return `${restore}. Do NOT re-issue '${method}' on the strength of this answer: this request had already left this shell when its transport died, and whether the daemon carried it out before that cannot be told from here \u2014 a re-issue can perform it a second time, because ${unsafe}. Read what happened instead of performing it a second time: ${readInsteadRoute(surface)}.`;
@@ -433,10 +437,23 @@ var EngineJsonRpcClient = class {
         this.failOversizedReply(error);
         return;
       }
-      this.teardown(`engine transport error: ${error.message}`, (method) => transportDeathRemedy(method, this.surface));
+      this.teardown(
+        `engine transport error: ${error.message}`,
+        (method, handedOff) => transportDeathRemedy(method, this.surface, handedOff),
+        NEVER_LEFT_TRANSPORT
+      );
+    });
+    this.io.onClose(() => this.teardown(
+      "engine transport closed",
+      (method, handedOff) => transportDeathRemedy(method, this.surface, handedOff),
+      NEVER_LEFT_TRANSPORT
+    ));
+    this.io.onOpen?.(() => {
+      for (const entry of this.pending.values()) {
+        entry.handedOff = true;
+      }
+      this.handshake();
     });
-    this.io.onClose(() => this.teardown("engine transport closed", (method) => transportDeathRemedy(method, this.surface)));
-    this.io.onOpen?.(() => this.handshake());
   }
   io;
   timeoutMs;
@@ -548,7 +565,7 @@ var EngineJsonRpcClient = class {
         id,
         method,
         correlation,
-        params,
+        handedOff: true,
         deadlineMs,
         methodDeadlineMs,
         timer: null,
@@ -568,8 +585,14 @@ var EngineJsonRpcClient = class {
         return;
       }
       this.pending.set(id, entry);
+      const queuedBefore = this.io.bufferedBytes?.() ?? null;
       try {
-        this.io.writeLine(JSON.stringify(frame));
+        const frameText = JSON.stringify(frame);
+        this.io.writeLine(frameText);
+        if (queuedBefore !== null) {
+          const queuedAfter = this.io.bufferedBytes?.() ?? 0;
+          entry.handedOff = queuedAfter < queuedBefore + frameText.length + 1;
+        }
       } catch (error) {
         this.pending.delete(id);
         this.reject(entry, new EngineCallError(
@@ -844,13 +867,14 @@ var EngineJsonRpcClient = class {
    * and one remedy for the whole batch is how "…, then retry" reached an
    * outstanding `act` at all. See {@link transportDeathRemedy}.
    */
-  teardown(message, remedyFor) {
+  teardown(message, remedyFor, neverLeftNote = null) {
     const entries = [...this.pending.values()];
     const tracked = entries.filter((entry) => entry.settled);
     this.pending.clear();
     for (const entry of entries) {
       if (!entry.settled) {
-        this.reject(entry, new EngineCallError(GP_E_ENGINE_UNREACHABLE, message, remedyFor(entry.method)));
+        const said = entry.handedOff || neverLeftNote === null ? message : `${message}; ${neverLeftNote}`;
+        this.reject(entry, new EngineCallError(GP_E_ENGINE_UNREACHABLE, said, remedyFor(entry.method, entry.handedOff)));
       } else if (entry.timer !== null) {
         clearTimeout(entry.timer);
         entry.timer = null;
@@ -893,6 +917,10 @@ var EngineJsonRpcClient = class {
     if (version !== "") {
       this.helloVersion = version;
     }
+    const reportedRoot = typeof report.stateRoot === "string" ? report.stateRoot.trim() : "";
+    if (reportedRoot !== "") {
+      this.helloStateRoot = reportedRoot;
+    }
     const protocol = typeof report.protocolVersion === "string" ? report.protocolVersion : null;
     if (protocol === null) {
       this.report(`engine self-report has no protocolVersion (engine=${jsonOrString(report.engine)}); expected '${expected}' \u2014 compatibility unverified`);
@@ -903,10 +931,6 @@ var EngineJsonRpcClient = class {
       return;
     }
     const reportedVersion = version === "" ? null : version;
-    const reportedRoot = typeof report.stateRoot === "string" ? report.stateRoot.trim() : "";
-    if (reportedRoot !== "") {
-      this.helloStateRoot = reportedRoot;
-    }
     const wantVersion = this.identity?.version;
     if (reportedVersion !== null && wantVersion !== void 0 && reportedVersion !== wantVersion) {
       this.report(`version mismatch: engine self-reports '${reportedVersion}', this MCP shell ships '${wantVersion}' (single version line) \u2014 one side is stale`);
@@ -2151,9 +2175,52 @@ var ProjectSetArgs = z9.strictObject({
 });
 function projectsPath(daemonStateRoot) {
   const envPath = process.env[PROJECTS_FILE_ENV];
-  if (envPath) return envPath;
+  if (envPath) return overrideProjectsPath(envPath);
   return daemonProjectsPath(daemonStateRoot);
 }
+function homeDefaultStateRoot() {
+  return stripFirmlink(path3.posix.normalize(systemHome() + "/.glasspane"));
+}
+function overrideProjectsPath(raw) {
+  const trimmed = raw.trim();
+  const normalized = foldSlashTerminators(stripFirmlink(path3.posix.normalize(trimmed)));
+  if (!normalized.startsWith("/")) {
+    throw refusedProjectsFileOverride(
+      trimmed,
+      `is not an absolute path (${trimmed}), so which projects file this write reaches moves with the working directory of whoever started this MCP server`
+    );
+  }
+  for (const component of normalized.split("/")) {
+    if (component === "." || component === "..") {
+      throw refusedProjectsFileOverride(
+        trimmed,
+        `carries a "." or ".." component (${trimmed}), so the file it names is not the file this call was asked to write`
+      );
+    }
+  }
+  const directory = path3.dirname(normalized);
+  if (directory === homeDefaultStateRoot()) {
+    return normalized;
+  }
+  const shape = stateRootRefusal(directory);
+  if (shape !== null) {
+    throw refusedProjectsFileOverride(trimmed, `its directory ${shape} (${directory})`);
+  }
+  const resolved = stripFirmlink(resolveExistingAncestor(directory));
+  const refusal = strongestRefusal(resolved === directory ? [directory] : [directory, resolved], resolved);
+  if (refusal !== null) {
+    throw refusedProjectsFileOverride(trimmed, `its directory ${refusalPhrase(refusal, resolved)}`);
+  }
+  return normalized;
+}
+function refusedProjectsFileOverride(raw, defect) {
+  const defaultFile = `${homeDefaultStateRoot()}/projects.json`;
+  return new ProjectRegistryError(
+    GP_E_STATE_ROOT_REFUSED,
+    `the ${PROJECTS_FILE_ENV} override this shell was started with ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. This is the override slot of **this process**, not a root the background service reported about itself \u2014 the daemon never reads ${PROJECTS_FILE_ENV} (R7-14), so the value being judged is one an environment, a wrapper, or an agent set for the MCP shell alone. It is not a harmless pointer either: \`gp_project_set\` would have created that directory and re-permissioned it to 0700, then written the project registry \u2014 bundle ids, pids and storage paths \u2014 into it, which is the same authority this module refuses a self-reported root over (\`StateRoot.notADedicatedRoot\`) and refuses an agent-named evidence archive over (\`refuseCandidate\`). Nothing was read and nothing was written by this call: no directory was created, no permission was changed, no projects.json was opened, listed or saved.`,
+    `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`glasspaned --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
+  );
+}
 function loadRegistry(filePath) {
   let bytes;
   try {
@@ -2353,13 +2420,22 @@ function saveProjects(filePath, entries) {
     if (error instanceof ProjectRegistryError) {
       throw new ProjectRegistryError(
         error.code,
-        `${error.message}; projects.json at ${filePath} was therefore not published as owner-only, and gp_project_set refuses to report a write the daemon's own modes did not hold. Bring the state root to them yourself (chmod 700 ${quoteShellArg(dir)}, chmod 600 ${quoteShellArg(filePath)}) and retry \u2014 a volume that ignores chmod (read-only mount, ACL, immutable flag) needs the daemon's --state-dir moved to one that honours permissions; until then the registry on disk and this shell disagree about who can read it`
+        `${error.message}; projects.json at ${filePath} was therefore not published as owner-only, and gp_project_set refuses to report a write the daemon's own modes did not hold. Bring the state root to them yourself (chmod 700 ${quoteShellArg(dir)}, chmod 600 ${quoteShellArg(filePath)}) and retry \u2014 a volume that ignores chmod (read-only mount, ACL, immutable flag) needs the daemon's --state-dir moved to one that honours permissions; until then the registry on disk and this shell disagree about who can read it`,
+        // The refusal above already names the two commands that make the modes true, so the
+        // remedy transcribes them instead of sending the reader to repair a file nobody
+        // called damaged (B5). Nothing here is a judgement about the registry's contents.
+        `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`glasspaned --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
       );
     }
     const errno = error?.code ?? "unknown";
     throw new ProjectRegistryError(
       GP_E_INTERNAL,
-      `projects.json at ${filePath} was not published: committing the bytes to the device failed (${errno}). gp_project_set answers "not saved" here rather than "saved", because a registration a power loss can drop is not a registration. This is the write's own failure, not a verdict about the file's contents: check what the volume will do (\`ls -lO ${quoteShellArg(dir)}\` for an immutable flag, \`diskutil info -live ${quoteShellArg(dir)}\` for a read-only or remote mount), fix that, then retry the same call.`
+      `projects.json at ${filePath} was not published: committing the bytes to the device failed (${errno}). gp_project_set answers "not saved" here rather than "saved", because a registration a power loss can drop is not a registration. This is the write's own failure, not a verdict about the file's contents: check what the volume will do (\`ls -lO ${quoteShellArg(dir)}\` for an immutable flag, \`diskutil info -live ${quoteShellArg(dir)}\` for a read-only or remote mount), fix that, then retry the same call.`,
+      // Carried by the error rather than derived from `GP_E_INTERNAL` in `tools.ts` (B5):
+      // that code's arm reads "the projects file is the problem … repair or restore the
+      // damaged entry", which is the opposite of the sentence above and would send an agent
+      // to edit a registry that this call never failed to decode.
+      `nothing was published by this call, and the file's contents are not in question: check what the volume will do \u2014 \`ls -lO ${quoteShellArg(dir)}\` for an immutable flag, \`diskutil info -live ${quoteShellArg(dir)}\` for a read-only or remote mount, \`df -h ${quoteShellArg(dir)}\` for a full one \u2014 fix that, and repeat the same gp_project_set once the volume commits. Do not repair or restore projects.json for this fault, and do not set ${FORCE_OVERWRITE_ENV}: it moves an unreadable registry aside, which is a different problem from a write the device refused`
     );
   }
 }
@@ -2478,7 +2554,7 @@ function daemonRestartNotice(filePath, daemonStateRoot) {
   return `Saved in ${filePath}, the projects file under the home record this user's state root defaults to. If this is the root the service was started on \u2014 which is not knowable from here, because this daemon's hello reported no stateRoot \u2014 then the running background service loaded that file once when it started, so gp_attach will keep returning GP_E_NOT_FOUND for this projectId until the service restarts: ${restartCommand()}. ${rootDiscriminator()}`;
 }
 function rootDiscriminator() {
-  return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
+  return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
 }
 function restartCommand() {
   return `run \`launchctl kickstart -k gui/${currentUid()}/com.glasspane.daemon\` \u2014 if that reports the service was not found, the launchd job was never bootstrapped, so ${daemonUnreachableRemedy()}`;
@@ -2654,10 +2730,22 @@ function describeError(error) {
 }
 var ProjectRegistryError = class extends Error {
   code;
-  constructor(code, message) {
+  /**
+   * The registry layer's own next move, when this fault has one that the code cannot
+   * state. `tools.ts` transcribes it instead of deriving a remedy from the code alone
+   * (B5): a durability fault and a damaged registry both answer `GP_E_INTERNAL`, and the
+   * sentence that is right about the second — "the projects file is the problem … repair
+   * or restore the damaged entry" — is a lie about the first, whose own message says "This
+   * is the write's own failure, not a verdict about the file's contents". Absent means
+   * "the code's arm is the honest answer here", which is what the read-side faults below
+   * rely on.
+   */
+  remedy;
+  constructor(code, message, remedy) {
     super(message);
     this.name = "ProjectRegistryError";
     this.code = code;
+    this.remedy = remedy;
   }
 };
 
@@ -3179,6 +3267,23 @@ function oversizedReplyAdvice(spec, params) {
   }
   return head + floorNote + `retry with ${shrinkable.map(describeKnob).join(" and ")}; the reply body has to fit one frame, and a retried identical request will be dropped identically; the connection is intact and the daemon keeps answering other requests`;
 }
+var RING_WRITE_REASON = "it is not a cheaper re-read of the first: it appends another entry to the daemon's bounded snapshot ring, and one more entry can evict the baseline an earlier snapshot returned \u2014 the one a later restore needs";
+function narrowingKnobPhrase(spec, params) {
+  const knobs = narrowingKnobsFor(spec, params);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
+  const atFloor = knobs.filter(atAdvertisedFloor);
+  if (shrinkable.length > 0) {
+    return `the parameter that would make such a reply smaller is ${shrinkable.map(describeKnob).join(" and ")}`;
+  }
+  if (atFloor.length > 0) {
+    return `the only parameter of that kind this tool advertises is already spent (${atFloor.map(describeKnob).join("; ")})`;
+  }
+  return "this tool advertises no parameter that shrinks a reply";
+}
+function payloadOverflowArm(method) {
+  if (isReplayUnsafeMethod(method)) return "replay-unsafe";
+  return isNarrowableByRetryMethod(method) ? "narrowable" : "ring-writing";
+}
 var NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
   ...REPLAY_UNSAFE_METHOD_NAMES,
   ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
@@ -3380,8 +3485,9 @@ async function projectGetTool(args, context) {
 function mapProjectError(error) {
   const passed = passedThroughRegistryError(error);
   if (passed !== null) {
+    const remedy = passed.remedy ?? projectErrorRemedy(passed.code);
     return {
-      content: [{ type: "text", text: formatToolError(passed.code, passed.message, projectErrorRemedy(passed.code)) }],
+      content: [{ type: "text", text: formatToolError(passed.code, passed.message, remedy) }],
       isError: true
     };
   }
@@ -3400,7 +3506,8 @@ function passedThroughRegistryError(error) {
     return null;
   }
   const message = typeof candidate.message === "string" ? candidate.message : "";
-  return { code: candidate.code, message };
+  const remedy = typeof candidate.remedy === "string" && candidate.remedy.trim() !== "" ? candidate.remedy : null;
+  return { code: candidate.code, message, remedy };
 }
 function projectErrorRemedy(code) {
   if (code === GP_E_PROJECT_LIMIT) {
@@ -3657,10 +3764,12 @@ async function recentReports(args, context) {
     };
   }
   if (packs.length === 0) {
+    const asked = skipped.length;
+    const rejectClause = rejected.length === 0 ? "" : `. ${rejectedClause(rejected.length)}${renderTrailIds(rejected, format, provenanceOf)} were never sent, so the daemon has no opinion about them and nothing here reports one`;
     return {
       content: [{ type: "text", text: formatToolError(
         GP_E_NO_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, provenanceOf)})`,
+        `no pack is reachable in the daemon history for any of the ${asked} ${asked === 1 ? "operation" : "operations"} this shell sent: each was answered GP_E_NO_EVIDENCE (${renderTrailIds(skipped, format, provenanceOf)})${rejectClause}`,
         "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
@@ -4049,6 +4158,7 @@ async function handleEvidenceAggregate(url, client, res) {
   const renderedIds = [];
   const skipped = [];
   const notFetched = [];
+  let hardFailure = null;
   const budget = new FanOutBudget(EVIDENCE_FANOUT_BUDGET_MS);
   try {
     for (const [index, operationId] of ids.entries()) {
@@ -4067,19 +4177,42 @@ async function handleEvidenceAggregate(url, client, res) {
           blocks.push(render(packForReport(pack, measuredSchemaVersion), format));
           renderedIds.push(operationId);
         } catch (error) {
-          failEvidenceFrameShape(res, error, operationId);
-          return;
+          hardFailure = {
+            operationId,
+            kind: "frame",
+            error,
+            line: `${GP_E_INTERNAL}: the daemon returned a last_evidence frame this gateway cannot render (no parseable evidencePack for ${operationId}: ${boundedCause(describeCause(error))})`
+          };
+          notFetched.push(...ids.slice(index + 1));
+          break;
         }
       } else if (settled.kind === "missing") {
         skipped.push(operationId);
       } else {
-        await failEngine(res, settled.error, TOOL_BY_NAME.get("gp_last_evidence"), { operationId });
-        return;
+        hardFailure = {
+          operationId,
+          kind: "engine",
+          error: settled.error,
+          line: engineFailureLine(settled.error)
+        };
+        notFetched.push(...ids.slice(index + 1));
+        break;
       }
     }
   } finally {
     budget.done();
   }
+  if (blocks.length === 0 && hardFailure !== null) {
+    const tail = notFetchedTail(notFetched);
+    if (hardFailure.kind === "frame") {
+      failEvidenceFrameShape(res, hardFailure.error, hardFailure.operationId, tail);
+      return;
+    }
+    await failEngine(res, hardFailure.error, TOOL_BY_NAME.get("gp_last_evidence"), {
+      operationId: hardFailure.operationId
+    }, tail);
+    return;
+  }
   if (blocks.length === 0 && notFetched.length > 0) {
     fail(
       res,
@@ -4103,15 +4236,23 @@ async function handleEvidenceAggregate(url, client, res) {
   const header = format === "html" ? `<h1>GlassPane evidence reports (${blocks.length})</h1>` : `# GlassPane evidence reports (${blocks.length})`;
   const skipNote = makeSkipNote(skipped, format);
   const unfetchedNote = makeNotFetchedNote(notFetched, format);
+  const failureNote = makeHardFailureNote(hardFailure, format);
   const separator = format === "html" ? "\n<hr>\n" : "\n\n---\n";
   const sections2 = [header];
-  for (const note of [skipNote, unfetchedNote]) {
+  for (const note of [skipNote, unfetchedNote, failureNote]) {
     if (note !== "") {
       sections2.push(note);
     }
   }
   sections2.push(blocks.join(separator));
-  ok(res, { format, renderedIds, skipped, notFetched, report: sections2.join("\n") });
+  ok(res, {
+    format,
+    renderedIds,
+    skipped,
+    notFetched,
+    ...hardFailure === null ? {} : { failed: [hardFailure.operationId] },
+    report: sections2.join("\n")
+  });
 }
 async function handleToolForward(name, req, client, res) {
   const spec = FORWARDABLE_TOOLS.get(name);
@@ -4300,6 +4441,33 @@ function makeNotFetchedNote(notFetched, format) {
   const sentence = `not fetched within this request's ${EVIDENCE_FANOUT_BUDGET_MS}ms wait: ${notFetched.length} ${label} left unanswered: ${notFetched.join(", ")}. Fetch one by id with GET /v1/evidence/<operationId>, or ask again with a shorter ids= list`;
   return format === "html" ? `<p class="gp-not-fetched">${escapeHTML(sentence)}</p>` : `> ${sentence}`;
 }
+var CAUSE_MAX_CHARS = 400;
+function describeCause(error) {
+  if (error instanceof Error) {
+    return error.message.trim() === "" ? error.name : error.message;
+  }
+  return String(error);
+}
+function boundedCause(text) {
+  return text.length <= CAUSE_MAX_CHARS ? text : `${text.slice(0, CAUSE_MAX_CHARS)}\u2026 [+${text.length - CAUSE_MAX_CHARS} chars not shown]`;
+}
+function engineFailureLine(error) {
+  return error instanceof EngineCallError ? `${error.code}: ${boundedCause(error.message)}` : `${GP_E_INTERNAL}: ${boundedCause(describeCause(error))}`;
+}
+function notFetchedTail(notFetched) {
+  if (notFetched.length === 0) {
+    return "";
+  }
+  const label = notFetched.length === 1 ? "id" : "ids";
+  return ` \u2014 and ${notFetched.length} ${label} this request never sent (${notFetched.join(", ")}), which is a stopped read, not an answer about them`;
+}
+function makeHardFailureNote(failure, format) {
+  if (failure === null) {
+    return "";
+  }
+  const sentence = `incomplete: ${failure.operationId} failed with ${failure.line} \u2014 the fan-out stopped there, so the packs above are what this request read, not the whole list`;
+  return format === "html" ? `<p class="gp-incomplete">${escapeHTML(sentence)}</p>` : `> ${sentence}`;
+}
 function ok(res, result, attribution) {
   writeJson(res, 200, attribution === void 0 ? { ok: true, result } : { ok: true, result, attribution });
 }
@@ -4368,26 +4536,42 @@ function httpStatusForEngineCode(code) {
       return 422;
   }
 }
-async function failEngine(res, error, spec, params) {
+async function failEngine(res, error, spec, params, tail = "") {
   if (error instanceof EngineCallError) {
-    fail(res, httpStatusForEngineCode(error.code), error.code, error.message, engineRemedy(error, spec, params));
+    fail(
+      res,
+      httpStatusForEngineCode(error.code),
+      error.code,
+      `${error.message}${tail}`,
+      engineRemedy(error, spec, params)
+    );
     return;
   }
   fail(
     res,
     500,
     GP_E_INTERNAL,
-    `this gateway could not complete the request: ${String(error)}`,
+    `this gateway could not complete the request: ${String(error)}${tail}`,
     gatewayFaultAdvice(spec)
   );
 }
 function engineRemedy(error, spec, params) {
   if (spec !== void 0 && error.code === GP_E_PAYLOAD_TOO_LARGE) {
     const asked = params ?? {};
-    return isReplayUnsafeMethod(spec.engineMethod) ? httpReplayUnsafePayloadAdvice(spec, asked) : oversizedReplyAdvice(spec, asked);
+    switch (payloadOverflowArm(spec.engineMethod)) {
+      case "replay-unsafe":
+        return httpReplayUnsafePayloadAdvice(spec, asked);
+      case "ring-writing":
+        return httpRingWritingPayloadAdvice(spec, asked);
+      case "narrowable":
+        return oversizedReplyAdvice(spec, asked);
+    }
   }
   return error.remedy;
 }
+function httpRingWritingPayloadAdvice(spec, params) {
+  return `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); '${spec.engineMethod}' reached the daemon and was answered, and only its reply was dropped \u2014 which means the baseline it captured is already stored. Do NOT send this request again to recover that reply: ${RING_WRITE_REASON}. ${narrowingKnobPhrase(spec, params)}, and using it is the second send this answer refuses; the ids the daemon stored are only ever where a caller already has them, in the snapshot replies it has already received, and this gateway lists no ring. Read what is held, and see the attached app as it is now without changing it with POST /v1/tools/observe, POST /v1/tools/assert_element or POST /v1/tools/probe_status; an operation whose id is already held re-reads with GET /v1/evidence/<operationId>. Taking a fresh baseline is a decision, not error recovery, and the connection is intact and the daemon keeps answering other requests`;
+}
 function httpReplayUnsafePayloadAdvice(spec, params) {
   return `do not re-send this request on this answer. '${spec.engineMethod}' reached the daemon and was answered, and only its reply was dropped for exceeding one frame, so sending it again performs the change a second time rather than recovering the first answer (an act presses the same control again, a restore replays its steps again, an attach re-points the daemon at another app). Read what happened instead of acting again: GET /v1/evidence/<operationId> and POST /v1/tools/last_evidence {operationId} return the pack of an operation whose id you already hold, and POST /v1/tools/observe, POST /v1/tools/assert_element and POST /v1/tools/probe_status read the attached app as it is now without changing it \u2014 this gateway keeps no operation trail of its own, so it cannot list which operations ran. If that reading shows this request never took effect, send it again narrowed to what its own schema advertises: ${oversizedReplyAdvice(spec, params)}`;
 }
@@ -4398,12 +4582,12 @@ function gatewayFaultAdvice(spec) {
   }
   return `re-send this request only if it is one that changes nothing \u2014 a read; the routes this surface answers are ${TOOL_ROUTES_TEXT}. ${log}.`;
 }
-function failEvidenceFrameShape(res, error, operationId) {
+function failEvidenceFrameShape(res, error, operationId, tail = "") {
   fail(
     res,
     502,
     GP_E_INTERNAL,
-    `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${String(error)})`,
+    `the daemon returned a last_evidence frame that does not match the engine contract (no parseable evidencePack${operationId === void 0 ? "" : ` for ${operationId}`}: ${String(error)})${tail}`,
     "the daemon answered this request, so the transport is up and restarting it changes nothing here; this gateway validates a pack before rendering or forwarding it, so GET /v1/evidence/<operationId> and POST /v1/tools/last_evidence {operationId} will both refuse this frame for the same reason. Read what the attached app is doing now without performing anything: POST /v1/tools/observe, POST /v1/tools/assert_element or POST /v1/tools/probe_status. Producing a fresh pack for this operation means acting again, which is a decision this read cannot make for you."
   );
 }