glasspane-mcp 1.3.1 → 1.4.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.3.1";
+    readonly version: "1.4.0";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;

package/dist/engine-client.d.ts

@@ -139,6 +139,28 @@ export declare const RESTORE_BASE_DEADLINE_MS = 30000;
 export declare function isReplayUnsafeMethod(method: string): boolean;
 /** The non-replayable methods, for gates that must see the set change on purpose. */
 export declare const REPLAY_UNSAFE_METHOD_NAMES: readonly string[];
+/**
+ * Methods whose re-issue writes daemon state the *caller* depends on, even though
+ * replaying them is not unsafe in the sense {@link REPLAY_UNSAFE_REASONS} means
+ * (no operation of the user's is performed a second time). They are the other half
+ * of the answer to "may this be narrowed by sending it again?", and they are kept
+ * apart from the set above because `test/probe-liveness.test.mjs` pins that set's
+ * membership as the no-replay judgement.
+ *
+ * `snapshot` is here because of a ring, not of a click: `storeSnapshot`
+ * (`engine/Sources/GlassPaneEngine/EngineCore.swift:2070`) appends the new
+ * baseline and then trims oldest-first to `EngineCore.snapshotHistoryLimit` (the
+ * same file, line 25 — 8 entries). A `gp_snapshot` whose caller timed out may
+ * therefore have been carried out already, and every re-send — "with a smaller
+ * maxDepth", which is what the tool layer used to say — adds another entry that can
+ * evict the baseline the caller's *own earlier* snapshot returned, the one
+ * `gp_restore {snapshotId}` needs later. Evicting a caller's evidence to fetch a
+ * cheaper copy of it is not narrowing.
+ *
+ * `attach` writes state too, and is already a replay-unsafe method; `tools.ts`
+ * unions the two lists rather than repeating names here.
+ */
+export declare const STATE_CHANGING_ON_RETRY_METHOD_NAMES: readonly string[];
 /** Deadline for one request; `restore` scales with its replayed step count. */
 export declare function engineDeadlineMs(method: string, params?: Record<string, unknown>): number;
 /** When the caller gets its answer for `method`: its deadline, capped. */
