glasspane-mcp 1.2.0 → 1.3.0

package/dist/audit-session.d.ts

@@ -20,8 +20,23 @@ 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;
+}
 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
@@ -34,15 +49,68 @@ export declare class EvidenceAuditSession {
     /** Record every operationId/evidenceId found in an engine result frame. */
     record(result: unknown): void;
     /**
-     * Clear the trail (called after a successful attach).
+     * 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.
+     */
+    recordLateArrival(apply: (session: EvidenceAuditSession) => void, admittedUnderGeneration?: number): 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 +123,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.0";
 };
 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,22 @@ 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, 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 +94,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 +118,18 @@ 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.
- */
-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;
 /** 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 +161,64 @@ 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 user-visible action.
+ */
+export declare function slowEngineRemedy(method: string, surface?: ShellSurface): string;
+/** 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;
+}
 /**
  * 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 +235,13 @@ export declare class EngineJsonRpcClient {
      * registration.
      */
     private readonly callerCeilingMs;
+    /** Whom a timeout's remedy is being written for; see {@link ShellSurface}. */
+    private readonly surface;
     private nextId;
     private closed;
     private readonly pending;
     private noteHandler;
+    private lateReplyHandler;
     constructor(io: LineIo, timeoutMs?: number | undefined, identity?: EngineIdentityExpectation | null, 
     /**
      * Ceiling on the caller's wait (B-02). Injectable because a test cannot
@@ -155,7 +249,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 +259,24 @@ 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;
+    /**
+     * 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
@@ -219,6 +331,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

package/dist/errors.d.ts

@@ -11,15 +11,45 @@ export declare const GP_E_PROJECT_LIMIT = "GP_E_PROJECT_LIMIT";
 export declare const GP_E_NOT_FOUND = "GP_E_NOT_FOUND";
 /**
  * Codes this shell raises for itself, in one place so a string literal cannot
- * exist twice with different spellings (X-15). They are **not** daemon codes:
- * the daemon's `GPErrorCode` enum has no counterpart for either, because both
- * describe a failure of the shell↔engine connection rather than of a request —
- * a deadline this process chose to stop waiting on, and a frame too large to
- * put on the wire. An agent must be able to tell those apart from a daemon
- * error, and the daemon's own vocabulary is the only place that could add them.
+ * exist twice with different spellings (X-15).
+ *
+ * `GP_E_ENGINE_TIMEOUT` is shell-only: the daemon's `GPErrorCode` enum has no
+ * counterpart, because it describes a deadline *this process* chose to stop
+ * waiting on while the daemon may still be working. An agent must be able to
+ * tell that apart from a daemon error, and the daemon's vocabulary is the only
+ * place that could add it.
+ *
+ * `GP_E_PAYLOAD_TOO_LARGE` is **not** shell-only — the daemon declares it too
+ * (`GPErrorCode.payloadTooLarge`, raised by its dispatcher for an oversized
+ * request frame), and this shell uses the same code for an oversized frame on
+ * *its* side of the stdio/HTTP boundary. Sharing the code is deliberate: one
+ * meaning ("that frame was too big"), whichever side hit the limit. It is
+ * spelled here rather than imported because there is no shared source for the
+ * two languages, and `test/remedy-surface.test.mjs` is what keeps this
+ * paragraph true: it reads the daemon's enum and fails if any code labelled
+ * shell-only ever appears in it, or if a code this file exports stops being
+ * either shared or genuinely shell-only.
  */
 export declare const GP_E_ENGINE_TIMEOUT = "GP_E_ENGINE_TIMEOUT";
 export declare const GP_E_PAYLOAD_TOO_LARGE = "GP_E_PAYLOAD_TOO_LARGE";
+/**
+ * Shell-only, and deliberately *not* a daemon code: this is what the shell
+ * answers when a daemon error frame arrives with no `code` at all. Naming it
+ * here (rather than inlining a string at the one call site, where it used to
+ * live) keeps it inside the same vocabulary an agent can look up, and
+ * `test/remedy-surface.test.mjs` checks it really is absent from the daemon's
+ * enum — if the daemon ever declares it, this fallback stops being a shell-side
+ * invention and the split has to be re-read.
+ */
+export declare const GP_E_UNKNOWN = "GP_E_UNKNOWN";
+/**
+ * Shell-only: this process could not resolve the user whose state directory is
+ * meant (`os.userInfo()` has no record). Distinct from `GP_E_INTERNAL` because
+ * the two have different remedies — one names a file to repair, the other names
+ * the account this shell is running under — and sending an agent to open
+ * `projects.json` for the second case sends it to a file that is fine.
+ */
+export declare const GP_E_NO_USER_RECORD = "GP_E_NO_USER_RECORD";
 export interface ToolErrorText {
     code: string;
     message: string;