glasspane-mcp 1.2.0 → 1.3.0

package/dist/http-gateway-cli.js

@@ -148,6 +148,8 @@ var GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 var GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
 var GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 var GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+var GP_E_UNKNOWN = "GP_E_UNKNOWN";
+var GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
 function formatToolError(code, message, remedy) {
   return `${code}: ${message} | remedy: ${remedy}`;
 }
@@ -169,8 +171,9 @@ function defaultSocketPath() {
   return process.env[ENGINE_SOCKET_ENV] ?? path.join(os.homedir(), ".glasspane", "engine.sock");
 }
 var ENGINE_TIMEOUT_MS = 1e4;
+var CALLER_VISIBLE_CEILING_MS = 5e4;
 var ENGINE_DEADLINES_MS = {
-  hello: 15e3,
+  // `hello` is at the bottom of this table, where its reason is written out.
   attach: 3e4,
   act: 12e4,
   observe: 45e3,
@@ -178,14 +181,35 @@ var ENGINE_DEADLINES_MS = {
   diagnose: 3e4,
   last_evidence: 6e4,
   snapshot: 9e4,
-  probe_status: 15e3,
-  shutdown: 15e3
+  probe_status: CALLER_VISIBLE_CEILING_MS,
+  // R8b-高4: the same trap as `probe_status`, one layer down. `handshake()` is
+  // fired by the transport's `connect` event, but `ReconnectingSocketIo` is lazy:
+  // the frame that *causes* the connection is written first, so when a session's
+  // very first request is an `act`, `hello` is queued behind it. At 15 s the
+  // handshake expired against a healthy daemon every time, R4-06's protocol and
+  // version comparison never ran, and the only trace was one stderr line — a
+  // silent loss of the one measurement that catches "an old daemon is under this
+  // shell". It gets the full client wait so the comparison happens.
+  hello: CALLER_VISIBLE_CEILING_MS,
+  shutdown: 15e3,
+  // R8-中5: these two used to ride `ENGINE_TIMEOUT_MS * 3` by omission, which is
+  // a deadline nobody derived from the daemon. Both are on the wire
+  // (`gp_audit_ui` forwards `audit_ui`; `gp_capture_view` calls `capture_view`
+  // from its own executor), and `test/method-table.test.mjs` now refuses any
+  // sent method that is missing here.
+  //
+  // `audit_ui` is one geometry snapshot walk (`AXChannel.geometrySnapshot`,
+  // capped by `AXChannel.treeTimeoutSeconds` = 10 s) plus a pure-geometry
+  // overlap scan. It rides `observe`'s number rather than a fresh guess: same
+  // tree walk, without observe's pixel round trip.
+  audit_ui: 45e3,
+  // `capture_view` is attach + `SCKCapturer.captureWindow` + PNG encode. The
+  // capture tries up to two candidate surfaces at `captureTimeoutSeconds` = 5 s
+  // each (R6-11 made the second candidate conditional, so two attempts is the
+  // real worst case), then encodes inside the frame budget.
+  capture_view: 3e4
 };
 var RESTORE_BASE_DEADLINE_MS = 3e4;
-var CALLER_VISIBLE_CEILING_MS = 5e4;
-function callerDeadlineMs(method, params, ceilingMs = CALLER_VISIBLE_CEILING_MS) {
-  return Math.min(engineDeadlineMs(method, params), ceilingMs);
-}
 var REPLAY_UNSAFE_METHODS = /* @__PURE__ */ new Set(["act", "restore"]);
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
@@ -196,6 +220,9 @@ function engineDeadlineMs(method, params) {
   const known = ENGINE_DEADLINES_MS[method];
   return known ?? ENGINE_TIMEOUT_MS * 3;
 }
+function callerDeadlineMs(method, params, ceilingMs = CALLER_VISIBLE_CEILING_MS) {
+  return Math.min(engineDeadlineMs(method, params), ceilingMs);
+}
 var ENGINE_PROTOCOL_VERSION = "0";
 var EngineCallError = class extends Error {
   code;
@@ -212,21 +239,50 @@ var EngineCallError = class extends Error {
     return { code: this.code, message: this.message, remedy: this.remedy };
   }
 };
-function slowEngineRemedy(method) {
-  const poll = "confirm the daemon is alive with a cheap call instead \u2014 gp_probe_status goes out immediately while this request is still outstanding (the shell no longer queues one MCP request behind another) and is answered as soon as the daemon is free of it";
+var LIVENESS_PROBE_OUTCOMES = [
+  "answered",
+  "engine-error",
+  "timed-out",
+  "unreachable"
+];
+function livenessProbeDecision(outcome) {
+  switch (outcome) {
+    case "answered":
+      return "answered at all (a result or an engine error frame) => the daemon is alive and has worked its way past the request in front of yours: keep waiting, the outstanding call's reply is still attributed and recorded";
+    case "engine-error":
+      return "answered with a named engine error code => the daemon is alive, so this answer never means \"restart the daemon because it is wedged\"; follow that code's own remedy instead, and note that some codes genuinely do name a restart (`GP_E_AX_UNAVAILABLE` does, because a wedged Accessibility API needs the service recycled) \u2014 that is the daemon's decision to make, not this sentence's";
+    case "timed-out":
+      return `not answered within its own window => NOT evidence that the daemon is down: it is single-connection and still busy with the earlier request (this is ${GP_E_ENGINE_TIMEOUT}, and the request stays registered so the real reply is attributed when it lands). Keep waiting; do not run the restore command on this answer alone, because restarting cancels and rolls back an action that is mid-flight on the user's screen`;
+    case "unreachable":
+      return `${GP_E_ENGINE_UNREACHABLE} (nothing is listening, or the transport died) => this is the one answer that justifies touching the daemon's lifecycle: ${daemonUnreachableRemedy()}`;
+  }
+}
+function livenessProbeGuide() {
+  return LIVENESS_PROBE_OUTCOMES.map((outcome) => `${outcome} \u2014 ${livenessProbeDecision(outcome)}`).join("; ");
+}
+function lateReplyRoute(surface) {
+  return surface === "mcp" ? "the original reply, when it lands, is written to this server's log (stderr) *and* its operationId is recorded in this session's trail, so a later gp_recent_reports lists the operation that ran instead of telling you to run it again \u2014 **while this server still tracks the request**: the window is bounded (" + LATE_REPLY_RETENTION + " timed-out requests, and an eviction is logged), a re-attach in between supersedes it (also logged, with the operationIds it dropped), and if this process has exited nothing will be recorded at all" : "the original reply, when it lands, is written to this gateway's stderr with its body, so the operationId it carries can be read off that line and fetched with GET /v1/evidence/<operationId> \u2014 the tracking window is bounded (" + LATE_REPLY_RETENTION + " timed-out requests, and an eviction is logged), and this gateway keeps no operation trail of its own";
+}
+function slowEngineRemedy(method, surface = "mcp") {
+  const poll = "if your client can send a second request while this one is still outstanding, confirm the daemon is alive with a cheap call: the shell does not queue one MCP request behind another, so gp_probe_status goes out at once and is answered as soon as the daemon is free of the request in front of it. Read its answer as: " + livenessProbeGuide();
+  const restarted = livenessProbeDecision("unreachable");
   if (REPLAY_UNSAFE_METHODS.has(method)) {
-    return `${poll}. The daemon serves one request at a time and is still working on this one, so wait for it; do NOT re-issue ${method}, because the original action can still take effect on the user's screen \u2014 the original reply is written to this server's log (stderr) when it lands, which is where the answer is. Restart only if gp_probe_status times out too \u2014 then ${daemonUnreachableRemedy()}`;
+    return `${poll}. The daemon serves one request at a time and is still working on this one, so wait for it; do NOT re-issue ${method}, because the original action can still take effect on the user's screen \u2014 ${lateReplyRoute(surface)}. Only ${restarted}`;
   }
-  return `${poll}. The daemon serves one request at a time and is still working on this one, so wait, then retry this read narrower (smaller maxDepth / a tighter selector); if gp_probe_status times out as well, ${daemonUnreachableRemedy()}`;
+  if (method === "probe_status") {
+    return `the liveness probe itself has not been answered, and it is given the longest wait this shell allows any request (${CALLER_VISIBLE_CEILING_MS}ms), so this particular answer carries no information about whether the daemon is alive: the daemon is single-connection and is still working on the request in front of this probe. ${livenessProbeDecision("timed-out")}. Keep waiting instead \u2014 the outstanding call's reply is attributed when it lands, and ${lateReplyRoute(surface)}. If the daemon's socket really is gone, the next call answers with ${GP_E_ENGINE_UNREACHABLE}, and that remedy names the restore command.`;
+  }
+  return `${poll}. The daemon serves one request at a time and is still working on this one, so wait, then retry this read narrower (smaller maxDepth / a tighter selector) \u2014 that is safe for a read; a restart is authorised only by ${restarted}`;
 }
 var LATE_REPLY_RETENTION = 16;
 var LOG_BODY_CHARS = 64 * 1024;
 var EngineJsonRpcClient = class {
-  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS) {
+  constructor(io, timeoutMs, identity = null, callerCeilingMs = CALLER_VISIBLE_CEILING_MS, surface = "mcp") {
     this.io = io;
     this.timeoutMs = timeoutMs;
     this.identity = identity;
     this.callerCeilingMs = callerCeilingMs;
+    this.surface = surface;
     this.io.onMessage((line) => this.handleMessage(line));
     this.io.onError((error) => {
       if (error instanceof OversizeFrameError) {
@@ -250,10 +306,12 @@ var EngineJsonRpcClient = class {
   timeoutMs;
   identity;
   callerCeilingMs;
+  surface;
   nextId = 0;
   closed = false;
   pending = /* @__PURE__ */ new Map();
   noteHandler = null;
+  lateReplyHandler = null;
   /**
    * Sink for facts that cannot be attached to any request of the caller: a
    * late reply, a frame with an id this client never issued, a daemon that
@@ -263,8 +321,26 @@ var EngineJsonRpcClient = class {
   onEngineNote(handler) {
     this.noteHandler = handler;
   }
-  /** Send a request and await its matching response frame. */
-  call(method, params) {
+  /**
+   * Sink for the *body* of a reply that lands after its caller was already
+   * answered (R8-高3). Logging it is not enough: the operationId in that frame
+   * is the only thing that puts the operation into this session's evidence
+   * trail, and without it `gp_recent_reports` answers
+   * `GP_E_NO_EVIDENCE ... run gp_act first` for an act that genuinely ran and
+   * genuinely mutated the user's screen — an agent reading that answer clicks
+   * again. The entry the reply is attributed to is only kept for
+   * `LATE_REPLY_RETENTION` requests, so this sink sees the tracked window and
+   * the eviction note says when something fell outside it.
+   */
+  onLateReply(handler) {
+    this.lateReplyHandler = handler;
+  }
+  /**
+   * Send a request and await its matching response frame. `correlation` is
+   * echoed to {@link onLateReply} if this request is answered after its caller
+   * has already been given a timeout; it is otherwise unused by this client.
+   */
+  call(method, params, correlation) {
     const id = this.nextId++;
     const frame = { id, method, ...params === void 0 ? {} : { params } };
     const methodDeadlineMs = this.timeoutMs ?? engineDeadlineMs(method, params);
@@ -273,6 +349,8 @@ var EngineJsonRpcClient = class {
       const entry = {
         id,
         method,
+        correlation,
+        params,
         deadlineMs,
         methodDeadlineMs,
         timer: null,
@@ -316,7 +394,7 @@ var EngineJsonRpcClient = class {
     this.reject(entry, new EngineCallError(
       GP_E_ENGINE_TIMEOUT,
       `engine is still working on '${entry.method}': no reply after ${entry.deadlineMs}ms. The request stays registered \u2014 a late reply is written to the server log \u2014 so this is a busy or slow daemon, not an unreachable one.` + capped,
-      slowEngineRemedy(entry.method)
+      slowEngineRemedy(entry.method, this.surface)
     ));
     this.retainForLateReply();
   }
@@ -403,12 +481,12 @@ var EngineJsonRpcClient = class {
     this.reject(entry, attribute(new EngineCallError(
       GP_E_PAYLOAD_TOO_LARGE,
       `the engine's reply to '${entry.method}' exceeded the ${MAX_FRAME_BYTES}-byte frame cap (${error.bytes} bytes) and was dropped; the connection is intact and other requests are unaffected`,
-      "narrow this request: retry with a smaller maxDepth or a more specific selector (the daemon keeps answering other requests)"
+      "narrow this request or ask for less of it; the tool's own schema names the parameters that can shrink a reply, and this shell rewrites this line into that advice when it can (the transport layer deliberately does not guess them)"
     ), entry, inferred));
   }
   engineError(body) {
     return new EngineCallError(
-      String(body.code ?? "GP_E_UNKNOWN"),
+      String(body.code ?? GP_E_UNKNOWN),
       String(body.message ?? "the engine sent an error frame without a message"),
       typeof body.remedy === "string" && body.remedy !== "" ? body.remedy : "the engine sent no remedy for this error code; check the daemon log (stderr) and retry"
     );
@@ -427,6 +505,18 @@ var EngineJsonRpcClient = class {
     this.report(
       `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported: ${body}`
     );
+    if (frame.error || frame.result === void 0) {
+      return;
+    }
+    const handler = this.lateReplyHandler;
+    if (handler === null) {
+      return;
+    }
+    try {
+      handler({ method: entry.method, result: frame.result, correlation: entry.correlation });
+    } catch (error) {
+      this.report(`the late-reply sink failed for '${entry.method}' (id ${entry.id}): ${String(error)}`);
+    }
   }
   resolve(entry, value) {
     this.complete(entry);
@@ -592,7 +682,8 @@ function unixSocketEngineClient(socketPath, options = {}) {
     new ReconnectingSocketIo(socketPath, open),
     void 0,
     options.identity ?? null,
-    options.callerCeilingMs ?? CALLER_VISIBLE_CEILING_MS
+    options.callerCeilingMs ?? CALLER_VISIBLE_CEILING_MS,
+    options.surface ?? "mcp"
   );
 }
 
@@ -1120,8 +1211,21 @@ var PROTECTED_SUBTREES = [
   "/private/tmp",
   "/private/var/tmp"
 ];
+function systemHome() {
+  try {
+    return os2.userInfo().homedir;
+  } catch (error) {
+    throw new ProjectRegistryError(
+      // Not GP_E_INTERNAL: `tools.ts` maps that code to "the projects file is
+      // damaged, go read it", and for this failure there is no damaged file —
+      // the process has no user record to derive a path from (R8b).
+      GP_E_NO_USER_RECORD,
+      `cannot read the user record this shell's home directory comes from (${describeError(error)}). The background service derives its state root the same way (NSHomeDirectory(), not $HOME), so there is no value here to fall back to: guessing from $HOME would name a projects.json the daemon does not load and would let the home-directory protection guard the wrong tree. Run this shell as a user that has an entry in the password database.`
+    );
+  }
+}
 function daemonProjectsPath() {
-  return path2.join(os2.homedir(), ".glasspane", "projects.json");
+  return path2.join(systemHome(), ".glasspane", "projects.json");
 }
 var FIRMLINK_PREFIX = "/System/Volumes/Data";
 var FORCE_OVERWRITE_ENV = "GLASSPANE_PROJECTS_FORCE_OVERWRITE";
@@ -1415,7 +1519,7 @@ function badPath(field, value, problem) {
 }
 var PATH_SHAPE_HINT = `An acceptable value is a project-owned directory at least two levels deep, e.g. "/Users/you/work/notes-app/.glasspane/evidence": absolute, with no "." or ".." components, not world-writable, with its nearest existing directory owned by the user running this shell (never a shared tree such as /Users/Shared, another user's home, /private/tmp, or a top-level directory of the boot volume), and not the filesystem root, a mounted volume root, your home directory, anything under ~/Library, or a system-owned tree (${PROTECTED_SUBTREES.join(", ")}) \u2014 the daemon writes evidence into this directory and deletes expired entries from it`;
 function refuseCandidate(target) {
-  const home = stripFirmlink(path2.posix.normalize(os2.homedir()));
+  const home = stripFirmlink(path2.posix.normalize(systemHome()));
   if (target === home) return named("the current user's home directory");
   if (isInside(`${home}/Library`, target)) return named("inside the current user's Library folder");
   if (isProtectedRoot(target)) return named("a protected system root");
@@ -1547,8 +1651,16 @@ var AttachArgs = z5.strictObject({
   bundleId: OptionalBundleIdSchema,
   pid: OptionalPidSchema,
   projectId: OptionalProjectIdSchema
-}).refine((v) => v.bundleId !== void 0 || v.pid !== void 0, {
-  message: "attach requires either bundleId or pid"
+}).refine((v) => v.bundleId === void 0 !== (v.pid === void 0), {
+  // Exclusive, not merely "at least one" (R8-中6). The advertised JSON Schema
+  // below already says `oneOf` (exactly one), and the daemon resolves both
+  // fields by *preferring pid and ignoring bundleId*
+  // (`AXChannel.resolveRunningApplication`: `if let pid { … } if let bundleId { … }`).
+  // So the loose zod rule let an agent name two different apps and get the one
+  // it did not mean, attached, and acting on the user's screen — with the reply
+  // naming only one of them. Refusing is the only answer that cannot mislead.
+  message: "attach takes exactly one of bundleId or pid, not both and not neither",
+  path: ["bundleId"]
 });
 var ObserveArgs = z5.strictObject({
   maxDepth: OptionalDepthSchema,
@@ -1896,6 +2008,47 @@ var TOOL_SPECS = [
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
+function narrowingKnobsFor(spec, params) {
+  const properties = spec.inputSchema.properties ?? {};
+  const knobs = [];
+  for (const [name, raw] of Object.entries(properties)) {
+    const schema = raw;
+    const sentValue = params[name];
+    const sent = typeof sentValue === "number" ? sentValue : void 0;
+    if (name === "maxDepth") {
+      knobs.push({ name, kind: "depth", minimum: schema.minimum, maximum: schema.maximum, sent });
+    } else if (name === "scale") {
+      knobs.push({ name, kind: "scale", minimum: schema.minimum, maximum: schema.maximum, sent });
+    } else if (name === "limit") {
+      knobs.push({ name, kind: "limit", minimum: schema.minimum, maximum: schema.maximum, sent });
+    } else if (name === "selector" || name === "role" || name === "title") {
+      knobs.push({ name, kind: "selector", sent: void 0 });
+    }
+  }
+  return knobs;
+}
+function describeKnob(knob) {
+  const bounds = knob.minimum !== void 0 && knob.maximum !== void 0 ? ` (this tool advertises ${knob.minimum}\u2026${knob.maximum})` : knob.maximum !== void 0 ? ` (this tool advertises at most ${knob.maximum})` : knob.minimum !== void 0 ? ` (this tool advertises at least ${knob.minimum})` : "";
+  switch (knob.kind) {
+    case "depth":
+      return `a smaller maxDepth${bounds}`;
+    case "limit":
+      return `a smaller limit${bounds}`;
+    case "selector":
+      return knob.name === "selector" ? "a more specific selector (aim at one element)" : `a tighter ${knob.name} filter`;
+    case "scale":
+      return knob.sent !== void 0 && knob.minimum !== void 0 && knob.sent <= knob.minimum ? `scale is already at this tool's floor (${knob.minimum}), so the image cannot be shrunk further here` : `a smaller scale${bounds}${knob.sent !== void 0 ? `, currently ${knob.sent}` : ""}`;
+  }
+}
+function oversizedReplyAdvice(spec, params) {
+  const knobs = narrowingKnobsFor(spec, params);
+  const shrinkable = knobs.filter((knob) => !(knob.kind === "scale" && knob.sent !== void 0 && knob.minimum !== void 0 && knob.sent <= knob.minimum));
+  const head = `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); `;
+  if (shrinkable.length === 0) {
+    return knobs.length > 0 ? head + `${knobs.map(describeKnob).join("; ")} \u2014 nothing left to narrow on this request: ask a smaller question (one element, one region) rather than retrying it unchanged; the connection is intact and the daemon keeps answering other requests` : head + "this tool advertises no parameter that shrinks a reply, so do not retry it unchanged \u2014 ask a smaller question (one element, one region) instead; the connection is intact and the daemon keeps answering other requests";
+  }
+  return head + `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`;
+}
 async function readTrail(session, turn, limit) {
   await turn.acquire();
   try {
@@ -1936,7 +2089,7 @@ function packForReport(pack, measuredSchemaVersion) {
 }
 async function captureView(args, context) {
   try {
-    const raw = await context.engine.call("capture_view", args);
+    const raw = await context.engine.call("capture_view", args, context.session.generation);
     const body = raw ?? {};
     const png = body.pngBase64;
     if (typeof png !== "string" || png.length === 0) {
@@ -2046,9 +2199,12 @@ async function projectGetTool(args) {
     if (entry === void 0) {
       return {
         content: [{ type: "text", text: formatToolError(
-          "GP_E_NOT_FOUND",
+          // Both the code and the remedy come from the one place they are
+          // spelled: this used to retype the literal and the sentence, so a
+          // change to `projectErrorRemedy` left this reply behind (R8-低).
+          GP_E_NOT_FOUND,
           `unknown project ${argv.projectId}`,
-          "check the projectId; use gp_project_list to view available projects"
+          projectErrorRemedy(GP_E_NOT_FOUND)
         ) }],
         isError: true
       };
@@ -2085,6 +2241,9 @@ function projectErrorRemedy(code) {
   if (code === GP_E_NOT_FOUND) {
     return "check the projectId; use gp_project_list to view available projects";
   }
+  if (code === GP_E_NO_USER_RECORD) {
+    return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
+  }
   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.`;
   }
@@ -2094,7 +2253,11 @@ async function exportEvidence(args, context) {
   const argv = args;
   const render2 = argv.format === "html" ? renderHTML : renderMarkdown;
   try {
-    const raw = await context.engine.call("last_evidence", { operationId: argv.operationId });
+    const raw = await context.engine.call(
+      "last_evidence",
+      { operationId: argv.operationId },
+      context.session.generation
+    );
     const { pack, measuredSchemaVersion } = parseEvidenceFrame(raw);
     await context.turn.acquire();
     try {
@@ -2124,7 +2287,11 @@ async function recentReports(args, context) {
   const skipped = [];
   for (const id of ids) {
     try {
-      const raw = await context.engine.call("last_evidence", { operationId: id });
+      const raw = await context.engine.call(
+        "last_evidence",
+        { operationId: id },
+        context.session.generation
+      );
       const parsed = parseEvidenceFrame(raw);
       packs.push({ id, pack: packForReport(parsed.pack, parsed.measuredSchemaVersion) });
     } catch (error) {
@@ -2205,7 +2372,18 @@ function createHttpGateway(options) {
       `createHttpGateway requires a non-empty token (read ${GLASSPANE_HTTP_TOKEN_ENV}); refusing to start with an empty or defaulted token`
     );
   }
-  const client = options.connectController !== void 0 ? options.connectController(options.socketPath) : unixSocketEngineClient(options.socketPath);
+  const report = options.report ?? ((note) => {
+    try {
+      process.stderr.write(`[glasspane-http] ${note}
+`);
+    } catch {
+    }
+  });
+  const client = options.connectController !== void 0 ? options.connectController(options.socketPath) : unixSocketEngineClient(options.socketPath, { surface: "http" });
+  client.onEngineNote?.((note) => report(`engine: ${note}`));
+  client.onLateReply?.(({ method, result }) => {
+    report(`late engine reply to '${method}': ${JSON.stringify(result) ?? String(result)}`);
+  });
   const expectedToken = Buffer.from(options.token, "utf8");
   const server = http.createServer((req, res) => {
     handleHttp(req, res, client, expectedToken).catch((error) => {
@@ -2370,7 +2548,7 @@ async function handleEvidenceAggregate(url, client, res) {
       if (error instanceof EngineCallError && error.code === GP_E_NO_EVIDENCE) {
         skipped.push(operationId);
       } else {
-        await failEngine(res, error);
+        await failEngine(res, error, TOOL_BY_NAME.get("gp_last_evidence"), { operationId });
         return;
       }
     }
@@ -2470,7 +2648,7 @@ async function handleToolForward(name, req, client, res) {
     }
     ok(res, result);
   } catch (error) {
-    await failEngine(res, error);
+    await failEngine(res, error, spec, checked.value);
   }
 }
 function handleEvidenceStats(res) {
@@ -2591,10 +2769,11 @@ function NotFound(res, pathname) {
     "GET /v1/hello, GET /v1/evidence/:operationId, GET /v1/evidence?ids=a,b&format=html, POST /v1/tools/:name"
   );
 }
-async function failEngine(res, error) {
+async function failEngine(res, error, spec, params) {
   if (error instanceof EngineCallError) {
     const status = error.code === GP_E_NO_EVIDENCE ? 404 : 502;
-    fail(res, status, error.code, error.message, error.remedy);
+    const remedy = spec !== void 0 && error.code === GP_E_PAYLOAD_TOO_LARGE ? oversizedReplyAdvice(spec, params ?? {}) : error.remedy;
+    fail(res, status, error.code, error.message, remedy);
     return;
   }
   fail(

package/dist/http-gateway.d.ts

@@ -19,6 +19,20 @@ export interface EngineClientLike {
     call(method: string, params?: Record<string, unknown>): Promise<unknown>;
     /** Present on the real client; optional so a fake may omit it. */
     close?(): void;
+    /**
+     * Sinks for what this gateway cannot answer with: a fact attached to no
+     * request (an id-less frame, a handshake that failed) and the body of a reply
+     * that landed after its caller was already answered. Both are the daemon's
+     * real behaviour, and with no sink they left no trace at all — while the
+     * remedy this gateway hands out tells the caller to go read stderr
+     * (R8-高3). Optional so a fake may omit it; the gateway refuses to *claim* a
+     * log line it did not register for.
+     */
+    onEngineNote?(handler: (note: string) => void): void;
+    onLateReply?(handler: (reply: {
+        method: string;
+        result: unknown;
+    }) => void): void;
 }
 export interface HttpGatewayOptions {
     /** Daemon socket path handed to the engine client (the default connector). */
@@ -29,6 +43,13 @@ export interface HttpGatewayOptions {
     host?: string;
     /** Injectable client factory so tests run without a real socket. */
     connectController?: (socketPath: string) => EngineClientLike;
+    /**
+     * Where to write the facts that have no HTTP response: engine notes and late
+     * replies. Defaults to stderr with this process's own prefix, because the
+     * remedy text this gateway hands out tells a caller to read *this gateway's
+     * stderr* — a promise that has to have a writer behind it (R8-高3).
+     */
+    report?: (note: string) => void;
 }
 export interface HttpGateway {
     server: Server;