glasspane-mcp 1.14.0 → 1.15.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.14.0";
+    readonly version: "1.15.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;
@@ -63,6 +63,13 @@ export interface McpServerDeps {
      * request it refers to stayed in flight and kept acting on the user's screen.
      */
     report?: (note: string) => void;
+    /**
+     * Reads how many replies this shell's stdout writer dropped because the pipe
+     * stopped draining. `gp_diagnose` surfaces it so a dropped reply is visible
+     * in-band rather than only in the log channel; it is wired from `index.ts`,
+     * where the `DrainAwareWriter` that counts them lives.
+     */
+    stdoutDroppedFrames?: () => number;
 }
 export declare class McpServer {
     private readonly deps;
@@ -103,7 +110,7 @@ export declare class McpServer {
  * that back from is this trail (`gp_recent_reports`). A sink that recorded into
  * a second session would look fixed and change nothing.
  */
-export declare function createTrackedMcpServer(engine: EngineJsonRpcClient, report: (note: string) => void): {
+export declare function createTrackedMcpServer(engine: EngineJsonRpcClient, report: (note: string) => void, stdoutDroppedFrames?: () => number): {
     server: McpServer;
     session: EvidenceAuditSession;
 };

package/dist/http-gateway-cli.js

@@ -1730,7 +1730,7 @@ function daemonRestartNotice(filePath) {
   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 \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 one thing this shell cannot see and will not guess from $HOME: `glasspaned --state-dir <root>` moves it to <root>/projects.json, and the socket reports no state root. Read it instead of deriving it \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): 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()}`;
@@ -2054,7 +2054,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
+        role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -2120,7 +2120,8 @@ var TOOL_SPECS = [
       }
     },
     validate: zodBridge(CaptureViewArgs),
-    execute: captureView
+    execute: captureView,
+    reachesDaemon: true
   },
   {
     name: "gp_diagnose",
@@ -2299,7 +2300,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
-var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0 || spec.reachesDaemon === true).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -2699,6 +2700,10 @@ function renderTrailId(id, format) {
 function renderTrailIds(ids, format) {
   return ids.map((id) => renderTrailId(id, format)).join(", ");
 }
+function renderErrorLine(text, format) {
+  const stripped = text.replace(/[\u0000-\u001f\u007f]/g, "\xB7");
+  return format === "html" ? escapeHTML(stripped) : stripped.replace(/[`[\]<>#*\\]/g, "\xB7");
+}
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
     return formatToolErrorShape(error.toBody());
@@ -2708,7 +2713,11 @@ function describeFetchFailure(error) {
     const [first] = mapped.content;
     return first !== void 0 && first.type === "text" ? first.text : "the evidence read failed";
   }
-  return `${GP_E_INTERNAL}: ${String(error)}`;
+  return formatToolError(
+    GP_E_INTERNAL,
+    String(error),
+    "a fetch inside gp_recent_reports failed for a reason that is neither a daemon error frame nor an evidence-shape refusal, so this shell cannot name the cause from here. Read that operation on its own with gp_last_evidence {operationId} \u2014 it answers inside its own deadline and reports the fault by itself \u2014 or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+  );
 }
 async function recentReports(args, context) {
   const argv = args;
@@ -2791,7 +2800,11 @@ async function recentReports(args, context) {
   }
   if (packs.length === 0 && hardFailure !== null) {
     const [first] = hardFailure.mapped.content;
-    const base = first !== void 0 && first.type === "text" ? first.text : `${GP_E_INTERNAL}: the evidence read failed`;
+    const base = first !== void 0 && first.type === "text" ? first.text : formatToolError(
+      GP_E_INTERNAL,
+      "the evidence read failed",
+      "the fetch mapped to an answer this shell could not render as text, so no more than the failure itself is known here. Read the operation on its own with gp_last_evidence {operationId}, which reports its own fault with a remedy, or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+    );
     const extras = [];
     if (notFetched.length > 0) {
       extras.push(`${notFetched.length} further ${notFetched.length === 1 ? "entry" : "entries"} never fetched: ` + renderTrailIds(notFetched, format));
@@ -2834,7 +2847,7 @@ async function recentReports(args, context) {
   const skipNote = skipped.length === 0 ? "" : note("gp-skipped", `skipped ${skipped.length} unreachable ${skipped.length === 1 ? "entry" : "entries"}: ${renderTrailIds(skipped, format)}`);
   const unfetchedNote = notFetched.length === 0 ? "" : format === "html" ? `<p class="gp-not-fetched">not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit</p>` : `> not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit`;
   const rejectNote = rejected.length === 0 ? "" : note("gp-rejected", `${rejectedClause(rejected.length)}${renderTrailIds(rejected, format)}. They were not sent, so nothing was lost by their absence here: gp_last_evidence validates an id the same way before it asks`);
-  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderForeign(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
+  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderErrorLine(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
   const separator = format === "html" ? "\n<hr>\n" : "\n\n---\n";
   const body = packs.map(({ pack }) => render2(pack, void 0)).join(separator);
   const sections2 = [header];

package/dist/http-gateway.js

@@ -1720,7 +1720,7 @@ function daemonRestartNotice(filePath) {
   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 \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 one thing this shell cannot see and will not guess from $HOME: `glasspaned --state-dir <root>` moves it to <root>/projects.json, and the socket reports no state root. Read it instead of deriving it \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): 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()}`;
@@ -2044,7 +2044,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
+        role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -2110,7 +2110,8 @@ var TOOL_SPECS = [
       }
     },
     validate: zodBridge(CaptureViewArgs),
-    execute: captureView
+    execute: captureView,
+    reachesDaemon: true
   },
   {
     name: "gp_diagnose",
@@ -2289,7 +2290,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
-var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0 || spec.reachesDaemon === true).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -2689,6 +2690,10 @@ function renderTrailId(id, format) {
 function renderTrailIds(ids, format) {
   return ids.map((id) => renderTrailId(id, format)).join(", ");
 }
+function renderErrorLine(text, format) {
+  const stripped = text.replace(/[\u0000-\u001f\u007f]/g, "\xB7");
+  return format === "html" ? escapeHTML(stripped) : stripped.replace(/[`[\]<>#*\\]/g, "\xB7");
+}
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
     return formatToolErrorShape(error.toBody());
@@ -2698,7 +2703,11 @@ function describeFetchFailure(error) {
     const [first] = mapped.content;
     return first !== void 0 && first.type === "text" ? first.text : "the evidence read failed";
   }
-  return `${GP_E_INTERNAL}: ${String(error)}`;
+  return formatToolError(
+    GP_E_INTERNAL,
+    String(error),
+    "a fetch inside gp_recent_reports failed for a reason that is neither a daemon error frame nor an evidence-shape refusal, so this shell cannot name the cause from here. Read that operation on its own with gp_last_evidence {operationId} \u2014 it answers inside its own deadline and reports the fault by itself \u2014 or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+  );
 }
 async function recentReports(args, context) {
   const argv = args;
@@ -2781,7 +2790,11 @@ async function recentReports(args, context) {
   }
   if (packs.length === 0 && hardFailure !== null) {
     const [first] = hardFailure.mapped.content;
-    const base = first !== void 0 && first.type === "text" ? first.text : `${GP_E_INTERNAL}: the evidence read failed`;
+    const base = first !== void 0 && first.type === "text" ? first.text : formatToolError(
+      GP_E_INTERNAL,
+      "the evidence read failed",
+      "the fetch mapped to an answer this shell could not render as text, so no more than the failure itself is known here. Read the operation on its own with gp_last_evidence {operationId}, which reports its own fault with a remedy, or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+    );
     const extras = [];
     if (notFetched.length > 0) {
       extras.push(`${notFetched.length} further ${notFetched.length === 1 ? "entry" : "entries"} never fetched: ` + renderTrailIds(notFetched, format));
@@ -2824,7 +2837,7 @@ async function recentReports(args, context) {
   const skipNote = skipped.length === 0 ? "" : note("gp-skipped", `skipped ${skipped.length} unreachable ${skipped.length === 1 ? "entry" : "entries"}: ${renderTrailIds(skipped, format)}`);
   const unfetchedNote = notFetched.length === 0 ? "" : format === "html" ? `<p class="gp-not-fetched">not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit</p>` : `> not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit`;
   const rejectNote = rejected.length === 0 ? "" : note("gp-rejected", `${rejectedClause(rejected.length)}${renderTrailIds(rejected, format)}. They were not sent, so nothing was lost by their absence here: gp_last_evidence validates an id the same way before it asks`);
-  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderForeign(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
+  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderErrorLine(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
   const separator = format === "html" ? "\n<hr>\n" : "\n\n---\n";
   const body = packs.map(({ pack }) => render2(pack, void 0)).join(separator);
   const sections2 = [header];

package/dist/index.js

@@ -780,19 +780,28 @@ var DrainAwareWriter = class {
   get failed() {
     return this.dead !== null;
   }
-  /** How many replies this writer refused to queue. `gp_diagnose` reads it: a
-   * silently-shrinking answer is the failure mode this ceiling replaces. */
+  /**
+   * How many replies this writer refused to queue. `gp_diagnose` reads it and
+   * surfaces it in-band (a reply dropped to a stalled stdout otherwise has no
+   * reader outside the logs): a silently-shrinking answer is the failure mode this
+   * ceiling replaces.
+   */
   get droppedFrames() {
     return this.dropped;
   }
-  /** @param text already framed, including its trailing newline. */
-  async write(text) {
+  /**
+   * @param text already framed, including its trailing newline.
+   * @param requestId the JSON-RPC id the frame answers, so a drop names *which*
+   * reply the agent lost rather than only that one went missing.
+   */
+  async write(text, requestId) {
     if (this.failed) {
       return false;
     }
     if (this.sink.writableLength >= this.backlogLimitBytes) {
       this.dropped += 1;
-      this.report(`reply dropped, not queued: stdout already holds ${this.sink.writableLength} bytes past the ${this.backlogLimitBytes} ceiling \u2014 the reader on the other end stopped consuming, so this frame (and ${this.dropped - 1} earlier one(s)) will not be delivered`);
+      const who = requestId === void 0 || requestId === null ? "a reply" : `reply ${JSON.stringify(requestId)}`;
+      this.report(`${who} dropped, not queued: stdout already holds ${this.sink.writableLength} bytes past the ${this.backlogLimitBytes} ceiling \u2014 the reader on the other end stopped consuming, so this frame (and ${this.dropped - 1} earlier one(s)) will not be delivered`);
       return false;
     }
     let flowing = true;
@@ -2143,7 +2152,7 @@ function daemonRestartNotice(filePath) {
   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 \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 one thing this shell cannot see and will not guess from $HOME: `glasspaned --state-dir <root>` moves it to <root>/projects.json, and the socket reports no state root. Read it instead of deriving it \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): 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()}`;
@@ -2467,7 +2476,7 @@ var TOOL_SPECS = [
       additionalProperties: false,
       properties: {
         maxDepth: { type: "integer", minimum: 1, maximum: 10 },
-        role: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
+        role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH }
       }
     },
     validate: zodBridge(ObserveArgs)
@@ -2533,7 +2542,8 @@ var TOOL_SPECS = [
       }
     },
     validate: zodBridge(CaptureViewArgs),
-    execute: captureView
+    execute: captureView,
+    reachesDaemon: true
   },
   {
     name: "gp_diagnose",
@@ -2712,7 +2722,7 @@ var TOOL_SPECS = [
     execute: projectGetTool
   }
 ];
-var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0).map((spec) => spec.engineMethod);
+var DAEMON_FORWARDED_METHODS = TOOL_SPECS.filter((spec) => spec.execute === void 0 || spec.reachesDaemon === true).map((spec) => spec.engineMethod);
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
@@ -2895,7 +2905,7 @@ function shellFaultRemedy(engineMethod) {
   }
   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) {
+async function executeTool(spec, args, engine, session, stdoutDroppedFrames) {
   if (!session) {
     return {
       content: [{ type: "text", text: formatToolError(
@@ -2919,16 +2929,16 @@ async function executeTool(spec, args, engine, session) {
   }
   const advised = engineWithPayloadAdvice(engine, spec, checked.value);
   if (!trailScopedTool(spec)) {
-    return runValidatedTool(spec, checked.value, advised, session, INERT_TRAIL_TURN);
+    return runValidatedTool(spec, checked.value, advised, session, INERT_TRAIL_TURN, stdoutDroppedFrames);
   }
   const turn = session.claimTrailTurn();
   try {
-    return await runValidatedTool(spec, checked.value, advised, session, turn);
+    return await runValidatedTool(spec, checked.value, advised, session, turn, stdoutDroppedFrames);
   } finally {
     turn.release();
   }
 }
-async function runValidatedTool(spec, value, engine, session, turn) {
+async function runValidatedTool(spec, value, engine, session, turn, stdoutDroppedFrames) {
   if (spec.execute !== void 0) {
     return spec.execute(value, { engine, session, turn });
   }
@@ -2955,6 +2965,15 @@ async function runValidatedTool(spec, value, engine, session, turn) {
 ${caBundleDiagnosis(reading.ca, updaterEnableCommand(reading.runtime))}
 ${runtimeSelfDiagnosis(reading.runtime, reading.stateFile)}` : reading.summary
       });
+      if (stdoutDroppedFrames !== void 0) {
+        const dropped = stdoutDroppedFrames();
+        if (dropped > 0) {
+          content.push({
+            type: "text",
+            text: `stdout backlog: this shell dropped ${dropped} ${dropped === 1 ? "reply" : "replies"} since startup because the reader on the other end stopped consuming them, so an answer you expected to receive may never have been written. The operation itself is unaffected \u2014 this is the byte stream, not the daemon. Drain stdout (close whatever is holding the pipe), then re-read the specific operation with gp_last_evidence {operationId}; do not re-run gp_act to regenerate work the trail already records`
+          });
+        }
+      }
     }
     return {
       content,
@@ -3357,6 +3376,10 @@ function renderTrailId(id, format) {
 function renderTrailIds(ids, format) {
   return ids.map((id) => renderTrailId(id, format)).join(", ");
 }
+function renderErrorLine(text, format) {
+  const stripped = text.replace(/[\u0000-\u001f\u007f]/g, "\xB7");
+  return format === "html" ? escapeHTML(stripped) : stripped.replace(/[`[\]<>#*\\]/g, "\xB7");
+}
 function describeFetchFailure(error) {
   if (error instanceof EngineCallError) {
     return formatToolErrorShape(error.toBody());
@@ -3366,7 +3389,11 @@ function describeFetchFailure(error) {
     const [first] = mapped.content;
     return first !== void 0 && first.type === "text" ? first.text : "the evidence read failed";
   }
-  return `${GP_E_INTERNAL}: ${String(error)}`;
+  return formatToolError(
+    GP_E_INTERNAL,
+    String(error),
+    "a fetch inside gp_recent_reports failed for a reason that is neither a daemon error frame nor an evidence-shape refusal, so this shell cannot name the cause from here. Read that operation on its own with gp_last_evidence {operationId} \u2014 it answers inside its own deadline and reports the fault by itself \u2014 or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+  );
 }
 async function recentReports(args, context) {
   const argv = args;
@@ -3449,7 +3476,11 @@ async function recentReports(args, context) {
   }
   if (packs.length === 0 && hardFailure !== null) {
     const [first] = hardFailure.mapped.content;
-    const base = first !== void 0 && first.type === "text" ? first.text : `${GP_E_INTERNAL}: the evidence read failed`;
+    const base = first !== void 0 && first.type === "text" ? first.text : formatToolError(
+      GP_E_INTERNAL,
+      "the evidence read failed",
+      "the fetch mapped to an answer this shell could not render as text, so no more than the failure itself is known here. Read the operation on its own with gp_last_evidence {operationId}, which reports its own fault with a remedy, or ask again with a smaller limit. Do not re-run gp_act to regenerate what the trail already holds"
+    );
     const extras = [];
     if (notFetched.length > 0) {
       extras.push(`${notFetched.length} further ${notFetched.length === 1 ? "entry" : "entries"} never fetched: ` + renderTrailIds(notFetched, format));
@@ -3492,7 +3523,7 @@ async function recentReports(args, context) {
   const skipNote = skipped.length === 0 ? "" : note("gp-skipped", `skipped ${skipped.length} unreachable ${skipped.length === 1 ? "entry" : "entries"}: ${renderTrailIds(skipped, format)}`);
   const unfetchedNote = notFetched.length === 0 ? "" : format === "html" ? `<p class="gp-not-fetched">not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit</p>` : `> not fetched within this report's ${RECENT_REPORTS_BUDGET_MS}ms wait: ${notFetched.length} ${notFetched.length === 1 ? "entry" : "entries"} left unanswered: ${renderTrailIds(notFetched, format)}. Fetch one by id with gp_last_evidence, or ask again with a smaller limit`;
   const rejectNote = rejected.length === 0 ? "" : note("gp-rejected", `${rejectedClause(rejected.length)}${renderTrailIds(rejected, format)}. They were not sent, so nothing was lost by their absence here: gp_last_evidence validates an id the same way before it asks`);
-  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderForeign(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
+  const failureNote = hardFailure === null ? "" : note("gp-fetch-failed", `the report stops here: ${renderTrailId(hardFailure.id, format)} failed with ${renderErrorLine(hardFailure.line, format)}. The ${packs.length} ${packs.length === 1 ? "pack" : "packs"} above were fetched and are rendered; read the failed one on its own with gp_last_evidence {operationId}. Do not re-run gp_act to regenerate what the trail already holds`);
   const separator = format === "html" ? "\n<hr>\n" : "\n\n---\n";
   const body = packs.map(({ pack }) => render(pack, void 0)).join(separator);
   const sections2 = [header];
@@ -3793,7 +3824,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.14.0" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.15.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -3912,7 +3943,13 @@ var McpServer = class {
     if (!spec) {
       return this.error(INVALID_PARAMS, `Unknown tool: ${name}`, id);
     }
-    const outcome = await executeTool(spec, params.arguments ?? {}, this.deps.engine, this.session);
+    const outcome = await executeTool(
+      spec,
+      params.arguments ?? {},
+      this.deps.engine,
+      this.session,
+      this.deps.stdoutDroppedFrames
+    );
     return this.result(id, { content: outcome.content, isError: outcome.isError });
   }
   asParams(rawParams) {
@@ -3935,7 +3972,7 @@ var McpServer = class {
     return { jsonrpc: JSONRPC, id, error: { code, message } };
   }
 };
-function createTrackedMcpServer(engine, report) {
+function createTrackedMcpServer(engine, report, stdoutDroppedFrames) {
   const session = new EvidenceAuditSession();
   engine.onLateReply(({ method, result, correlation, attribution }) => {
     if (correlation !== void 0 && correlation !== session.generation) {
@@ -3969,7 +4006,7 @@ function createTrackedMcpServer(engine, report) {
       }
     );
   });
-  return { server: new McpServer({ engine, session, report }), session };
+  return { server: new McpServer({ engine, session, report, stdoutDroppedFrames }), session };
 }
 function describeAttach(result) {
   if (typeof result !== "object" || result === null) {
@@ -4113,12 +4150,13 @@ function main() {
   const replies = new DrainAwareWriter(process2.stdout, logNote, DRAIN_WAIT_MS, () => shutdown());
   const queue = new OrderedReplyQueue((error) => logNote(`reply failed: ${String(error)}`));
   engine.onEngineNote(logNote);
-  const server = createTrackedMcpServer(engine, logNote).server;
+  const server = createTrackedMcpServer(engine, logNote, () => replies.droppedFrames).server;
   const writeResponse = async (response) => {
     if (response === null) {
       return;
     }
-    await replies.write(canonicalJson(response) + "\n");
+    const id = response.id;
+    await replies.write(canonicalJson(response) + "\n", id);
   };
   const reader = new LineReader({
     onLine: (line) => {
@@ -4138,7 +4176,7 @@ function main() {
     queue.push(async () => shutdown());
   });
   process2.stdin.on("close", () => queue.push(async () => shutdown()));
-  process2.on("SIGINT", shutdown);
-  process2.on("SIGTERM", shutdown);
+  process2.on("SIGINT", () => queue.push(async () => shutdown()));
+  process2.on("SIGTERM", () => queue.push(async () => shutdown()));
 }
 main();

package/dist/io.d.ts

@@ -155,11 +155,19 @@ export declare class DrainAwareWriter {
     private dropped;
     constructor(sink: Writable, report: (note: string) => void, drainWaitMs: number, onDead: (error: Error) => void, backlogLimitBytes?: number);
     get failed(): boolean;
-    /** How many replies this writer refused to queue. `gp_diagnose` reads it: a
-     * silently-shrinking answer is the failure mode this ceiling replaces. */
+    /**
+     * How many replies this writer refused to queue. `gp_diagnose` reads it and
+     * surfaces it in-band (a reply dropped to a stalled stdout otherwise has no
+     * reader outside the logs): a silently-shrinking answer is the failure mode this
+     * ceiling replaces.
+     */
     get droppedFrames(): number;
-    /** @param text already framed, including its trailing newline. */
-    write(text: string): Promise<boolean>;
+    /**
+     * @param text already framed, including its trailing newline.
+     * @param requestId the JSON-RPC id the frame answers, so a drop names *which*
+     * reply the agent lost rather than only that one went missing.
+     */
+    write(text: string, requestId?: number | string | null): Promise<boolean>;
     private waitForDrain;
 }
 //# sourceMappingURL=io.d.ts.map

package/dist/project-registry.d.ts

@@ -147,7 +147,8 @@ export declare function projectSet(args: ProjectSetArgs): ProjectSetResult;
  * with no state root. `glasspaned --state-dir <root>` makes it load
  * `<root>/projects.json` (`ProjectRegistry(stateRoot:)`, and every subcommand
  * resolves through the same root), and the socket cannot be asked which root the
- * running job chose — the method table is frozen and reports no state root. So a
+ * running job chose — since 1.15.0 the daemon says so in `hello`'s `stateRoot`, while a
+ * service still running an older binary does not. So a
  * notice that simply ordered a restart was telling an agent that restarting would
  * help in the one case where it cannot, and a notice that said "this is the file
  * the service loads" was naming a file the service may not load. Both branches

package/dist/tools.d.ts

@@ -258,6 +258,15 @@ export interface ToolSpec {
      * packs and render them through the report generator.
      */
     execute?: (args: Record<string, unknown>, context: ToolExecuteContext) => Promise<ToolResult>;
+    /**
+     * True for a tool that has its own `execute` yet still puts a real daemon
+     * method on the wire (`gp_capture_view`'s executor calls `capture_view`), so
+     * `hello.capabilities` reconciliation must count its `engineMethod` as
+     * forwarded. Left unset on genuinely shell-only tools (`gp_recent_reports`,
+     * the project tools), whose `engineMethod` is a pseudo-method the daemon does
+     * not advertise and would answer with `methodNotFound`.
+     */
+    reachesDaemon?: true;
 }
 export interface ToolExecuteContext {
     engine: EngineJsonRpcClient;
@@ -294,6 +303,15 @@ export declare const TOOL_SPECS: readonly ToolSpec[];
  * (`engine-client.describeCapabilityDrift`): a hand-copied second truth is the
  * exact drift the reader exists to catch, and the gateway already derives its own
  * forwardable set from `execute === undefined` for the same reason.
+ *
+ * `execute === undefined` alone under-counts: `gp_capture_view` has its own
+ * executor, yet that executor calls `capture_view` on the wire, so the daemon
+ * advertises a method the agent *can* reach and the reconciliation would report
+ * as unreachable from MCP. `reachesDaemon` marks exactly those executor tools
+ * that still forward a real daemon method; `test/shell-2026-defects.test.mjs`
+ * cross-checks this set against both the daemon's advertised capability names and
+ * the literal `.call("…")` sites so neither a new omission nor a stale pseudo-
+ * method survives silently.
  */
 export declare const DAEMON_FORWARDED_METHODS: readonly string[];
 export declare const TOOL_BY_NAME: ReadonlyMap<string, ToolSpec>;
@@ -422,7 +440,14 @@ export declare function executeTool(spec: ToolSpec, args: unknown, engine: Engin
  * 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>;
+session: EvidenceAuditSession, 
+/**
+ * Reads how many replies this shell's stdout writer dropped under backpressure,
+ * so `gp_diagnose` can surface a lost reply in-band. Optional: only `index.ts`
+ * owns the writer, and a caller without one (tests, the HTTP gateway) leaves it
+ * undefined and the tool stays silent.
+ */
+stdoutDroppedFrames?: () => number): 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
@@ -451,6 +476,14 @@ export declare function parseEvidenceFrame(raw: unknown): {
  * byte-identical to the shared golden.
  */
 export declare function packForReport(pack: EvidencePack, measuredSchemaVersion: string): EvidencePackReportView;
+/**
+ * One fetch failure, in the one line a partial report has room for.
+ * Exported for `test/shell-2026-defects.test.mjs`, which pins the
+ * `{code, message, remedy}` shape of the fallback arm: that arm is what a
+ * non-daemon, non-shape error reaches, and a two-field string there is an error
+ * frame leaving the shell with no next move.
+ */
+export declare function describeFetchFailure(error: unknown): string;
 export type { Selector, Action, AssertionProperty };
 /**
  * The engine view handed to one tool: the same client, with one kind of error's

package/package.json

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

package/schemas/convergence-round-state.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.iterate.dev/convergence-round-state-0.1.json",
+  "title": "ConvergenceRoundState",
+  "description": "What a caller states about the round that just finished, which the convergence rules turn into an action (5.7 R40 scenario 4). Every field is a verdict somebody else produced; this contract moves none of them. NOTE ON SOURCE OF TRUTH: the field constraints are duplicated from `src/convergence.ts`, which is the definition; this file mirrors it. The ordering that decides which verdict wins (breaker, then budget, then errored check, then findings, then evidence, then invariants, then converged) is arithmetic in the validator and cannot be expressed in JSON Schema — a schema-only implementation must re-implement `convergenceDecision` and be tested against the cases in `fixtures/convergence.ok-01.json`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["round", "maxRounds", "invariantState", "openFindings", "evidenceComplete", "breakerLevel"],
+  "properties": {
+    "schemaVersion": {
+      "const": "iterate.convergence/0.1"
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "maxRounds": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "invariantState": {
+      "enum": ["pass", "fail", "error", "unmeasured"]
+    },
+    "openFindings": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "evidenceComplete": {
+      "type": "boolean"
+    },
+    "breakerLevel": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 3
+    }
+  }
+}

package/schemas/decision-log-entry.schema.json

@@ -40,6 +40,26 @@
     "createdAt": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "kind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,31}$",
+      "description": "What sort of decision this line records, in the recording ecosystem's own vocabulary (iterate uses round_start / review_result / atomic_fix / …, the GlassPane fork records tool executions). Deliberately NOT an enum: the kernel does not own either vocabulary, and enumerating them would make every new producer kind a kernel release. See the module doc in src/decision-log-entry.ts."
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Loop position the decision belongs to, when the producer counts rounds. Optional because a one-off tool execution is not part of a round."
+    },
+    "dimension": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 64,
+      "description": "The dimension this decision was serving, using the same id rule as dimension-context (DIMENSION_ID_PATTERN / DIMENSION_ID_MAX_LENGTH, imported not restated). This is what lets a recorded decision count toward 'N/M dimensions verified' from either ecosystem."
+    },
+    "payload": {
+      "type": "object",
+      "description": "Structured detail carried alongside the human-readable summary — the field the legacy 'data' object maps onto. NOTE A BOUND THE SCHEMA CANNOT STATE: the canonical-JSON form of this object is limited to PAYLOAD_MAX_CANONICAL_LENGTH (8192) characters by the TypeScript validator and the Python port, because an unbounded field in a hash-chained ledger lets a line's bytes and digest grow without limit. JSON Schema has no way to bound serialized length, so this is a documented divergence, pinned as a named case in kernel/test/decision-log-entry.test.mjs rather than silently allowed."
     }
   }
 }

package/schemas/evidence-pack.schema.json

@@ -197,16 +197,19 @@
         "role": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 512
+          "maxLength": 512,
+          "description": "What the target is, in the accessibility tree's own vocabulary. Never empty: the engine's matcher reads an empty role as 'no constraint stated', so an empty role stops naming what the assertion targets instead of narrowing it — and the daemon refuses it."
         },
         "title": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 512
+          "maxLength": 512,
+          "description": "Optional display label. When present it is never empty, for the same reason as role: a report rendered from `title: \"\"` prints a missing label and reads as 'the tree had no title there'."
         },
         "identifier": {
           "type": "string",
-          "maxLength": 512
+          "maxLength": 512,
+          "description": "Optional AXIdentifier. Deliberately has no minLength: no side rules on an empty identifier (the daemon has no guard for it), so the kernel does not invent one."
         }
       }
     },

package/schemas/invariant-report.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.iterate.dev/invariant-report-0.1.json",
+  "title": "InvariantReport",
+  "description": "What the invariant runner observed when it checked a recipe's invariants (5.7 R40 scenario 1: the failure that has to reach the other harness). Whoever runs the checks produces this; whoever decides whether to re-verify reads it. A check kind of `refused` means the runner declined to execute a configured command because it carries shell metacharacters or is empty — it is a violation, so a report whose only failing check was refused is `fail`, never `error`. NOTE ON SOURCE OF TRUTH: the check-name and detail constraints are duplicated from `src/invariant-report.ts`, which is the definition; this file mirrors it. The outcome-vs-checks rule IS expressible here and is expressed twice on purpose: the `allOf` branches below and the zod `superRefine` must refuse the same reports, so a second implementation that only validates JSON Schema still cannot carry a pass over a failed check.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "outcome", "checks"],
+  "properties": {
+    "schemaVersion": {
+      "const": "iterate.invariant-report/0.1"
+    },
+    "outcome": {
+      "enum": ["pass", "fail", "error"]
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/$defs/invariantCheck"
+      }
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "durationMs": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "pass"
+          }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "checks": {
+            "items": {
+              "properties": {
+                "ok": {
+                  "const": true
+                }
+              },
+              "required": ["ok"]
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "fail"
+          }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "checks": {
+            "contains": {
+              "properties": {
+                "ok": {
+                  "const": false
+                }
+              },
+              "required": ["ok"]
+            },
+            "minContains": 1
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "invariantCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "kind", "ok"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "kind": {
+          "enum": ["ensure", "command", "refused"]
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "detail": {
+          "type": "string",
+          "maxLength": 4096
+        }
+      }
+    }
+  }
+}

package/schemas/provider-registration.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.iterate.dev/provider-registration-0.1.json",
+  "title": "ProviderRegistration",
+  "description": "Metadata for one judgement producer, so both harnesses can consume the same provider through the same shape (5.7 R40 scenario 5). It declares who provides what and what they need; it never carries a judgement, which stays in the engine and the reviewers. NOTE ON SOURCE OF TRUTH: the field constraints are duplicated from `src/provider-registration.ts`, which is the definition; this file mirrors it. METHOD-LEVEL UNIQUENESS IS ENFORCED BY ZOD ONLY: `uniqueItems` compares whole objects, so two methods with the same name but different `requires` pass this schema and are refused by `ProviderRegistrationSchema`. The registry semantics (refusing to overwrite an id, no default provider, no fuzzy resolve) are functions in the validator, not schema features.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "kind", "version", "methods"],
+  "properties": {
+    "schemaVersion": {
+      "const": "iterate.provider/0.1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 64
+    },
+    "kind": {
+      "enum": ["ae-diagnosis", "report-render", "evidence-source"]
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "origin": {
+      "enum": ["kernel", "glasspane", "iterate", "plugin"]
+    },
+    "methods": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/providerMethod"
+      }
+    }
+  },
+  "$defs": {
+    "providerMethod": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "requires"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "maxLength": 64
+        },
+        "requires": {
+          "type": "array",
+          "maxItems": 16,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 64
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/reverification-request.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.iterate.dev/reverification-request-0.1.json",
+  "title": "ReverificationRequest",
+  "description": "The ask that comes out of a failed invariant report (5.7 R40 scenario 1): re-run these recipe steps, dimensions, or operations. It cites the failure by digest rather than embedding it, so the ledger line that records the re-verification can be checked against the ledger line that records the failure. NOTE ON SOURCE OF TRUTH: the field constraints are duplicated from `src/invariant-report.ts`, which is the definition; this file mirrors it. The 'an empty target set is not a re-verification' rule IS expressible here and is expressed twice on purpose, via `anyOf`, so a schema-only implementation refuses it too.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "trigger", "targets"],
+  "properties": {
+    "schemaVersion": {
+      "const": "iterate.reverification/0.1"
+    },
+    "trigger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "reportDigest"],
+      "properties": {
+        "kind": {
+          "const": "invariant"
+        },
+        "reportDigest": {
+          "type": "string",
+          "pattern": "^iv_[0-9a-f]{64}$"
+        }
+      }
+    },
+    "targets": {
+      "type": "object",
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": ["recipeSteps"]
+        },
+        {
+          "required": ["dimensions"]
+        },
+        {
+          "required": ["operationIds"]
+        }
+      ],
+      "properties": {
+        "recipeSteps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/recipeStep"
+          }
+        },
+        "dimensions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 64
+          }
+        },
+        "operationIds": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^op_[0-9A-HJKMNP-TV-Z]{26}$"
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "recipeStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "params"],
+      "properties": {
+        "kind": {
+          "enum": ["act", "observe", "assert", "diagnose"]
+        },
+        "params": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}

package/schemas/run-plan.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.iterate.dev/run-plan-0.1.json",
+  "title": "RunPlan",
+  "description": "Which review dimensions a run intends to cover, in planned order (5.7 R40 scenario 2: dimension-aware context compression needs a plan to be aware of). Whoever configures the run produces this; whoever renders coverage reads it. Nothing in the kernel reads a config file to make one. NOTE ON SOURCE OF TRUTH: the id/label/focus constraints are duplicated from `src/dimension-context.ts`, which has no JSON Schema of its own — until that gap is closed, the zod side is the definition and this file mirrors it. ID-LEVEL UNIQUENESS IS ENFORCED BY ZOD ONLY: `uniqueItems` compares whole objects, so two entries with the same id but different focus pass this schema and are refused by `RunPlanSchema`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "dimensions"],
+  "properties": {
+    "schemaVersion": {
+      "const": "iterate.run-plan/0.1"
+    },
+    "dimensions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/plannedDimension"
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "enum": ["config", "recipe", "session", "manual"]
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        }
+      }
+    }
+  },
+  "$defs": {
+    "plannedDimension": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "maxLength": 64
+        },
+        "label": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "focus": {
+          "type": "string",
+          "maxLength": 4096
+        }
+      }
+    }
+  }
+}