@@ -366,6 +388,12 @@ export declare class EngineJsonRpcClient {
      * Oldest request this client still tracks, settled ones included: that is the
      * request the daemon's arrival-ordered answer belongs to. `Map` iteration is
      * insertion order, which is the order the requests went out.
+     *
+     * An entry whose id-less answer has already been taken (`arrivalOrderConsumed`)
+     * is passed over for *this* purpose while staying in the map for the echoed-id
+     * lookup: the guess has been spent once and may not be spent again on the next
+     * id-less frame, and the request it was spent on is still the request whose real
+     * reply can arrive with its id (finding 中-4).
      */
     private oldestTracked;
     /**

package/dist/http-gateway-cli.js

@@ -219,6 +219,7 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
     const steps = params?.steps;
@@ -275,6 +276,10 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function clientClosingRemedy(surface) {
+  const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
+  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 reIssueGuidance(surface) {
   return `wait for the outstanding reply rather than sending this request again: the daemon answers one request at a time, so a second copy of it now only queues behind the one still running and answers nothing sooner, and if the first did take effect the copy performs it a second time. What is worth narrowing here, and whether it can still be narrowed at the values this request already sent, is a fact about a schema, and this layer holds no schema for any request: ${NARROWING_AUTHORITY[surface]}. Re-send only after reading that, and only if the request is one whose repetition changes nothing`;
 }
@@ -430,8 +435,8 @@ var EngineJsonRpcClient = class {
     this.state.closed = true;
     this.teardown(new EngineCallError(
       GP_E_ENGINE_UNREACHABLE,
-      "engine client closed",
-      daemonUnreachableRemedy()
+      "engine client closed: this shell's own client is ending, so whether the daemon finished this request is not known here and this client can no longer attribute the reply that may still land",
+      clientClosingRemedy(this.surface)
     ));
     this.io.close();
   }
@@ -480,7 +485,11 @@ var EngineJsonRpcClient = class {
     if (typeof id === "number") {
       const entry = this.pending.get(id);
       if (!entry) {
-        this.report(`engine sent a frame for request id ${id}, which this client never issued (or already gave up on): ${truncate(line)}`);
+        const tracked = [...this.pending.values()];
+        const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
+        this.report(
+          `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
+        );
         return;
       }
       this.pending.delete(id);
@@ -495,8 +504,9 @@ var EngineJsonRpcClient = class {
       const target = this.oldestTracked();
       if (target) {
         if (target.settled) {
-          this.pending.delete(target.id);
           this.reportLateReply(target, frame, true);
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         if (frame.error) {
@@ -557,9 +567,20 @@ var EngineJsonRpcClient = class {
    * Oldest request this client still tracks, settled ones included: that is the
    * request the daemon's arrival-ordered answer belongs to. `Map` iteration is
    * insertion order, which is the order the requests went out.
+   *
+   * An entry whose id-less answer has already been taken (`arrivalOrderConsumed`)
+   * is passed over for *this* purpose while staying in the map for the echoed-id
+   * lookup: the guess has been spent once and may not be spent again on the next
+   * id-less frame, and the request it was spent on is still the request whose real
+   * reply can arrive with its id (finding 中-4).
    */
   oldestTracked() {
-    return this.pending.values().next().value;
+    for (const entry of this.pending.values()) {
+      if (!entry.arrivalOrderConsumed) {
+        return entry;
+      }
+    }
+    return void 0;
   }
   /**
    * Route the reply that lands after its caller was already answered. `inferred`
@@ -1041,8 +1062,8 @@ var LEGACY_EVIDENCE_SCHEMA_VERSION = "glasspane.evidence/0.1-draft";
 var AttributionLevelSchema = z.enum(["soft", "strong", "weak"]);
 var CircuitBreakerLevelSchema = z.number().int().min(0).max(3);
 var SelectorSchema = z.strictObject({
-  role: z.string().max(SELECTOR_MAX_LENGTH),
-  title: z.string().max(SELECTOR_MAX_LENGTH).optional(),
+  role: z.string().min(1).max(SELECTOR_MAX_LENGTH),
+  title: z.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
   identifier: z.string().max(SELECTOR_MAX_LENGTH).optional()
 });
 var ActionSchema = z.enum([
@@ -1794,14 +1815,9 @@ var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
 var ExpectSchema = z5.union([z5.string().max(512), z5.boolean()]);
-var ShellSelectorSchema = z5.strictObject({
-  role: z5.string().min(1).max(SELECTOR_MAX_LENGTH),
-  title: z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
-  identifier: z5.string().max(SELECTOR_MAX_LENGTH).optional()
-});
 var SnapshotIdSchema = z5.string().regex(/^snap_[0-9A-HJKMNP-TV-Z]{26}$/);
 var ActStepSchema = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema
 });
 var RestoreStepsSchema = z5.array(ActStepSchema).min(1).max(64).optional();
@@ -1841,12 +1857,12 @@ var AuditUiArgs = z5.strictObject({
   minHitTargetPt: OptionalHitTargetSchema
 });
 var ActArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema,
   degrade: z5.boolean().optional()
 });
 var AssertElementArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   property: AssertionPropertySchema,
   expected: ExpectSchema
 });
@@ -1890,9 +1906,11 @@ var selectorJsonSchema = {
   type: "object",
   additionalProperties: false,
   properties: {
-    // `minLength` here is the advertised half of {@link ShellSelectorSchema};
+    // `minLength` here is the advertised half of the kernel's `SelectorSchema`;
     // `test/tools.test.mjs` compares the two against each other and against the
-    // daemon's own rule, so neither side can be tightened or loosened alone.
+    // daemon's own rule, and `test/consumer-consistency.test.mjs` compares both
+    // against the published `kernel/schemas/evidence-pack.schema.json`, so no
+    // side can be tightened or loosened alone.
     role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     title: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     identifier: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
@@ -2176,6 +2194,25 @@ var TOOL_SPECS = [
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
+var TARGET_SELECTING_KNOBS = {
+  gp_act: {
+    param: "selector",
+    picks: "which control the action is performed on",
+    substitute: "a different control takes the press, and the user's screen changes in a way no one asked for"
+  },
+  gp_assert_element: {
+    param: "selector",
+    picks: "which element the claim is about",
+    substitute: "the answer then describes a different element, while this session's trail still files it as the verdict on the claim you first made"
+  }
+};
+function targetSelectingKnob(specName, paramName) {
+  if (!Object.prototype.hasOwnProperty.call(TARGET_SELECTING_KNOBS, specName)) {
+    return null;
+  }
+  const entry = TARGET_SELECTING_KNOBS[specName];
+  return entry !== void 0 && entry.param === paramName ? { picks: entry.picks, substitute: entry.substitute } : null;
+}
 function narrowingKnobsFor(spec, params) {
   const properties = spec.inputSchema.properties ?? {};
   const knobs = [];
@@ -2190,11 +2227,21 @@ function narrowingKnobsFor(spec, params) {
     } 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 });
+      const target = targetSelectingKnob(spec.name, name);
+      knobs.push(target === null ? { name, kind: "selector", sent: void 0 } : { name, kind: "target", sent: void 0, picks: target.picks, substitute: target.substitute });
     }
   }
   return knobs;
 }
+function replyShrinkingKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind !== "target");
+}
+function targetKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind === "target");
+}
+function describeTargetKnob(knob) {
+  return `'${knob.name}' names ${knob.picks ?? "which element this operation is about"}, so changing it is not a smaller or cheaper request \u2014 it is a different operation, and ${knob.substitute ?? "the answer then describes something else"}`;
+}
 function atAdvertisedFloor(knob) {
   return knob.minimum !== void 0 && knob.sent !== void 0 && knob.sent <= knob.minimum;
 }
@@ -2208,6 +2255,8 @@ function knobSubject(kind) {
       return "the image";
     case "selector":
       return "the reply";
+    case "target":
+      return "the element the operation is about";
   }
 }
 function describeKnob(knob) {
@@ -2224,19 +2273,27 @@ function describeKnob(knob) {
       return knob.name === "selector" ? "a more specific selector (aim at one element)" : `a tighter ${knob.name} filter`;
     case "scale":
       return `a smaller scale${bounds}${knob.sent !== void 0 ? `, currently ${knob.sent}` : ""}`;
+    case "target":
+      return describeTargetKnob(knob);
   }
 }
 function oversizedReplyAdvice(spec, params) {
   const knobs = narrowingKnobsFor(spec, params);
   const atFloor = knobs.filter(atAdvertisedFloor);
-  const shrinkable = knobs.filter((knob) => !atAdvertisedFloor(knob));
+  const target = targetKnobs(knobs);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
   const head = `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); `;
-  const floorNote = atFloor.length === 0 ? "" : `${atFloor.map(describeKnob).join("; ")}; `;
+  const refused = [...atFloor.map(describeKnob), ...target.map(describeTargetKnob)];
+  const floorNote = refused.length === 0 ? "" : `${refused.join("; ")}; `;
   if (shrinkable.length === 0) {
-    return knobs.length > 0 ? head + `${atFloor.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 knobs.length > 0 ? head + floorNote + "nothing left to narrow on this request: " + (target.length > 0 ? "this request already carries one element and one region, so read the tree with gp_observe and, if the element you meant is another one, make that its own claim rather than treating this answer as a size problem" : "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 + 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 NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
+  ...REPLAY_UNSAFE_METHOD_NAMES,
+  ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
+]);
 async function readTrail(session, turn, limit) {
   await turn.acquire();
   try {

package/dist/http-gateway.js

@@ -215,6 +215,7 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
     const steps = params?.steps;
@@ -271,6 +272,10 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function clientClosingRemedy(surface) {
+  const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
+  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 reIssueGuidance(surface) {
   return `wait for the outstanding reply rather than sending this request again: the daemon answers one request at a time, so a second copy of it now only queues behind the one still running and answers nothing sooner, and if the first did take effect the copy performs it a second time. What is worth narrowing here, and whether it can still be narrowed at the values this request already sent, is a fact about a schema, and this layer holds no schema for any request: ${NARROWING_AUTHORITY[surface]}. Re-send only after reading that, and only if the request is one whose repetition changes nothing`;
 }
@@ -426,8 +431,8 @@ var EngineJsonRpcClient = class {
     this.state.closed = true;
     this.teardown(new EngineCallError(
       GP_E_ENGINE_UNREACHABLE,
-      "engine client closed",
-      daemonUnreachableRemedy()
+      "engine client closed: this shell's own client is ending, so whether the daemon finished this request is not known here and this client can no longer attribute the reply that may still land",
+      clientClosingRemedy(this.surface)
     ));
     this.io.close();
   }
@@ -476,7 +481,11 @@ var EngineJsonRpcClient = class {
     if (typeof id === "number") {
       const entry = this.pending.get(id);
       if (!entry) {
-        this.report(`engine sent a frame for request id ${id}, which this client never issued (or already gave up on): ${truncate(line)}`);
+        const tracked = [...this.pending.values()];
+        const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
+        this.report(
+          `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
+        );
         return;
       }
       this.pending.delete(id);
@@ -491,8 +500,9 @@ var EngineJsonRpcClient = class {
       const target = this.oldestTracked();
       if (target) {
         if (target.settled) {
-          this.pending.delete(target.id);
           this.reportLateReply(target, frame, true);
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         if (frame.error) {
@@ -553,9 +563,20 @@ var EngineJsonRpcClient = class {
    * Oldest request this client still tracks, settled ones included: that is the
    * request the daemon's arrival-ordered answer belongs to. `Map` iteration is
    * insertion order, which is the order the requests went out.
+   *
+   * An entry whose id-less answer has already been taken (`arrivalOrderConsumed`)
+   * is passed over for *this* purpose while staying in the map for the echoed-id
+   * lookup: the guess has been spent once and may not be spent again on the next
+   * id-less frame, and the request it was spent on is still the request whose real
+   * reply can arrive with its id (finding 中-4).
    */
   oldestTracked() {
-    return this.pending.values().next().value;
+    for (const entry of this.pending.values()) {
+      if (!entry.arrivalOrderConsumed) {
+        return entry;
+      }
+    }
+    return void 0;
   }
   /**
    * Route the reply that lands after its caller was already answered. `inferred`
@@ -1031,8 +1052,8 @@ var LEGACY_EVIDENCE_SCHEMA_VERSION = "glasspane.evidence/0.1-draft";
 var AttributionLevelSchema = z.enum(["soft", "strong", "weak"]);
 var CircuitBreakerLevelSchema = z.number().int().min(0).max(3);
 var SelectorSchema = z.strictObject({
-  role: z.string().max(SELECTOR_MAX_LENGTH),
-  title: z.string().max(SELECTOR_MAX_LENGTH).optional(),
+  role: z.string().min(1).max(SELECTOR_MAX_LENGTH),
+  title: z.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
   identifier: z.string().max(SELECTOR_MAX_LENGTH).optional()
 });
 var ActionSchema = z.enum([
@@ -1784,14 +1805,9 @@ var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
 var ExpectSchema = z5.union([z5.string().max(512), z5.boolean()]);
-var ShellSelectorSchema = z5.strictObject({
-  role: z5.string().min(1).max(SELECTOR_MAX_LENGTH),
-  title: z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
-  identifier: z5.string().max(SELECTOR_MAX_LENGTH).optional()
-});
 var SnapshotIdSchema = z5.string().regex(/^snap_[0-9A-HJKMNP-TV-Z]{26}$/);
 var ActStepSchema = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema
 });
 var RestoreStepsSchema = z5.array(ActStepSchema).min(1).max(64).optional();
@@ -1831,12 +1847,12 @@ var AuditUiArgs = z5.strictObject({
   minHitTargetPt: OptionalHitTargetSchema
 });
 var ActArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema,
   degrade: z5.boolean().optional()
 });
 var AssertElementArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   property: AssertionPropertySchema,
   expected: ExpectSchema
 });
@@ -1880,9 +1896,11 @@ var selectorJsonSchema = {
   type: "object",
   additionalProperties: false,
   properties: {
-    // `minLength` here is the advertised half of {@link ShellSelectorSchema};
+    // `minLength` here is the advertised half of the kernel's `SelectorSchema`;
     // `test/tools.test.mjs` compares the two against each other and against the
-    // daemon's own rule, so neither side can be tightened or loosened alone.
+    // daemon's own rule, and `test/consumer-consistency.test.mjs` compares both
+    // against the published `kernel/schemas/evidence-pack.schema.json`, so no
+    // side can be tightened or loosened alone.
     role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     title: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     identifier: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
@@ -2166,6 +2184,25 @@ var TOOL_SPECS = [
 var TOOL_BY_NAME = new Map(
   TOOL_SPECS.map((spec) => [spec.name, spec])
 );
+var TARGET_SELECTING_KNOBS = {
+  gp_act: {
+    param: "selector",
+    picks: "which control the action is performed on",
+    substitute: "a different control takes the press, and the user's screen changes in a way no one asked for"
+  },
+  gp_assert_element: {
+    param: "selector",
+    picks: "which element the claim is about",
+    substitute: "the answer then describes a different element, while this session's trail still files it as the verdict on the claim you first made"
+  }
+};
+function targetSelectingKnob(specName, paramName) {
+  if (!Object.prototype.hasOwnProperty.call(TARGET_SELECTING_KNOBS, specName)) {
+    return null;
+  }
+  const entry = TARGET_SELECTING_KNOBS[specName];
+  return entry !== void 0 && entry.param === paramName ? { picks: entry.picks, substitute: entry.substitute } : null;
+}
 function narrowingKnobsFor(spec, params) {
   const properties = spec.inputSchema.properties ?? {};
   const knobs = [];
@@ -2180,11 +2217,21 @@ function narrowingKnobsFor(spec, params) {
     } 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 });
+      const target = targetSelectingKnob(spec.name, name);
+      knobs.push(target === null ? { name, kind: "selector", sent: void 0 } : { name, kind: "target", sent: void 0, picks: target.picks, substitute: target.substitute });
     }
   }
   return knobs;
 }
+function replyShrinkingKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind !== "target");
+}
+function targetKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind === "target");
+}
+function describeTargetKnob(knob) {
+  return `'${knob.name}' names ${knob.picks ?? "which element this operation is about"}, so changing it is not a smaller or cheaper request \u2014 it is a different operation, and ${knob.substitute ?? "the answer then describes something else"}`;
+}
 function atAdvertisedFloor(knob) {
   return knob.minimum !== void 0 && knob.sent !== void 0 && knob.sent <= knob.minimum;
 }
@@ -2198,6 +2245,8 @@ function knobSubject(kind) {
       return "the image";
     case "selector":
       return "the reply";
+    case "target":
+      return "the element the operation is about";
   }
 }
 function describeKnob(knob) {
@@ -2214,19 +2263,27 @@ function describeKnob(knob) {
       return knob.name === "selector" ? "a more specific selector (aim at one element)" : `a tighter ${knob.name} filter`;
     case "scale":
       return `a smaller scale${bounds}${knob.sent !== void 0 ? `, currently ${knob.sent}` : ""}`;
+    case "target":
+      return describeTargetKnob(knob);
   }
 }
 function oversizedReplyAdvice(spec, params) {
   const knobs = narrowingKnobsFor(spec, params);
   const atFloor = knobs.filter(atAdvertisedFloor);
-  const shrinkable = knobs.filter((knob) => !atAdvertisedFloor(knob));
+  const target = targetKnobs(knobs);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
   const head = `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); `;
-  const floorNote = atFloor.length === 0 ? "" : `${atFloor.map(describeKnob).join("; ")}; `;
+  const refused = [...atFloor.map(describeKnob), ...target.map(describeTargetKnob)];
+  const floorNote = refused.length === 0 ? "" : `${refused.join("; ")}; `;
   if (shrinkable.length === 0) {
-    return knobs.length > 0 ? head + `${atFloor.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 knobs.length > 0 ? head + floorNote + "nothing left to narrow on this request: " + (target.length > 0 ? "this request already carries one element and one region, so read the tree with gp_observe and, if the element you meant is another one, make that its own claim rather than treating this answer as a size problem" : "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 + 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 NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
+  ...REPLAY_UNSAFE_METHOD_NAMES,
+  ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
+]);
 async function readTrail(session, turn, limit) {
   await turn.acquire();
   try {

package/dist/index.js

@@ -46,8 +46,8 @@ var LEGACY_EVIDENCE_SCHEMA_VERSION = "glasspane.evidence/0.1-draft";
 var AttributionLevelSchema = z.enum(["soft", "strong", "weak"]);
 var CircuitBreakerLevelSchema = z.number().int().min(0).max(3);
 var SelectorSchema = z.strictObject({
-  role: z.string().max(SELECTOR_MAX_LENGTH),
-  title: z.string().max(SELECTOR_MAX_LENGTH).optional(),
+  role: z.string().min(1).max(SELECTOR_MAX_LENGTH),
+  title: z.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
   identifier: z.string().max(SELECTOR_MAX_LENGTH).optional()
 });
 var ActionSchema = z.enum([
@@ -265,6 +265,107 @@ function parseEvidencePackRead(input) {
   throw schemaError("evidence pack", result.error);
 }
 
+// src/update-state.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+var STATE_DIR_ENV = "GLASSPANE_STATE_DIR";
+function recordHome() {
+  try {
+    return os.userInfo().homedir;
+  } catch {
+    return null;
+  }
+}
+function updateStateFile(env = process.env, stateRootOverride) {
+  const named2 = stateRootOverride ?? env[STATE_DIR_ENV];
+  if (typeof named2 === "string" && named2.trim() !== "") {
+    return path.join(path.resolve(named2), "update-state.json");
+  }
+  const home = recordHome();
+  if (home === null) {
+    return null;
+  }
+  return path.join(home, ".glasspane", "update-state.json");
+}
+var KNOWN_STATUSES = /* @__PURE__ */ new Set([
+  "up-to-date",
+  "available",
+  "staged",
+  "applied",
+  "deferred",
+  "needs-consent",
+  "check-overdue",
+  "rolled-back",
+  "check-failed",
+  "staged-build-failed",
+  "apply-failed",
+  "rollback-failed",
+  "disabled",
+  "installer-pointer-stale"
+]);
+function readUpdateState(env = process.env, stateRootOverride) {
+  const stateFile = updateStateFile(env, stateRootOverride);
+  if (stateFile === null) {
+    return {
+      kind: "unresolvable",
+      stateFile: null,
+      summary: "update state: this process has no password-database record, so the state root cannot be named; nothing was read and no claim about GlassPane's freshness is being made"
+    };
+  }
+  if (!fs.existsSync(stateFile)) {
+    return {
+      kind: "absent",
+      stateFile,
+      summary: `update state: no ${stateFile} \u2014 auto-update has never run on this machine, so nothing here says the installed GlassPane is current; run \`node updater/cli.js check\` (or use the settings panel) to find out`
+    };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(stateFile, "utf8");
+  } catch (error) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} exists but could not be read (${String(error)}); freshness is unknown, which is not the same as up to date`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} is not valid JSON (${String(error)}); freshness is unknown, which is not the same as up to date`
+    };
+  }
+  const status = typeof parsed.status === "string" ? parsed.status : null;
+  if (status === null || !KNOWN_STATUSES.has(status)) {
+    return {
+      kind: "unreadable",
+      stateFile,
+      summary: `update state: ${stateFile} carries status ${JSON.stringify(parsed.status ?? null)}, which is not a status this shell knows; the updater and this shell disagree about the contract, so freshness is unknown`
+    };
+  }
+  const bits = [
+    `status=${status}`,
+    `current=${String(parsed.current ?? "unknown")}`,
+    `latest=${String(parsed.latest ?? "none-seen")}`,
+    `lastCheckAt=${String(parsed.updatedAt ?? "never")}`,
+    `autoUpdate=${parsed.disabled === true ? "off" : parsed.autoApply === true ? "on" : "on-by-default"}`
+  ];
+  const lastError = parsed.lastError;
+  if (lastError && typeof lastError.message === "string") {
+    bits.push(`lastError=${lastError.code ?? "no-code"}: ${lastError.message}`);
+  }
+  const staged = parsed.staged;
+  if (staged && typeof staged.version === "string") {
+    bits.push(`staged=${staged.version}${staged.digest ? ` (${String(staged.digest).slice(0, 12)}\u2026)` : ""}`);
+  }
+  return { kind: "read", stateFile, summary: `update state: ${bits.join("; ")}` };
+}
+
 // src/io.ts
 var MAX_FRAME_BYTES = 4 * 1024 * 1024;
 var OVERSIZE_PREFIX_BYTES = 512;
