glasspane-mcp 1.2.0 → 1.3.1

package/dist/audit-session.d.ts

@@ -20,8 +20,61 @@ export interface TrailTurn {
     /** Hand the trail on: this turn is done with it, or never will be. */
     release(): void;
 }
+/**
+ * Handed to {@link EvidenceAuditSession.recordLateArrival} when the request that
+ * produced a late reply never said which generation it belonged to. It is
+ * deliberately not `undefined` and not a number the real epochs can ever reach:
+ * an unattributed frame is *known* unattributed, and refusing it is the default.
+ */
+export declare const UNKNOWN_GENERATION = -1;
+/** Where a late arrival ended up: written, or refused because a re-attach got there first. */
+export interface LateArrivalOutcome {
+    written: boolean;
+    /** The trail generation in force at the moment of the decision. */
+    generationAtWrite: number;
+}
+/**
+ * How an id got into this trail, per id, in the words a renderer can put beside
+ * it. The three values are not adjectives of confidence: they name which
+ * mechanism wrote the id, and each one is a fact the session itself observes.
+ *
+ * - `in-order`: written by a call whose own request held a trail turn, answered
+ *   by a frame that echoed that request's id. This is the only entry the trail
+ *   may describe as verified.
+ * - `late`: written from a reply that landed after its caller had already been
+ *   answered, so it had no turn left to write at and took the position
+ *   {@link recordLateArrival} gives it — behind whatever is still outstanding.
+ *   The *operation* is the daemon's own; only its place in request order is
+ *   arranged by arrival.
+ * - `late-inferred`: that same late write, for a frame that echoed **no request
+ *   id** (R10-中2). Which request it answers is then a guess from the daemon's
+ *   in-order scheduling, not a match, and an id pulled out of it can be filed
+ *   under the wrong operation. The trail still records it — dropping it would
+ *   claim "no such operation ran", which is the more dangerous lie for an agent
+ *   deciding whether to click again — but it must not read as verified, and
+ *   `gp_recent_reports` has to say so from here rather than from the log line.
+ *
+ * Producers: `EngineJsonRpcClient`'s `LateReply.attribution` decides between the
+ * last two (`echoed-id` -> `late`, `arrival-order` -> `late-inferred`); a caller
+ * that passes nothing gets `late`, which is everything this session can see on
+ * its own.
+ */
+export type TrailProvenance = "in-order" | "late" | "late-inferred";
+/**
+ * The attribution a late arrival carries: the same two literals
+ * `engine-client.ts`'s `FrameAttribution` produces, and `unknown` for a caller
+ * that cannot say (a wiring that has not read the field yet).
+ */
+export type LateArrivalAttribution = "echoed-id" | "arrival-order" | "unknown";
+/**
+ * The sentence the surface that shows the trail puts beside one id. Written here
+ * because this is the layer that knows the mechanism; the tool layer renders it.
+ */
+export declare const TRAIL_PROVENANCE_NOTES: Readonly<Record<TrailProvenance, string>>;
 export declare class EvidenceAuditSession {
     private ids;
+    private epoch;
+    private attachedAppKey;
     /**
      * Turns claimed but not released. This, not a "latest gate", is what a new
      * claim waits for: a turn that abandons the trail (its engine call failed
@@ -31,18 +84,116 @@ export declare class EvidenceAuditSession {
      * order the turn machinery exists to remove.
      */
     private openGates;
-    /** Record every operationId/evidenceId found in an engine result frame. */
+    /**
+     * How each id in {@link ids} got here. Keyed by the id, because that is what a
+     * reader holds; the map is trimmed with the list and cleared when the trail
+     * restarts, so an id can never outlive the provenance that describes it.
+     */
+    private readonly provenance;
+    /**
+     * Non-null while {@link recordLateArrival} holds the trail, and says how the
+     * frame being written was attributed. This is what lets a plain
+     * `trail.record(result)` inside that callback be filed as a late arrival without
+     * the caller having to remember to say so: the write happens inside a window only
+     * that method opens, so the mechanism is visible here rather than being a claim
+     * somebody must repeat at every call site.
+     */
+    private lateWindow;
+    /**
+     * Record every operationId/evidenceId found in an engine result frame, tagged
+     * with the provenance of the path that is recording it (see
+     * {@link TrailProvenance}): `in-order` from a call that held its own trail turn,
+     * `late`/`late-inferred` from inside {@link recordLateArrival}.
+     */
     record(result: unknown): void;
     /**
-     * Clear the trail (called after a successful attach).
+     * How one id in this trail got recorded, or null when the trail does not hold
+     * it — never recorded, evicted past {@link AUDIT_HISTORY_LIMIT}, or cleared by a
+     * {@link restart}. A reader that lists ids for an agent renders
+     * {@link TRAIL_PROVENANCE_NOTES} for anything that is not `in-order`: an id
+     * pulled from a frame this shell only *guessed* an owner for must not appear
+     * beside one it matched by id (R10-中2).
+     *
+     * Read off the map alone, so the map *is* the record of what the trail holds: an
+     * id whose provenance outlives its own entry would come back labelled as if it
+     * were still listed, and the eviction and the restart are the two places that
+     * would have to remember to delete. `test/engine-client.test.mjs` pins both.
+     */
+    provenanceOf(id: string): TrailProvenance | null;
+    /** The ids currently filed as inferred; see {@link TrailProvenance}. */
+    inferredIds(): string[];
+    /**
+     * The trail's generation number. Every {@link restart} bumps it.
+     *
+     * It exists so a reply that arrives *after* its caller was already answered
+     * can be judged against the trail it was written into: {@link recordLateArrival}
+     * takes the epoch the request was admitted under, and a mismatch means a
+     * re-attach happened in between. Without it, a late write lands in a *new*
+     * session's trail — an operationId from the previous app that
+     * `gp_recent_reports` then fetches and renders as if it belonged to this one
+     * (R8b-高1, measured: `['op_OLDAPP']` in the trail after attaching a second
+     * app).
+     */
+    get generation(): number;
+    /** The app the trail currently belongs to, or null before the first attach. */
+    get attachedApp(): string | null;
+    /**
+     * A successful attach: the trail restarts **only when the attached app
+     * changed**, because that is the daemon's own rule —
+     * `EngineCore.attach` clears `history` under
+     * `if attachedApp != app`, and its comment says re-attach to the same app is
+     * idempotent. Clearing on *every* attach (what this used to do) is strictly
+     * worse in two directions: an idempotent re-attach wiped operations that were
+     * really in the trail (including one recorded by a late reply, which put
+     * `gp_recent_reports` back to "run gp_act first"), and — because the clear
+     * happens whenever the reply lands — it could also drop the record of an act
+     * the daemon still has.
+     *
+     * `appKey` must be built from every stored property of Swift's `AttachedApp`
+     * (`pid`, `bundleId`, `appName`); a key that ignored `pid` would keep the
+     * trail across an app restart whose history the daemon did clear. The gate
+     * that pins this to the Swift struct is
+     * `test/attach-identity.test.mjs`.
      *
-     * Deliberately does *not* touch {@link openGates}: outstanding turns are not
-     * outstanding mutations, and forgetting them would let a later read overtake
-     * an act that is still going to write.
+     * Returns whether the trail was restarted. A null `appKey` means the attach
+     * result did not identify the app at all, which is treated as a change: an
+     * unknown identity cannot be *shown* to be the same app, and a stale trail is
+     * the failure that misattributes evidence.
      */
-    reset(): void;
+    restart(appKey: string | null): boolean;
     /** The most recent `limit` recorded operationIds, oldest first. */
     recentIds(limit: number): string[];
+    /**
+     * Record a frame that arrives with **no request of the caller still holding a
+     * turn**: a late engine reply (R8-高3, `EngineJsonRpcClient.onLateReply`). Its
+     * own turn was released the moment the timeout was reported to the agent, so
+     * there is no request-order position left to write at.
+     *
+     * It still goes through the turn machinery rather than a bare `record()`,
+     * because a direct write could land *between* two admitted calls and reorder
+     * the trail against the requests the agent made — the exact thing the turns
+     * exist to prevent. Claiming on arrival gives the only honest position left:
+     * behind whatever is still outstanding, and ordered among late arrivals by
+     * when they arrived.
+     *
+     * `admittedUnderGeneration` is compared **inside** that wait (see the body):
+     * the position and the epoch can only be judged at the moment the write
+     * actually happens. A reply whose request carried no generation cannot be
+     * placed either — so it is passed as {@link UNKNOWN_GENERATION} and the caller
+     * decides whether that is acceptable; this method refuses it by default, because
+     * "we do not know which attach this belongs to" is not a reason to write into
+     * somebody else's trail.
+     *
+     * `attribution` is how the transport matched that frame to a request, and it is
+     * the difference between `late` and `late-inferred` below: a frame that echoed
+     * the id the client sent is confirmed, one with no id is filed against the
+     * oldest tracked request by the daemon's in-order scheduling (R10-中2). Anything
+     * this method writes is a late arrival by construction, so the window opens
+     * whether or not the caller can say more — the default `unknown` is what the
+     * session can see on its own, and it is *not* `in-order`: an unconfirmed
+     * attribution must not read as a verified one.
+     */
+    recordLateArrival(apply: (session: EvidenceAuditSession) => void, admittedUnderGeneration?: number, attribution?: LateArrivalAttribution): Promise<LateArrivalOutcome>;
     /**
      * Claim the next position in this session's trail request order, so that
      * overlapping calls mutate and read `ids` in the order they were admitted
@@ -55,4 +206,13 @@ export declare class EvidenceAuditSession {
      */
     claimTrailTurn(): TrailTurn;
 }