@@ -497,9 +598,9 @@ var DrainAwareWriter = class {
 
 // src/engine-client.ts
 import net from "node:net";
-import os from "node:os";
-import path from "node:path";
-import fs from "node:fs";
+import os2 from "node:os";
+import path2 from "node:path";
+import fs2 from "node:fs";
 import { fileURLToPath } from "node:url";
 
 // src/errors.ts
@@ -522,16 +623,16 @@ function formatToolErrorShape(error) {
 
 // src/engine-client.ts
 function daemonUnreachableRemedy() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const installerCli = path.resolve(here, "..", "..", "installer", "cli.js");
-  if (fs.existsSync(installerCli)) {
+  const here = path2.dirname(fileURLToPath(import.meta.url));
+  const installerCli = path2.resolve(here, "..", "..", "installer", "cli.js");
+  if (fs2.existsSync(installerCli)) {
     return `run "node ${installerCli} --restore-launchd" (auto-restores and verifies the launchd-managed daemon), then retry`;
   }
   return "ensure the glasspane daemon is running (launchd job com.glasspane.daemon; in a repo checkout run `node installer/cli.js --restore-launchd`), then retry";
 }
 var ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
 function defaultSocketPath() {
-  return process.env[ENGINE_SOCKET_ENV] ?? path.join(os.homedir(), ".glasspane", "engine.sock");
+  return process.env[ENGINE_SOCKET_ENV] ?? path2.join(os2.homedir(), ".glasspane", "engine.sock");
 }
 var ENGINE_TIMEOUT_MS = 1e4;
 var CALLER_VISIBLE_CEILING_MS = 5e4;
@@ -582,6 +683,7 @@ function isReplayUnsafeMethod(method) {
   return Object.prototype.hasOwnProperty.call(REPLAY_UNSAFE_REASONS, method);
 }
 var REPLAY_UNSAFE_METHOD_NAMES = Object.keys(REPLAY_UNSAFE_REASONS);
+var STATE_CHANGING_ON_RETRY_METHOD_NAMES = ["snapshot"];
 function engineDeadlineMs(method, params) {
   if (method === "restore") {
     const steps = params?.steps;
@@ -638,6 +740,10 @@ var NARROWING_AUTHORITY = {
   mcp: "the gp_* tool that took this call publishes its own parameters, and their floors, in the schema shown beside that tool \u2014 read it there, not here",
   http: "this gateway publishes no parameter listing of its own, so the floors a body was accepted against are in the request contract this call was copied from"
 };
+function clientClosingRemedy(surface) {
+  const readRoute = surface === "mcp" ? "gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one in full" : "this gateway keeps no operation trail of its own, so the stderr line this reply is written to is the record";
+  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 reIssueGuidance(surface) {
   return `wait for the outstanding reply rather than sending this request again: the daemon answers one request at a time, so a second copy of it now only queues behind the one still running and answers nothing sooner, and if the first did take effect the copy performs it a second time. What is worth narrowing here, and whether it can still be narrowed at the values this request already sent, is a fact about a schema, and this layer holds no schema for any request: ${NARROWING_AUTHORITY[surface]}. Re-send only after reading that, and only if the request is one whose repetition changes nothing`;
 }
@@ -793,8 +899,8 @@ var EngineJsonRpcClient = class {
     this.state.closed = true;
     this.teardown(new EngineCallError(
       GP_E_ENGINE_UNREACHABLE,
-      "engine client closed",
-      daemonUnreachableRemedy()
+      "engine client closed: this shell's own client is ending, so whether the daemon finished this request is not known here and this client can no longer attribute the reply that may still land",
+      clientClosingRemedy(this.surface)
     ));
     this.io.close();
   }
@@ -843,7 +949,11 @@ var EngineJsonRpcClient = class {
     if (typeof id === "number") {
       const entry = this.pending.get(id);
       if (!entry) {
-        this.report(`engine sent a frame for request id ${id}, which this client never issued (or already gave up on): ${truncate(line)}`);
+        const tracked = [...this.pending.values()];
+        const held = tracked.length === 0 ? "nothing is tracked now" : `this client still tracks ${tracked.length} request(s): ` + tracked.map((kept) => "'" + kept.method + "' id " + kept.id + (kept.settled ? " (caller already answered)" : "")).join(", ");
+        this.report(
+          `engine sent a frame for request id ${id}, which this client never issued (or already gave up on); ` + held + ": " + truncate(line)
+        );
         return;
       }
       this.pending.delete(id);
@@ -858,8 +968,9 @@ var EngineJsonRpcClient = class {
       const target = this.oldestTracked();
       if (target) {
         if (target.settled) {
-          this.pending.delete(target.id);
           this.reportLateReply(target, frame, true);
+          target.arrivalOrderConsumed = true;
+          this.retainForLateReply();
           return;
         }
         if (frame.error) {
@@ -920,9 +1031,20 @@ var EngineJsonRpcClient = class {
    * Oldest request this client still tracks, settled ones included: that is the
    * request the daemon's arrival-ordered answer belongs to. `Map` iteration is
    * insertion order, which is the order the requests went out.
+   *
+   * An entry whose id-less answer has already been taken (`arrivalOrderConsumed`)
+   * is passed over for *this* purpose while staying in the map for the echoed-id
+   * lookup: the guess has been spent once and may not be spent again on the next
+   * id-less frame, and the request it was spent on is still the request whose real
+   * reply can arrive with its id (finding 中-4).
    */
   oldestTracked() {
-    return this.pending.values().next().value;
+    for (const entry of this.pending.values()) {
+      if (!entry.arrivalOrderConsumed) {
+        return entry;
+      }
+    }
+    return void 0;
   }
   /**
    * Route the reply that lands after its caller was already answered. `inferred`
@@ -1612,9 +1734,9 @@ function exponentialFromDigits(digits, power) {
 }
 
 // src/project-registry.ts
-import fs2 from "node:fs";
-import os2 from "node:os";
-import path2 from "node:path";
+import fs3 from "node:fs";
+import os3 from "node:os";
+import path3 from "node:path";
 import { randomBytes } from "node:crypto";
 import { z as z4 } from "zod";
 var CROCKFORD_BODY_RE = "[0-9A-HJKMNP-TV-Z]{26}";
@@ -1653,7 +1775,7 @@ var PROTECTED_SUBTREES = [
 ];
 function systemHome() {
   try {
-    return os2.userInfo().homedir;
+    return os3.userInfo().homedir;
   } catch (error) {
     throw new ProjectRegistryError(
       // Not GP_E_INTERNAL: `tools.ts` maps that code to "the projects file is
@@ -1665,7 +1787,7 @@ function systemHome() {
   }
 }
 function daemonProjectsPath() {
-  return path2.join(systemHome(), ".glasspane", "projects.json");
+  return path3.join(systemHome(), ".glasspane", "projects.json");
 }
 var FIRMLINK_PREFIX = "/System/Volumes/Data";
 var FORCE_OVERWRITE_ENV = "GLASSPANE_PROJECTS_FORCE_OVERWRITE";
@@ -1696,7 +1818,7 @@ function projectsPath() {
 function loadRegistry(filePath) {
   let raw;
   try {
-    raw = fs2.readFileSync(filePath, "utf8");
+    raw = fs3.readFileSync(filePath, "utf8");
   } catch (error) {
     if (nodeErrorCode(error) === "ENOENT") {
       return { projects: [], failure: null };
@@ -1765,7 +1887,7 @@ function requireUsableRegistry(filePath, snapshot) {
   }
   const discarded = `${filePath}.unreadable-${uniqueToken()}`;
   try {
-    fs2.renameSync(filePath, discarded);
+    fs3.renameSync(filePath, discarded);
   } catch (error) {
     throw new ProjectRegistryError(
       GP_E_INTERNAL,
@@ -1784,7 +1906,7 @@ var STATE_DIR_MODE = 448;
 var STATE_FILE_MODE = 384;
 function tightenMode(target, want, kind) {
   try {
-    fs2.chmodSync(target, want);
+    fs3.chmodSync(target, want);
   } catch (error) {
     throw new ProjectRegistryError(
       GP_E_INTERNAL,
@@ -1793,7 +1915,7 @@ function tightenMode(target, want, kind) {
   }
   let mode;
   try {
-    mode = fs2.statSync(target).mode & 511;
+    mode = fs3.statSync(target).mode & 511;
   } catch (error) {
     throw new ProjectRegistryError(
       GP_E_INTERNAL,
@@ -1808,18 +1930,18 @@ function tightenMode(target, want, kind) {
   }
 }
 function saveProjects(filePath, entries) {
-  const dir = path2.dirname(filePath);
+  const dir = path3.dirname(filePath);
   const tmpPath = `${filePath}.tmp-${uniqueToken()}`;
   try {
-    fs2.mkdirSync(dir, { recursive: true, mode: STATE_DIR_MODE });
+    fs3.mkdirSync(dir, { recursive: true, mode: STATE_DIR_MODE });
     tightenMode(dir, STATE_DIR_MODE, "directory");
-    fs2.writeFileSync(tmpPath, JSON.stringify(entries, null, 2), "utf8");
+    fs3.writeFileSync(tmpPath, JSON.stringify(entries, null, 2), "utf8");
     tightenMode(tmpPath, STATE_FILE_MODE, "file");
-    fs2.renameSync(tmpPath, filePath);
+    fs3.renameSync(tmpPath, filePath);
     tightenMode(filePath, STATE_FILE_MODE, "file");
   } catch (error) {
     try {
-      fs2.unlinkSync(tmpPath);
+      fs3.unlinkSync(tmpPath);
     } catch {
     }
     if (error instanceof ProjectRegistryError) {
@@ -1927,7 +2049,7 @@ function assertSingleIdentity(entry) {
 }
 function daemonRestartNotice(filePath) {
   const daemonPath = daemonProjectsPath();
-  if (path2.resolve(filePath) !== path2.resolve(daemonPath)) {
+  if (path3.resolve(filePath) !== path3.resolve(daemonPath)) {
     return `Saved in ${filePath}. The background service does not read this path because of anything in its own configuration: its default root is the folder under this user's home record, where it loads ${daemonPath} once when it starts, and ${PROJECTS_FILE_ENV} \u2014 the variable that pointed this write here \u2014 is honoured by this MCP shell only, so as far as the service's own configuration goes it never reads that file, and no restart of the service will make it load this one. ${rootDiscriminator()} To land the entry where that default root looks: unset ${PROJECTS_FILE_ENV} for this shell (or point it at ${daemonPath}) and repeat gp_project_set, then restart the background service so it reloads \u2014 ${restartCommand()}`;
   }
   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()}`;
@@ -1959,7 +2081,7 @@ function checkAgentPath(field, value) {
       throw badPath(field, value, `must not contain "." or ".." components (got "${value}")`);
     }
   }
-  const logical = path2.posix.normalize(value);
+  const logical = path3.posix.normalize(value);
   const given = stripFirmlink(logical);
   const resolved = stripFirmlink(resolveExistingAncestor(logical));
   const refusal = strongestRefusal(given === resolved ? [resolved] : [resolved, given], resolved);
@@ -2008,7 +2130,7 @@ function refuseHomeDotDirectory(target, home) {
   return named(`a dot-directory of the current user's home directory (~/${first}), which is where that account's credentials and client configuration live (\`~/.ssh\`, \`~/.aws\`, \`~/.gnupg\`, \`~/.config\`) or the daemon's own private state (\`~/.glasspane\`); the daemon chmods a registered storage root to 0700 and writes evidence packs into it, and prunes expired ones out of it, so this is not a place a project archive may be pointed at \u2014 name a directory inside the project instead, e.g. "the project tree/${first}"`);
 }
 function refuseCandidate(target) {
-  const home = stripFirmlink(path2.posix.normalize(systemHome()));
+  const home = stripFirmlink(path3.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");
   const homeDot = refuseHomeDotDirectory(target, home);
@@ -2037,7 +2159,7 @@ function refuseUnownedTree(target) {
   }
   let stat;
   try {
-    stat = fs2.statSync(ancestor);
+    stat = fs3.statSync(ancestor);
   } catch (error) {
     return `under a nearest existing directory ${ancestor} that cannot be inspected (${describeError(error)})`;
   }
@@ -2052,10 +2174,10 @@ function refuseUnownedTree(target) {
 function nearestExistingAncestor(target) {
   let cursor = target;
   for (; ; ) {
-    if (fs2.existsSync(cursor)) {
+    if (fs3.existsSync(cursor)) {
       return cursor;
     }
-    const parent = path2.posix.dirname(cursor);
+    const parent = path3.posix.dirname(cursor);
     if (parent === cursor) return parent;
     cursor = parent;
   }
@@ -2075,12 +2197,12 @@ function resolveExistingAncestor(target) {
   const missingTail = [];
   for (; ; ) {
     try {
-      const real = fs2.realpathSync(cursor);
-      return missingTail.length === 0 ? real : path2.posix.join(real, ...missingTail);
+      const real = fs3.realpathSync(cursor);
+      return missingTail.length === 0 ? real : path3.posix.join(real, ...missingTail);
     } catch {
-      const parent = path2.posix.dirname(cursor);
+      const parent = path3.posix.dirname(cursor);
       if (parent === cursor) return target;
-      missingTail.unshift(path2.posix.basename(cursor));
+      missingTail.unshift(path3.posix.basename(cursor));
       cursor = parent;
     }
   }
@@ -2126,14 +2248,9 @@ var OPERATION_ID_PATTERN2 = /^op_[0-9A-HJKMNP-TV-Z]{26}$/;
 var OptionalOperationIdSchema = z5.string().regex(OPERATION_ID_PATTERN2).optional();
 var OptionalProjectIdSchema = z5.string().regex(/^prj_[0-9A-HJKMNP-TV-Z]{26}$/).optional();
 var ExpectSchema = z5.union([z5.string().max(512), z5.boolean()]);
-var ShellSelectorSchema = z5.strictObject({
-  role: z5.string().min(1).max(SELECTOR_MAX_LENGTH),
-  title: z5.string().min(1).max(SELECTOR_MAX_LENGTH).optional(),
-  identifier: z5.string().max(SELECTOR_MAX_LENGTH).optional()
-});
 var SnapshotIdSchema = z5.string().regex(/^snap_[0-9A-HJKMNP-TV-Z]{26}$/);
 var ActStepSchema = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema
 });
 var RestoreStepsSchema = z5.array(ActStepSchema).min(1).max(64).optional();
@@ -2173,12 +2290,12 @@ var AuditUiArgs = z5.strictObject({
   minHitTargetPt: OptionalHitTargetSchema
 });
 var ActArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   action: ActionSchema,
   degrade: z5.boolean().optional()
 });
 var AssertElementArgs = z5.strictObject({
-  selector: ShellSelectorSchema,
+  selector: SelectorSchema,
   property: AssertionPropertySchema,
   expected: ExpectSchema
 });
@@ -2222,9 +2339,11 @@ var selectorJsonSchema = {
   type: "object",
   additionalProperties: false,
   properties: {
-    // `minLength` here is the advertised half of {@link ShellSelectorSchema};
+    // `minLength` here is the advertised half of the kernel's `SelectorSchema`;
     // `test/tools.test.mjs` compares the two against each other and against the
-    // daemon's own rule, so neither side can be tightened or loosened alone.
+    // daemon's own rule, and `test/consumer-consistency.test.mjs` compares both
+    // against the published `kernel/schemas/evidence-pack.schema.json`, so no
+    // side can be tightened or loosened alone.
     role: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     title: { type: "string", minLength: 1, maxLength: SELECTOR_MAX_LENGTH },
     identifier: { type: "string", maxLength: SELECTOR_MAX_LENGTH }
@@ -2538,6 +2657,25 @@ function attachIdentityOf(result) {
   const bundleId = typeof record.bundleId === "string" ? record.bundleId : "<no-bundle-id>";
   return `${pid}|${bundleId}|${appName}`;
 }
+var TARGET_SELECTING_KNOBS = {
+  gp_act: {
+    param: "selector",
+    picks: "which control the action is performed on",
+    substitute: "a different control takes the press, and the user's screen changes in a way no one asked for"
+  },
+  gp_assert_element: {
+    param: "selector",
+    picks: "which element the claim is about",
+    substitute: "the answer then describes a different element, while this session's trail still files it as the verdict on the claim you first made"
+  }
+};
+function targetSelectingKnob(specName, paramName) {
+  if (!Object.prototype.hasOwnProperty.call(TARGET_SELECTING_KNOBS, specName)) {
+    return null;
+  }
+  const entry = TARGET_SELECTING_KNOBS[specName];
+  return entry !== void 0 && entry.param === paramName ? { picks: entry.picks, substitute: entry.substitute } : null;
+}
 function narrowingKnobsFor(spec, params) {
   const properties = spec.inputSchema.properties ?? {};
   const knobs = [];
@@ -2552,11 +2690,21 @@ function narrowingKnobsFor(spec, params) {
     } 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 });
+      const target = targetSelectingKnob(spec.name, name);
+      knobs.push(target === null ? { name, kind: "selector", sent: void 0 } : { name, kind: "target", sent: void 0, picks: target.picks, substitute: target.substitute });
     }
   }
   return knobs;
 }
+function replyShrinkingKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind !== "target");
+}
+function targetKnobs(knobs) {
+  return knobs.filter((knob) => knob.kind === "target");
+}
+function describeTargetKnob(knob) {
+  return `'${knob.name}' names ${knob.picks ?? "which element this operation is about"}, so changing it is not a smaller or cheaper request \u2014 it is a different operation, and ${knob.substitute ?? "the answer then describes something else"}`;
+}
 function atAdvertisedFloor(knob) {
   return knob.minimum !== void 0 && knob.sent !== void 0 && knob.sent <= knob.minimum;
 }
@@ -2570,6 +2718,8 @@ function knobSubject(kind) {
       return "the image";
     case "selector":
       return "the reply";
+    case "target":
+      return "the element the operation is about";
   }
 }
 function describeKnob(knob) {
@@ -2586,16 +2736,20 @@ function describeKnob(knob) {
       return knob.name === "selector" ? "a more specific selector (aim at one element)" : `a tighter ${knob.name} filter`;
     case "scale":
       return `a smaller scale${bounds}${knob.sent !== void 0 ? `, currently ${knob.sent}` : ""}`;
+    case "target":
+      return describeTargetKnob(knob);
   }
 }
 function oversizedReplyAdvice(spec, params) {
   const knobs = narrowingKnobsFor(spec, params);
   const atFloor = knobs.filter(atAdvertisedFloor);
-  const shrinkable = knobs.filter((knob) => !atAdvertisedFloor(knob));
+  const target = targetKnobs(knobs);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
   const head = `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); `;
-  const floorNote = atFloor.length === 0 ? "" : `${atFloor.map(describeKnob).join("; ")}; `;
+  const refused = [...atFloor.map(describeKnob), ...target.map(describeTargetKnob)];
+  const floorNote = refused.length === 0 ? "" : `${refused.join("; ")}; `;
   if (shrinkable.length === 0) {
-    return knobs.length > 0 ? head + `${atFloor.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 knobs.length > 0 ? head + floorNote + "nothing left to narrow on this request: " + (target.length > 0 ? "this request already carries one element and one region, so read the tree with gp_observe and, if the element you meant is another one, make that its own claim rather than treating this answer as a size problem" : "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 + 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`;
 }
@@ -2605,23 +2759,33 @@ var REPLAY_UNSAFE_PAYLOAD_HARMS = {
   attach: "it re-points the daemon at another app, and a changed attach discards the evidence history a request that has not answered yet is being recorded in"
 };
 function replayUnsafePayloadAdvice(spec, method, params) {
-  const shrinkable = narrowingKnobsFor(spec, params).filter((knob) => !atAdvertisedFloor(knob));
+  const knobs = narrowingKnobsFor(spec, params);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
+  const target = targetKnobs(knobs);
   const head = `the reply was too large for one frame (${MAX_FRAME_BYTES}-byte limit); `;
   const harm = REPLAY_UNSAFE_PAYLOAD_HARMS[method] ?? "it changes daemon state";
-  const narrower = shrinkable.length > 0 ? `with ${shrinkable.map(describeKnob).join(" and ")}` : "only after narrowing it (this tool advertises no parameter that shrinks a reply, so ask a smaller question: one element, one region)";
+  const narrower = shrinkable.length > 0 ? `with ${shrinkable.map(describeKnob).join(" and ")}` : target.length > 0 ? `exactly as it stands, with the same ${target.map((knob) => knob.name).join(" and ")} (${target.map(describeTargetKnob).join("; ")})` : "only after narrowing it (this tool advertises no parameter that shrinks a reply, so ask a smaller question: one element, one region)";
   return head + `do not re-issue this request. '${spec.name}' already reached the daemon and was answered \u2014 only the answer was dropped for exceeding one frame \u2014 and ${harm}, so sending it again performs the change a second time rather than recovering the first. Read what happened instead: gp_recent_reports lists the operations this session recorded and gp_last_evidence {operationId} returns one of them in full, and gp_observe / gp_assert_element read the app the daemon is attached to now without performing anything (gp_probe_status answers on the same connection and names the apps with a live probe with their pids). The connection is intact and the daemon keeps answering other requests; if that reading shows this request never took effect, it can be sent again ${narrower}, and a retried identical request will be dropped identically.`;
 }
 function slowReplyAdvice(spec, params) {
   const knobs = narrowingKnobsFor(spec, params);
   const atFloor = knobs.filter(atAdvertisedFloor);
-  const shrinkable = knobs.filter((knob) => !atAdvertisedFloor(knob));
+  const target = targetKnobs(knobs);
+  const shrinkable = replyShrinkingKnobs(knobs).filter((knob) => !atAdvertisedFloor(knob));
   const floorNote = atFloor.length === 0 ? "" : ` ${atFloor.map(describeKnob).join("; ")}.`;
-  const narrowed = shrinkable.length === 0 ? `there is nothing left to narrow on this request:${floorNote} ask a smaller question (one element, one region) rather than re-sending the same one and waiting out the same deadline on it` : `once it is answered, re-send '${spec.name}' with ${shrinkable.map(describeKnob).join(" and ")} \u2014 these are the parameters this tool itself advertises as deciding how much work one answer carries${floorNote}`;
+  const narrowed = shrinkable.length > 0 ? `once it is answered, re-send '${spec.name}' with ${shrinkable.map(describeKnob).join(" and ")} \u2014 these are the parameters this tool itself advertises as deciding how much work one answer carries${floorNote}` : target.length > 0 ? `there is nothing left to narrow on this request, and no parameter of '${spec.name}' can stand in for one: ${target.map(describeTargetKnob).join("; ")}. Wait for the outstanding reply \u2014 it is attributed and recorded in this session's trail when it lands \u2014 and read the app rather than re-aiming this claim: gp_observe lists what is on screen, and gp_probe_status names the apps with a live probe` : `there is nothing left to narrow on this request:${floorNote} ask a smaller question (one element, one region) rather than re-sending the same one and waiting out the same deadline on it`;
   const probeGuide = LIVENESS_PROBE_OUTCOMES.map((outcome) => `${outcome} \u2014 ${livenessProbeDecision(outcome)}`).join("; ");
   return `the daemon serves one request at a time and is still working on this one, so this answer describes a busy daemon, not a dead one: wait for it, and do not put a second copy of the same request on the wire while the first is outstanding \u2014 it queues behind the work that is already late. ${narrowed}. If your client can send a second request while this one is still outstanding, confirm the daemon is alive with gp_probe_status (this shell does not queue one MCP request behind another) and read its answer as: ${probeGuide}. A restart is authorised only by ${livenessProbeDecision("unreachable")}. Nothing is discarded by this shell having answered early: ${lateReplyRoute("mcp")}`;
 }
+var NOT_NARROWABLE_BY_RETRY = /* @__PURE__ */ new Set([
+  ...REPLAY_UNSAFE_METHOD_NAMES,
+  ...STATE_CHANGING_ON_RETRY_METHOD_NAMES
+]);
+function isNarrowableByRetryMethod(method) {
+  return !NOT_NARROWABLE_BY_RETRY.has(method);
+}
 function toolAuthorsTimeoutAdvice(spec, method, params) {
-  return !isReplayUnsafeMethod(method) && narrowingKnobsFor(spec, params).length > 0;
+  return isNarrowableByRetryMethod(method) && narrowingKnobsFor(spec, params).length > 0;
 }
 async function readTrail(session, turn, limit) {
   await turn.acquire();
@@ -2672,8 +2836,12 @@ async function runValidatedTool(spec, value, engine, session, turn) {
     } finally {
       turn.release();
     }
+    const content = [{ type: "text", text: canonicalJson(raw) }];
+    if (spec.name === "gp_diagnose") {
+      content.push({ type: "text", text: readUpdateState().summary });
+    }
     return {
-      content: [{ type: "text", text: canonicalJson(raw) }],
+      content,
       isError: false
     };
   } catch (error) {
@@ -3157,7 +3325,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-03-26",
   MCP_PROTOCOL_VERSION
 ];
-var SERVER_INFO = { name: "glasspane-mcp", version: "1.3.1" };
+var SERVER_INFO = { name: "glasspane-mcp", version: "1.4.0" };
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;

package/dist/tools.d.ts

@@ -357,6 +357,8 @@ export declare function replayUnsafePayloadAdvice(spec: ToolSpec, method: string
  * exact harm R8-高1 removed.
  */
 export declare function slowReplyAdvice(spec: ToolSpec, params: Record<string, unknown>): string;
+/** May the tool layer answer a timeout on `method` by telling the caller to re-send narrower? */
+export declare function isNarrowableByRetryMethod(method: string): boolean;
 /**
  * Does the tool layer have more to say about a timeout on `method` than the
  * transport does?
@@ -366,8 +368,9 @@ export declare function slowReplyAdvice(spec: ToolSpec, params: Record<string, u
  * see the tool's schema. Everywhere else the transport's own sentence stands —
  * including `gp_probe_status`, whose remedy the transport writes specially because
  * a probe that went unanswered must not be told to send a probe (and must not
- * name a restart at all). Replay-unsafe methods are the transport's too: its
- * remedy already forbids the re-issue, and this layer adds no reason to re-issue.
+ * name a restart at all). And a method whose re-issue changes daemon state is not
+ * narrowed by re-sending it at all ({@link NOT_NARROWABLE_BY_RETRY}): its answer
+ * is the transport's, which orders no re-send.
  */
 export declare function toolAuthorsTimeoutAdvice(spec: ToolSpec, method: string, params: Record<string, unknown>): boolean;
 /**

package/dist/update-state.d.ts

@@ -0,0 +1,25 @@
+/** Env the daemon's own `--state-dir` maps to for this process (X-22 family). */
+export declare const STATE_DIR_ENV = "GLASSPANE_STATE_DIR";
+/**
+ * The home the *other* processes use. `os.homedir()` reads `$HOME`, which a caller
+ * controls; `os.userInfo().homedir` reads the password record, which is what
+ * `NSHomeDirectory()` in the panel and `StateRoot.homeDefault()` in the daemon both
+ * return. Refuse rather than fall back — the same rule `project-registry.ts` states
+ * at length, and for the same reason: a redirected `$HOME` here means reading a
+ * state file that describes nobody's machine.
+ */
+export declare function recordHome(): string | null;
+/** Where `update-state.json` lives for this process, or null when it cannot be named. */
+export declare function updateStateFile(env?: NodeJS.ProcessEnv, stateRootOverride?: string): string | null;
+export interface UpdateStateReading {
+    kind: "read" | "absent" | "unreadable" | "unresolvable";
+    stateFile: string | null;
+    summary: string;
+}
+/**
+ * Read and render. Never throws: `gp_diagnose` answers about an operation, and a
+ * missing or broken update file is a fact about the machine, not a reason to fail
+ * the diagnosis.
+ */
+export declare function readUpdateState(env?: NodeJS.ProcessEnv, stateRootOverride?: string): UpdateStateReading;
+//# sourceMappingURL=update-state.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glasspane-mcp",
-  "version": "1.3.1",
+  "version": "1.4.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/evidence-pack.schema.json

@@ -196,10 +196,12 @@
       "properties": {
         "role": {
           "type": "string",
+          "minLength": 1,
           "maxLength": 512
         },
         "title": {
           "type": "string",
+          "minLength": 1,
           "maxLength": 512
         },
         "identifier": {