+/**
+ * Bounded recursive walk (depth ≤ 3) that collects string-valued
+ * `operationId` / `evidenceId` fields — from act/assert/diagnose/restore
+ * results and from nested `evidencePack` frames. Depth is capped so an
+ * adversarial frame cannot force an unbounded descent.
+ */
+/** The same bounded walk, as the shell's one way to ask "does this frame name an
+ * operation?" — the late-reply wiring needs it to say *what* it dropped. */
+export declare function operationIds(value: unknown): string[];
 //# sourceMappingURL=audit-session.d.ts.map

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.2.0";
+    readonly version: "1.3.1";
 };
 export declare const PARSE_ERROR = -32700;
 export declare const INVALID_REQUEST = -32600;
@@ -46,8 +46,23 @@ export interface RpcResponse {
 export interface McpServerDeps {
     engine: EngineJsonRpcClient;
     specs?: readonly ToolSpec[];
-    /** Overridable audit session (per-server operationId trail, spec v1.3 §10.3). */
-    session?: EvidenceAuditSession;
+    /**
+     * The per-server operationId trail (spec v1.3 §10.3). **Required**: it used to
+     * be optional with a `?? new EvidenceAuditSession()` default, which let a
+     * server be built with a trail nobody else holds a reference to — every tool
+     * result then looked correct while `gp_recent_reports` answered from an empty
+     * trail, and the late-reply sink was wired to a *different* session. The
+     * composition is `createTrackedMcpServer`'s job now, so the default had no
+     * legitimate user (R8b-低).
+     */
+    session: EvidenceAuditSession;
+    /**
+     * Sink for facts the protocol gives no answer to: a notification this shell
+     * does not act on. Without it `notifications/cancelled` — a client saying it
+     * has given up on a request — vanished with zero trace while the daemon
+     * request it refers to stayed in flight and kept acting on the user's screen.
+     */
+    report?: (note: string) => void;
 }
 export declare class McpServer {
     private readonly deps;
@@ -72,4 +87,24 @@ export declare class McpServer {
     private result;
     private error;
 }
+/**
+ * Wire an engine client to a server over one shared audit session, including the
+ * late-reply sink (R8-高3).
+ *
+ * This is a function rather than four lines inside `main()` so that the test for
+ * "a reply that lands after the caller was answered still reaches the trail"
+ * drives **the** wiring an MCP client actually gets. Inlining it would leave the
+ * only copy of that decision in a file that runs `main()` on import, i.e. a fix
+ * on a path no test can execute.
+ *
+ * The session is created here and handed to `McpServer` rather than left to its
+ * default, because the engine client must reach the *same* instance: a late
+ * reply names an operation that really ran, and the only place an agent can get
+ * 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): {
+    server: McpServer;
+    session: EvidenceAuditSession;
+};
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/engine-client.d.ts

@@ -36,8 +36,26 @@ export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
  *
  * Deliberately not "fixed" by asking the daemon: before a connection exists
  * there is no daemon to ask, and `hello` is itself answered after connecting.
- * Matching the daemon's home lookup from Node would take an FFI call to
- * `NSHomeDirectory()`, which this shell does not have.
+ *
+ * R8-中9, and read this before "harmonising" it with `systemHome()`: matching the
+ * daemon's lookup from Node **is** available — `os.userInfo().homedir` reads the
+ * user record, the same source `NSHomeDirectory()` uses, no FFI needed, and
+ * `project-registry.ts`'s `systemHome()` does exactly that. This function
+ * deliberately does not. The two files sit on opposite sides of a safety
+ * question:
+ *   - `projects.json` is *our* data: naming a file the daemon cannot load turns
+ *     a write into a stray, so it must follow the daemon's rule.
+ *   - the engine socket is *the user's screen*: a process that pointed `$HOME`
+ *     somewhere private as its own isolation boundary currently fails to connect
+ *     ("nothing is listening on the guessed path", an honest refusal). Resolve
+ *     the home the daemon's way here and that same process silently drives the
+ *     live daemon — clicks, state writes, the whole act surface — against a
+ *     machine it asked not to be on. `$HOME`-redirect is not a supported way to
+ *     isolate from a daemon (name the socket, or don't), but it must not be
+ *     upgraded into a way to reach it either.
+ *
+ * `test/engine-client.test.mjs` pins both halves of that split, so changing
+ * either side is a deliberate edit against a red test rather than a cleanup.
  *
  * Single source all the same: the CLI argument parser in index.ts and the
  * reconnecting transport both resolve the path through this function, so an env
@@ -46,6 +64,24 @@ export declare const ENGINE_SOCKET_ENV = "GLASSPANE_ENGINE_SOCK";
 export declare function defaultSocketPath(): string;
 /** Fallback deadline for a method missing from the table below. */
 export declare const ENGINE_TIMEOUT_MS = 10000;
+/**
+ * B-02: how long a *caller* may be kept waiting for any method, whatever the
+ * daemon's own worst case is.
+ *
+ * A real MCP client times a single request out at around 60 s, stops waiting,
+ * and the agent — holding no answer, no code and no remedy — re-issues the
+ * call. On `act` that re-issue performs the same click on the user's screen a
+ * second time, which is precisely the harm a deadline is meant to remove. So
+ * the ceiling sits below a client's patience: the shell answers at 50 s with
+ * `GP_E_ENGINE_TIMEOUT` and the no-replay remedy, and the request stays
+ * registered, so the reply that arrives later is still attributed and written
+ * to the log (`onDeadline` -> `reportLateReply`). Nothing is discarded by
+ * answering early — the only thing that ends that registration is the transport
+ * going away, and `teardown` logs the tracked requests it drops when it does —
+ * which is what makes the multi-minute deadlines above safe to cap: they
+ * describe the daemon, not the caller's wait.
+ */
+export declare const CALLER_VISIBLE_CEILING_MS = 50000;
 /**
  * Per-method wall-clock deadlines. 10 s is the daemon's *internal* latency
  * flag (`EngineCore.performanceLatencyBudgetMs`), not its worst-case wall
@@ -60,9 +96,23 @@ export declare const ENGINE_TIMEOUT_MS = 10000;
  * method below the ceiling, and above it they are the daemon-side worst case
  * the timeout text quotes — the caller answered at the ceiling, while the
  * request stays registered so the real reply is attributed when it lands.
+ *
+ * `probe_status` is deliberately *not* "the cheap call, so give it the shortest
+ * window". The daemon answers one request at a time, so a probe is queued
+ * behind whatever the agent is standing over, and {@link slowEngineRemedy}
+ * tells the agent to send exactly this probe *while an `act` is outstanding*. A
+ * probe with a shorter window than the request in front of it expires against a
+ * busy daemon, and the agent then reads "the probe timed out too" as permission
+ * to restart — which cancels and rolls back an action mid-flight on the user's
+ * screen. It gets the full client-safe wait so the busy-but-will-finish case is
+ * answerable at all; the case where it is not (`act` up to 120 s against a 50 s
+ * ceiling — no deadline here can cover it, since the ceiling is the client's
+ * patience, not the daemon's) is what
+ * {@link livenessProbeDecision}'s `timed-out` entry exists to disarm.
+ * `test/probe-liveness.test.mjs` pins both halves: the armed timer, and the
+ * arithmetic invariant that no method can outlive the probe meant to diagnose it.
  */
 export declare const ENGINE_DEADLINES_MS: {
-    readonly hello: 15000;
     readonly attach: 30000;
     readonly act: 120000;
     readonly observe: 45000;
@@ -70,31 +120,29 @@ export declare const ENGINE_DEADLINES_MS: {
     readonly diagnose: 30000;
     readonly last_evidence: 60000;
     readonly snapshot: 90000;
-    readonly probe_status: 15000;
+    readonly probe_status: 50000;
+    readonly hello: 50000;
     readonly shutdown: 15000;
+    readonly audit_ui: 45000;
+    readonly capture_view: 30000;
 };
 /** Fixed part of an ffwd restore deadline (per-step cost is `act` above). */
 export declare const RESTORE_BASE_DEADLINE_MS = 30000;
 /**
- * B-02: how long a *caller* may be kept waiting for any method, whatever the
- * daemon's own worst case is.
- *
- * A real MCP client times a single request out at around 60 s, stops waiting,
- * and the agent — holding no answer, no code and no remedy — re-issues the
- * call. On `act` that re-issue performs the same click on the user's screen a
- * second time, which is precisely the harm a deadline is meant to remove. So
- * the ceiling sits below a client's patience: the shell answers at 50 s with
- * `GP_E_ENGINE_TIMEOUT` and the no-replay remedy, and the request stays
- * registered, so the reply that arrives later is still attributed and written
- * to the log (`onDeadline` -> `reportLateReply`). Nothing is discarded by
- * answering early, which is what makes the multi-minute deadlines above safe to
- * cap: they describe the daemon, not the caller's wait.
+ * The single answer to "will re-issuing this method perform a change the daemon may
+ * already have carried out?". Exported because two other layers have to ask it —
+ * `tools.ts` when it rewrites an oversized reply, `http-gateway.ts` when it answers
+ * a curl caller — and a membership list copied into each of them is how the advice
+ * for one tool drifts back into "just retry the click". A caller that wants the
+ * *reason* per method owns that text; membership comes from here.
  */
-export declare const CALLER_VISIBLE_CEILING_MS = 50000;
-/** When the caller gets its answer for `method`: its deadline, capped. */
-export declare function callerDeadlineMs(method: string, params?: Record<string, unknown>, ceilingMs?: number): number;
+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[];
 /** 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. */
+export declare function callerDeadlineMs(method: string, params?: Record<string, unknown>, ceilingMs?: number): number;
 /** Engine protocol version this shell speaks (daemon `hello.protocolVersion`). */
 export declare const ENGINE_PROTOCOL_VERSION = "0";
 /** Daemon self-report the shell compares a fresh connection against. */
@@ -126,8 +174,91 @@ export declare class EngineCallError extends Error {
     constructor(code: string, message: string, remedy: string);
     toBody(): EngineErrorBody;
 }
-/** Remedy for a deadline overrun: wait and measure, never restart or replay. */
-export declare function slowEngineRemedy(method: string): string;
+/**
+ * What an agent can learn from a `gp_probe_status` it sent while another call is
+ * outstanding, and — the part that was wrong before — what each answer
+ * authorises.
+ *
+ * R8-高1: the sentence this replaces told the agent to "restart only if
+ * gp_probe_status times out too". The daemon serves **one request at a time**,
+ * so a probe is queued behind the very request it is meant to diagnose: against
+ * a busy daemon "the probe timed out as well" is the *expected* answer, not
+ * evidence of death. Following it therefore meant running `--restore-launchd`
+ * against a daemon that is mid-`act` on the user's screen — and SIGTERM makes
+ * that daemon cancel and roll back the in-flight action (`main.swift`'s early
+ * shutdown path). A liveness check whose failure branch is reached exactly when
+ * the thing it checks is alive is not a check. Only a transport outcome can tell
+ * "gone" from "busy", so every outcome now states its own decision, and
+ * `test/probe-liveness.test.mjs` pins that exactly one of them may name the
+ * restore command.
+ */
+export type LivenessProbeOutcome = "answered" | "engine-error" | "timed-out" | "unreachable";
+/** Every outcome the four sentences below cover; the gate iterates this list. */
+export declare const LIVENESS_PROBE_OUTCOMES: readonly LivenessProbeOutcome[];
+/**
+ * The decision for one probe outcome. There is no `default` on purpose: adding
+ * an outcome to {@link LIVENESS_PROBE_OUTCOMES} without deciding what it
+ * authorises is a compile error rather than a silent hole.
+ *
+ * Only `unreachable` may name the restore command, because only it is raised
+ * when the socket itself is gone ({@link GP_E_ENGINE_UNREACHABLE}); `timed-out`
+ * is {@link GP_E_ENGINE_TIMEOUT}, which by construction means "no answer yet".
+ * The lookup is a function, not a frozen object, so the filesystem probe inside
+ * `daemonUnreachableRemedy()` stays out of module initialisation.
+ */
+export declare function livenessProbeDecision(outcome: LivenessProbeOutcome): string;
+/**
+ * Which way into this shell an answer is being delivered to. The two surfaces
+ * hold different state: only the MCP stdio server has an
+ * `EvidenceAuditSession`, so only it can promise that a late reply's
+ * operationId will come back through `gp_recent_reports`. Promising that to a
+ * `curl` caller of the HTTP gateway sends it to a tool that route does not even
+ * expose (`POST /v1/tools/recent_reports` is a 404 — `FORWARDABLE_TOOLS` skips
+ * every tool with its own `execute`), so each surface gets the sentence about
+ * the state it really has (R8b-高3).
+ */
+export type ShellSurface = "mcp" | "http";
+/** Where the answer to a timed-out request can be found, per surface. */
+export declare function lateReplyRoute(surface: ShellSurface): string;
+/**
+ * Remedy for a deadline overrun: wait and measure, never restart on a probe that
+ * merely went unanswered, and never replay a request whose re-issue has a side
+ * effect.
+ */
+export declare function slowEngineRemedy(method: string, surface?: ShellSurface): string;
+/** Log ceiling for a frame body; excess is marked, never silently cut. */
+export declare const LOG_BODY_CHARS: number;
+/**
+ * How a reply frame was matched to the request it is reported for.
+ *
+ * `echoed-id` is the frame carrying the request id this client sent and the
+ * lookup hitting; that is the only attribution this transport can *confirm*.
+ * `arrival-order` is the daemon's id-less answer (it loses the id on the paths
+ * that could not parse or could not serialize the frame), matched to the oldest
+ * request still tracked because the daemon answers in the order it received
+ * them — an inference from scheduling, never a confirmation, so anything written
+ * from it into an evidence trail has to carry that caveat with it
+ * (`EvidenceAuditSession.provenanceOf`).
+ *
+ * Spelled as the same two literals `audit-session.ts` accepts for the same
+ * reason: the transport is the only thing that sees the frame, and the session is
+ * the only thing that decides what the trail claims about an id.
+ */
+export type FrameAttribution = "echoed-id" | "arrival-order";
+/** One late engine reply, as handed to {@link EngineJsonRpcClient.onLateReply}. */
+export interface LateReply {
+    method: string;
+    result: unknown;
+    /** Whatever `call()` was given; see {@link Pending.correlation}. */
+    correlation?: number;
+    /**
+     * Whether this reply's *request* was confirmed by an echoed id or inferred
+     * from arrival order; see {@link FrameAttribution}. A sink that records this
+     * body into a trail must not present an `arrival-order` frame as a confirmed
+     * one, because the method it is filed under is a guess.
+     */
+    attribution: FrameAttribution;
+}
 /**
  * Request/response association over a line transport. Kept independent of
  * the transport so tests inject a fake LineIo (spec §7.1 "fake engine
@@ -144,10 +275,29 @@ export declare class EngineJsonRpcClient {
      * registration.
      */
     private readonly callerCeilingMs;
-    private nextId;
-    private closed;
+    /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
+    private readonly surface;
+    /**
+     * Every mutable piece of this client's state, in one object that is *never*
+     * reassigned through `this`.
+     *
+     * That is not a style choice (R10-中4). `tools.ts` hands one tool an engine view
+     * built with `Object.create(engine)`, which puts the real client on the shadow's
+     * prototype chain so the shadow shares its map, its sinks and its transport — and
+     * any method that runs with the *shadow* as `this` then writes its field on the
+     * shadow, because assigning a property that exists only on the prototype creates
+     * an own property instead of touching the prototype's. `pending` survived that
+     * only because it is a `Map` that gets mutated rather than reassigned. A
+     * `this.closed = true` did not: it marked the shadow closed and left the client
+     * sending requests on a transport it had been told to end. Reading state out of
+     * this box still resolves through the chain, and writing a property of it mutates
+     * the one box the client itself holds.
+     *
+     * `test/engine-client.test.mjs` closes the *shadow* and asserts the client behind
+     * it is closed, which is the observable form of the whole rule.
+     */
+    private readonly state;
     private readonly pending;
-    private noteHandler;
     constructor(io: LineIo, timeoutMs?: number | undefined, identity?: EngineIdentityExpectation | null, 
     /**
      * Ceiling on the caller's wait (B-02). Injectable because a test cannot
@@ -155,7 +305,9 @@ export declare class EngineJsonRpcClient {
      * caller with a longer patience gets a longer wait, never a longer
      * registration.
      */
-    callerCeilingMs?: number);
+    callerCeilingMs?: number, 
+    /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
+    surface?: ShellSurface);
     /**
      * Sink for facts that cannot be attached to any request of the caller: a
      * late reply, a frame with an id this client never issued, a daemon that
@@ -163,8 +315,31 @@ export declare class EngineJsonRpcClient {
      * "not measured" turns into a confident wrong story.
      */
     onEngineNote(handler: (note: string) => void): void;
-    /** Send a request and await its matching response frame. */
-    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Sink for the *body* of a reply that lands after its caller was already
+     * answered (R8-高3). Logging it is not enough: the operationId in that frame
+     * is the only thing that puts the operation into this session's evidence
+     * trail, and without it `gp_recent_reports` answers
+     * `GP_E_NO_EVIDENCE ... run gp_act first` for an act that genuinely ran and
+     * genuinely mutated the user's screen — an agent reading that answer clicks
+     * again. The entry the reply is attributed to is only kept for
+     * `LATE_REPLY_RETENTION` requests, so this sink sees the tracked window and
+     * the eviction note says when something fell outside it.
+     */
+    onLateReply(handler: (reply: LateReply) => void): void;
+    /**
+     * Whether {@link close} has ended this client. Public because the answer has to
+     * be readable *through* the `Object.create` shadow the tool layer builds: a
+     * shadow that was closed has to report the client behind it closed, otherwise
+     * "closed" is a property of whichever object happened to receive the call.
+     */
+    isClosed(): boolean;
+    /**
+     * Send a request and await its matching response frame. `correlation` is
+     * echoed to {@link onLateReply} if this request is answered after its caller
+     * has already been given a timeout; it is otherwise unused by this client.
+     */
+    call(method: string, params?: Record<string, unknown>, correlation?: number): Promise<unknown>;
     close(): void;
     /**
      * Timeout path: settle the caller with a *slow* diagnosis but keep the
@@ -181,14 +356,31 @@ export declare class EngineJsonRpcClient {
     private settleFromFrame;
     /**
      * A frame over the cap: attribute it to the request it belonged to — from
-     * the retained head when the daemon echoed an id, else by arrival order —
-     * and fail that one call only.
+     * the retained head when the daemon echoed an id, else by arrival order, which
+     * is the oldest *tracked* request for the same reason the id-less frame path
+     * uses it (R9-高1) — and fail that one call only.
      */
     private failOversizedReply;
     private engineError;
-    /** Oldest request the caller is still waiting on (daemon FIFO order). */
-    private oldestOpen;
+    /**
+     * 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.
+     */
+    private oldestTracked;
+    /**
+     * Route the reply that lands after its caller was already answered. `inferred`
+     * marks an attribution made by arrival order rather than by a matching id, and
+     * says so in the note — and hands the same distinction to the sink, which is
+     * the only place the caveat can travel with the body it records (R10-中2: an
+     * id-less result is a *guess about which request this is the answer to*, and a
+     * trail that files it without that note presents a guessed frame as a verified
+     * one). What the transport may not do is claim the sink recorded anything: it
+     * cannot see whether the trail accepted the frame or refused it for belonging to
+     * a superseded attach.
+     */
     private reportLateReply;
+    private reportSinkFailure;
     private resolve;
     private reject;
     /**
@@ -197,7 +389,17 @@ export declare class EngineJsonRpcClient {
      * longer answer it, and keep it after a timeout for the late reply.
      */
     private complete;
-    /** Reject everything outstanding and drop every handle. */
+    /**
+     * Reject everything outstanding and drop every handle. The settled entries go
+     * too, and that has to be reported: each of them was answered with "the
+     * request stays registered" (`onDeadline`) and with {@link lateReplyRoute}'s
+     * promise that its reply is attributed when it lands. This map is what that
+     * promise was standing on, so clearing it silently leaves an agent reading the
+     * log for an operation that really ran, finding nothing, and unable to tell
+     * "this shell stopped tracking it" from "it never happened" — the difference
+     * that decides whether it re-performs an `act` on the user's screen (R9-中1).
+     * The reverse mutation is to delete this note and keep the silent clear.
+     */
     private teardown;
     private report;
     /**
@@ -209,6 +411,7 @@ export declare class EngineJsonRpcClient {
     private handshake;
     private verifyIdentity;
 }
+export declare function truncate(text: string): string;
 /** How a transport stream is opened; injectable so tests need no socket. */
 export type EngineTransportOpener = (socketPath: string) => Duplex;
 /**
@@ -219,6 +422,8 @@ export declare function unixSocketEngineClient(socketPath: string, options?: {
     identity?: EngineIdentityExpectation;
     open?: EngineTransportOpener;
     callerCeilingMs?: number;
+    /** Pass `"http"` from the gateway: its callers have no operation trail. */
+    surface?: ShellSurface;
 }): EngineJsonRpcClient;
 /**
  * Build a client over an existing LineIo (used by tests with a fake