@gravitylabsllc/porthole 0.1.0 → 0.2.1

package/dist/index.js

@@ -4,414 +4,2067 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { DeviceClient } from "./device.js";
+import { DeviceClient, isAttached, isHandshaking } from "./device.js";
 import { TimelineServer } from "./timeline.js";
+import { readFileSync } from "node:fs";
+import { resolveProjectRoot, resolveSdkDir, restartAppAsync, runAdb, runAdbAsync } from "./adb.js";
+import { describe as describeMoment, fromBootMs, momentOf, toBoot } from "./moment.js";
+import { CPU_PROBE, describeSystem, parseCpu, parseMemory, parseThermal, parseTop, } from "./system.js";
+import { askTrace, findTraceProcessor, QUESTIONS } from "./perfetto.js";
+import { captureArgs, countPortholeLabels, describeCapture, planCapture } from "./systrace.js";
+import { mkdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildTrace, describeBudget, num, resolveProfile, str } from "./trace.js";
+import { UNKNOWN_DEVICE_ID, clippedMsOf, fillWindowFromDisk, sessionsRoot as sessionsRootPath, } from "./sessions.js";
+import { InvalidScenarioError, buildSavedTrace, coverageNote, defaultOutPath, defaultScenarioName, validateScenario, writeSavedTrace } from "./save.js";
+import { Watermark, buildBanner, classificationSummary, classify } from "./watermark.js";
+/** Read, not retyped: a hardcoded version here drifts from the package. */
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const HOST = process.env.PORTHOLE_HOST ?? "127.0.0.1";
 const PORT = Number(process.env.PORTHOLE_PORT ?? 8677);
 const UI_PORT = Number(process.env.PORTHOLE_UI_PORT ?? 8678);
-const device = new DeviceClient(HOST, PORT);
-const timeline = new TimelineServer(device, UI_PORT);
-const server = new McpServer({
-    name: "porthole",
-    version: "0.1.0",
-});
-/** Summary line first, then the JSON. The summary is often the whole answer. */
-function ok(summary, payload) {
-    return {
-        content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(payload, null, 2)}` }],
-    };
-}
-function fail(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { content: [{ type: "text", text: message }], isError: true };
-}
-async function call(method, params, summarise) {
-    try {
-        const result = await device.request(method, params);
-        return ok(summarise(result), result);
+/**
+ * GRA-89: how much longer than the plan's own recording duration
+ * `capture_system_trace` gives the on-device `perfetto` invocation before
+ * presuming it wedged — adb's own connect/attach overhead plus whatever
+ * margin covers a slow device, on top of the `-t Ns` the command itself
+ * asked to run for.
+ */
+const CAPTURE_ADB_TIMEOUT_BUFFER_MS = 30_000;
+/**
+ * GRA-186: how long `capture_system_trace`'s `restartApp: true` path polls
+ * for the on-device trace file before giving up and restarting anyway.
+ *
+ * The recording itself is one `runAdbAsync` call that only resolves when the
+ * whole `-t Ns` window is over (GRA-89), so it gives no mid-flight signal
+ * that the session has actually started — restarting the app before it has
+ * would just repeat the case this option exists to fix, restarting after the
+ * whole window is over would restart to no purpose at all. Perfetto creates
+ * its output file on-device as soon as the session starts, before it writes
+ * a single event into it, so polling for that file's existence is the
+ * smallest reliable "it has started" signal available without parsing
+ * perfetto's own stderr. If it never appears within this bound the restart
+ * still goes ahead — the whole point is to make the app tag visible to the
+ * target process, and doing that late is far better than not doing it.
+ */
+const RESTART_POLL_TIMEOUT_MS = 5_000;
+const RESTART_POLL_INTERVAL_MS = 150;
+async function waitForCaptureToStart(devicePath, options) {
+    const deadline = Date.now() + RESTART_POLL_TIMEOUT_MS;
+    for (;;) {
+        const probe = await runAdbAsync(["shell", "test", "-e", devicePath], { ...options, timeoutMs: 2_000 });
+        if (probe.ok)
+            return;
+        if (Date.now() >= deadline)
+            return;
+        await new Promise((resolveWait) => setTimeout(resolveWait, RESTART_POLL_INTERVAL_MS));
     }
-    catch (error) {
-        return fail(error);
+}
+/**
+ * GRA-171: builds the `content` array both `ok()` and `fail()` return, so
+ * there is exactly one place a summary and a payload are put together.
+ *
+ * GRA-169 defended this same seam by *normalising*: `ok()` joined summary
+ * and payload with the literal string `"\n\n"` and collapsed every blank
+ * line out of the summary first, because a consumer found the payload by
+ * searching the *text* for that substring — a property of the string, not
+ * of anything the protocol enforced. Interpolate a device value containing
+ * a blank line (`hello.device`, say) into the summary and the search finds
+ * the wrong occurrence, slicing from the middle of the prose instead of the
+ * start of the JSON; `JSON.parse` throws and the payload is gone, not
+ * merely mislabelled. Normalising away every blank line closed that one
+ * failure mode (14 tests, no known gap) but it was still a textual fix for
+ * a textual bug: it bought safety by silently rewriting an author's
+ * intended blank line into a space, and it left `fail()` unguarded, since
+ * `fail()` never called `collapseBlankLines()` — a second chokepoint nobody
+ * had reason to notice was missing.
+ *
+ * GRA-171's structural option was on the table from the start but rejected
+ * for a reason that did not hold: 0.1.0 wire compatibility. The founder's
+ * 2026-09-15 decision that 0.2.0 may change this delimiter removes that
+ * obstacle, so the summary and the payload are now two separate blocks in
+ * the `content` array, never one string joined by a marker. **This is what
+ * "the delimiter cannot occur in data" means concretely: there is no
+ * delimiter for a value to collide with, at any position, in either
+ * block.** A consumer takes `content[0]` for the summary and `content[1]`
+ * for the payload by position — the same way this function decides which
+ * is which by argument count, not by scanning either string for anything.
+ * No text search happens over either block's contents at all, so a value
+ * containing every shape GRA-169 catalogued (CRLF pairs, three to seven
+ * consecutive newlines, whitespace-only lines, U+2028/U+2029, NBSP, form
+ * feed, leading and trailing blank lines, the empty string, or literally
+ * `"\n\n"` itself) is carried verbatim in its own block and never
+ * inspected here. If a future call site ever concatenated the payload back
+ * into the summary string by hand instead of passing it as the `payload`
+ * argument, that call site alone would reintroduce a textual seam — this
+ * function cannot protect against bypassing itself, only against being
+ * used and still failing.
+ *
+ * `collapseBlankLines()` (GRA-169) is deleted rather than kept alongside
+ * this, and that is a deliberate call, not reflex. GRA-168's CRLF
+ * normalisation was kept after GRA-166's scanner made it redundant for
+ * *correctness*, because it still served a second purpose — canonical
+ * output — that removing it would have destroyed. `collapseBlankLines()`
+ * has no second purpose: its only job, on every call site, was defending
+ * the "\n\n" delimiter, and it always cost prose fidelity to do it — a
+ * device value an agent might want verbatim came back with its blank lines
+ * flattened to spaces. With no delimiter left to defend, keeping it would
+ * mean paying that cost for a defence nothing needs any more. That is a
+ * reason to remove it, not merely permission to.
+ *
+ * Module-level and exported, as `collapseBlankLines()` was, so
+ * `index.test.ts` can call this directly with adversarial summaries and
+ * payloads and assert on the `content` array's shape and the payload
+ * block's JSON round-trip — no `vi.mock`/`spyOn` needed, because there is
+ * no module-local binding to intercept: the function under test *is* the
+ * chokepoint, not a wrapper around one.
+ */
+export function joinSummaryAndPayload(summary, ...payload) {
+    const blocks = [{ type: "text", text: summary }];
+    if (payload.length > 0) {
+        // JSON.stringify(undefined) is the JS value `undefined`, not a string —
+        // the `?? "null"` keeps this block's `text` a real string always (the
+        // MCP content schema requires one), and keeps the payload something
+        // `JSON.parse` can read back rather than a block with no usable text.
+        blocks.push({ type: "text", text: JSON.stringify(payload[0], null, 2) ?? "null" });
     }
+    return blocks;
 }
-// ---------------------------------------------------------------------------
-// tools
-// ---------------------------------------------------------------------------
-server.registerTool("porthole_status", {
-    title: "Porthole status",
-    description: "Whether the porthole is connected to a running app, which collectors are active, and what to " +
-        "do if it is not. Start here when another tool reports it cannot reach the device.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-}, async () => {
-    const payload = {
-        state: device.state,
-        host: HOST,
-        port: PORT,
-        app: device.hello,
-        timelineUi: timeline.isRunning() ? timeline.url() : null,
-        bufferedEvents: timeline.buffer().length,
-        lastError: device.lastError,
-    };
-    const summary = device.state === "connected" && device.hello
-        ? `Connected to ${device.hello.packageName} on ${device.hello.device} ` +
-            `(API ${device.hello.sdkInt}). Collectors: ${device.hello.collectors.join(", ")}.`
-        : device.notConnectedMessage();
-    return ok(summary, payload);
-});
-server.registerTool("recompositions", {
-    title: "Recomposition counts",
-    description: "How many times each instrumented composable recomposed, and which state keys were written " +
-        "just before each recomposition. Use it to find the composable doing needless work and the " +
-        "state that keeps invalidating it.\n\n" +
-        "Two limits worth holding in mind: only call sites wrapped in PortholeScreen or " +
-        "Modifier.portholeNode are counted, so an absent composable is uninstrumented rather than " +
-        "idle; and triggeredBy is a temporal correlation within a ~32ms window, not a causal read " +
-        "of the invalidation graph, so several states changing in one frame all get listed.\n\n" +
-        "Keys like 'unnamed#3f2a1c' are state objects nobody named. In a Compose app most of them " +
-        "belong to the framework — ripples, scroll offsets, focus, animation clocks — and are not " +
-        "worth chasing. A key that is yours and still unnamed means its owner was never registered: " +
-        "Porthole.registerViewModel for a ViewModel, collectAsNamedState for a Flow, " +
-        "rememberNamedState for state a composable creates for itself.\n\n" +
-        "A key carrying 'holds' is anonymous state that was found holding one of the app's own " +
-        "types, so it is definitely the app's and definitely unregistered — that one is worth " +
-        "chasing. Its absence proves nothing: an unregistered Int is indistinguishable from a " +
-        "ripple, so most of the app's own unnamed state will not be flagged.",
-    inputSchema: {
-        screen: z
-            .string()
-            .optional()
-            .describe("Only nodes on this screen, matched against the enclosing PortholeScreen name."),
-        sinceMs: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe("Look back this many milliseconds. Omit for everything still buffered."),
-        from: z
-            .number()
-            .int()
-            .optional()
-            .describe("Absolute start, in the device uptime clock every event carries. Use this to ask " +
-            "about a moment seen on the timeline instead of guessing a lookback."),
-        to: z.number().int().optional().describe("Absolute end, same clock. Defaults to now."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ screen, sinceMs, from, to }) => call("recompositions", { screen, sinceMs, from, to }, (report) => {
-    if (report.nodes.length === 0) {
-        return "No instrumented composable recomposed in that window.";
+export function createPortholeServer(options = {}) {
+    // GRA-53 `#window-fallback`: the real boot path gets on-disk session
+    // persistence; a test that injects its own `options.device` (the harness
+    // in `testing/harness.ts`, or a hand-built fake) is unaffected — this
+    // branch only runs when nothing was injected.
+    const device = options.device ?? new DeviceClient(HOST, PORT, sessionsRootPath(resolveProjectRoot().directory));
+    const timeline = options.timeline ?? new TimelineServer(device, UI_PORT);
+    const adbEnv = options.adbEnv;
+    const adbBinary = options.adbBinary;
+    // GRA-55: one watermark per process (see watermark.ts's module doc comment
+    // for why not per connection), re-opened against whichever session
+    // directory is current every time a tool runs — cheap, since `open()` is a
+    // no-op once the directory has not changed.
+    const watermark = new Watermark();
+    /** Set by `resolveWindowSince` on a first-ever `since: "last"` call, consumed by `ok()` (AC5). */
+    let pendingFirstEverNote = null;
+    const FIRST_EVER_NOTE = 'First call this session: "since": "last" has nothing to start from yet, so this is the ' +
+        "whole buffer, the same default as before since existed. ";
+    const server = new McpServer({
+        name: "porthole",
+        version: options.version ?? pkg.version,
+    });
+    /**
+     * Summary first, payload second — as two `content` blocks now (see
+     * `joinSummaryAndPayload()` above), not one string joined by a delimiter.
+     * GRA-171: the post-collapse assertion this function used to carry
+     * (`ok(): summary still contains a blank line after
+     * collapseBlankLines()`) is deleted along with `collapseBlankLines()`
+     * itself, and deliberately, not by omission. That assertion guarded one
+     * specific failure of the textual design — the delimiter search finding
+     * the wrong "\n\n" — and GRA-169's own QA had already shown it was
+     * unreachable by any test without a production refactor, because `ok()`
+     * called `collapseBlankLines` by a module-local binding no mock could
+     * intercept. A structural join has no blank-line assumption to violate:
+     * there is no search, so there is nothing for the assertion to catch that
+     * `joinSummaryAndPayload()`'s own direct tests do not already cover by
+     * construction. Keeping an assertion for a failure mode that no longer
+     * exists would be exactly the untested-claim shape this ticket exists to
+     * end, just moved from "untested" to "vacuous".
+     */
+    /**
+     * GRA-55: the one place every successful tool result passes through, which
+     * is what "the banner goes on every tool, built in one place" (the EM's
+     * own condition for this ticket) means concretely — no per-tool call adds
+     * it, so no tool can forget it the way the ticket's own history names as
+     * the risk ("the one tool that forgets is the one the agent was using
+     * when the ANR happened"). `attachSinceLastAndBanner()` does the actual
+     * work; this function stays a thin async wrapper so every existing call
+     * site (`return ok(summary, payload)`, inside an already-`async` handler)
+     * keeps compiling unchanged — an `async` function returning a `Promise`
+     * is flattened by the caller's own `await`/`return` exactly as returning
+     * the value directly would be.
+     */
+    async function ok(summary, payload) {
+        const { summary: withBanner, payload: withSinceLast } = await attachSinceLastAndBanner(summary, payload);
+        return { content: joinSummaryAndPayload(withBanner, withSinceLast) };
     }
-    const top = report.nodes[0];
-    const cause = top.triggeredBy[0];
-    const total = report.nodes.reduce((sum, node) => sum + node.count, 0);
-    return (`${total} recompositions across ${report.nodes.length} nodes. ` +
-        `Worst: ${top.name} at ${top.count}` +
-        (cause ? `, most often after a write to ${cause.key} (${cause.count} of them).` : "."));
-}));
-server.registerTool("semantics_tree", {
-    title: "Semantics tree",
-    description: "The Compose semantics tree with a stable id per node. stableId is a structural path hash: " +
-        "the same UI produces the same id across captures and across process restarts, so two " +
-        "captures can be diffed. Nodes carrying a porthole node id line up with the ids in the " +
-        "recompositions report.",
-    inputSchema: {
-        merged: z
-            .boolean()
-            .optional()
-            .describe("Merged tree (what accessibility services see). Default true."),
-        maxDepth: z.number().int().positive().optional().describe("Depth cap. Default 40."),
-        maxNodes: z.number().int().positive().optional().describe("Node budget. Default 1500."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ merged, maxDepth, maxNodes }) => call("semantics_tree", { merged, maxDepth, maxNodes }, (tree) => tree.error ? tree.error : tree.root ? "Captured the semantics tree." : "Empty tree."));
-server.registerTool("nav_state", {
-    title: "Navigation state",
-    description: "The current back stack with each entry's route, arguments and lifecycle state, plus the " +
-        "deep link that opened the app if there was one. Answers 'how did I get to this screen' " +
-        "and 'what arguments is it actually holding', which is usually where the bug is.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-}, async () => call("nav_state", {}, (nav) => nav.error ??
-    `At ${nav.current?.route ?? "an unnamed destination"} with ${nav.backStack.length} entries on the stack.`));
-server.registerTool("state", {
-    title: "ViewModel state",
-    description: "Current values of the state held by registered ViewModels. Each field says whether writes " +
-        "to it are attributable — meaning snapshot state the recomposition report can name. A " +
-        "StateFlow is never attributable on its own; collectAsNamedState is what makes the State " +
-        "it produces nameable.",
-    inputSchema: {
-        viewModel: z
-            .string()
-            .optional()
-            .describe("Registered name or class name. Omit for every registered owner."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ viewModel }) => call("state", { viewModel }, (dump) => {
-    if (dump.owners.length === 0) {
-        return 'No ViewModels registered. Call Porthole.registerViewModel("CartViewModel", vm) where you obtain it.';
+    /**
+     * GRA-171: routes through `joinSummaryAndPayload()` too, with no payload
+     * block (a bare `payload.length > 0` check away from getting one, if an
+     * error ever needs structured detail). Before this ticket `fail()` built
+     * its `content` array by hand and never passed through the chokepoint
+     * `ok()` used for `collapseBlankLines()` — the GRA-169 ticket named this
+     * explicitly as half of why normalisation could not be a complete fix.
+     * With both going through the same function there is exactly one place
+     * a `content` array is assembled, for success or failure alike.
+     */
+    function fail(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: joinSummaryAndPayload(message), isError: true };
     }
-    return dump.owners.map((owner) => `${owner.name} (${owner.fields.length} fields)`).join(", ");
-}));
-server.registerTool("inflight", {
-    title: "In-flight work",
-    description: "Open HTTP calls with the phase each is stuck in, database queries currently executing and " +
-        "the thread running them, and enqueued or running WorkManager jobs. This is the tool for " +
-        "'why is this screen still spinning'.\n\n" +
-        "Also returns recentHttp: the last 25 finished calls with status, headers and — when the " +
-        "app opted in via BodyCapture — request and response body previews. A body with text:null " +
-        "carries an omittedReason saying why it was not captured (disabled, wrong content type, " +
-        "one-shot stream); that is different from the call having had no body at all.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-}, async () => call("inflight", {}, (flight) => {
-    const parts = [];
-    if (flight.http.length) {
-        const worst = flight.http[0];
-        parts.push(`${flight.http.length} HTTP call(s), oldest ${worst.method} ${worst.url} ` +
-            `in '${worst.phase}' for ${worst.elapsedMs}ms`);
+    async function call(method, params, summarise) {
+        try {
+            const result = await device.request(method, params);
+            return ok(summarise(result), result);
+        }
+        catch (error) {
+            return fail(error);
+        }
     }
-    if (flight.queries.length) {
-        const writes = flight.queries.filter((q) => q.kind === "write").length;
-        parts.push(`${flight.queries.length} query(ies) running on ${flight.queries[0].thread}` +
-            (writes ? ` (${writes} write)` : ""));
+    /**
+     * GRA-163: the payload half of the stale-ring fix, so an agent can tell
+     * live data from post-mortem data without parsing the prose next to it.
+     *
+     * GRA-163 QA round 1: this used to take the caller's own `connected`
+     * value as a parameter, so it agreed with whichever sense of "connected"
+     * the caller happened to be using for its own boolean field — loose
+     * (isAttached) on an empty-ring branch, strict (pending === null) on a
+     * non-empty one. That is fine for the `connected` field itself (GRA-157
+     * chose the loose sense on purpose, for "should an agent keep polling"),
+     * but `exitedProcess` answers a different question — "is what I am about
+     * to hand back confirmed to belong to the running process" — and that
+     * question has exactly one right answer regardless of which `connected`
+     * a given branch reports, or it is the same defect this ticket exists to
+     * remove: three tools (or two branches of one tool) disagreeing about the
+     * same state. So this is gated on `device.pendingMessage() === null`
+     * directly — the strict sense, always, independent of the caller's own
+     * `connected` — which is also why `porthole_status` (which never had a
+     * `connected` field at all) and `findings`/`what_was_happening`'s
+     * empty-ring branches (which report the loose sense) now all agree with
+     * the non-empty branches on when this is null.
+     *
+     * Null whenever a session is currently confirmed live, or nothing has
+     * ever exited in this server's lifetime (`device.lastExited` starts
+     * null). Otherwise the last confirmed process and when its socket closed,
+     * in the same shape every tool that calls this returns it in, so the
+     * three tools' payloads agree on more than just prose.
+     */
+    function exitedProcessField() {
+        if (device.pendingMessage() === null || !device.lastExited)
+            return null;
+        const { hello, disconnectedAt } = device.lastExited;
+        return {
+            packageName: hello.packageName,
+            device: hello.device,
+            disconnectedAt: new Date(disconnectedAt).toISOString(),
+        };
     }
-    if (flight.work.length)
-        parts.push(`${flight.work.length} work job(s)`);
-    const recent = flight.recentHttp ?? [];
-    const failed = recent.filter((c) => c.status !== null && c.status >= 400);
-    if (recent.length) {
-        parts.push(`${recent.length} recent call(s)` +
-            (failed.length ? `, ${failed.length} with a ${failed[0].status}` : ""));
+    /**
+     * The prose half, and — after QA round 1 — the *only* place any tool says
+     * anything about an exited process. `device.ts`'s `pendingMessage()` used
+     * to append its own sentence here ("whatever is still buffered is from
+     * X"), which was wrong on any branch where nothing actually is buffered:
+     * `pendingMessage()` has no visibility into `timeline.buffer()`, only
+     * this file does. `hasBufferedData` must be true only when the ring this
+     * particular answer is about genuinely has content — every call site
+     * below passes the same fact it already used to choose its branch (the
+     * `!span`/`events.length === 0` checks), never a guess.
+     *
+     * `connected` (QA round 2): `exited` is null in two different
+     * situations — a confirmed live session (`connected: true`, nothing to
+     * say), and no confirmed live session *and* nothing has ever exited in
+     * this server's lifetime (the very first connection, still handshaking,
+     * with a ring already non-empty — GRA-163's own race mechanism:
+     * `buildRaceRig()`, push one event before the deferred `hello` resolves).
+     * The second case still has real data with no confirmed owner and needs
+     * its own sentence — the original fix said so ("Nothing has confirmed
+     * itself as the running process yet...") until this function's QA round 1
+     * rewrite silently dropped it while consolidating three call sites into
+     * one. Restored here, gated on there being data to caveat in the first
+     * place: an empty ring with no known predecessor has nothing worth
+     * flagging beyond what `pending`'s own message already says.
+     */
+    function exitedProcessNotice(exited, hasBufferedData, connected) {
+        if (exited) {
+            return hasBufferedData
+                ? `${exited.packageName} on ${exited.device} exited at ${exited.disconnectedAt}; what ` +
+                    "follows is from it, not from what is running now. "
+                : `${exited.packageName} on ${exited.device} exited at ${exited.disconnectedAt}; nothing ` +
+                    "is currently buffered from it. ";
+        }
+        if (!connected && hasBufferedData) {
+            return ("Nothing has confirmed itself as the running process yet, so what follows is not yet " +
+                "confirmed to be live. ");
+        }
+        return "";
     }
-    return parts.length ? parts.join("; ") : "Nothing in flight.";
-}));
-server.registerTool("frames", {
-    title: "Frame timing",
-    description: "How many frames the app dropped, and where the time went in the worst ones. This is the " +
-        "outcome every other collector is a proxy for: a recomposition count only matters because " +
-        "of what it does to frame time.\n\n" +
-        "worstPhase names the stage that dominated a janky frame, which is what decides where to " +
-        "look: layoutMeasure or draw points at composition doing too much, gpu or swapBuffers at " +
-        "overdraw or an expensive shader, unknownDelay at the main thread being busy with " +
-        "something that is not drawing at all. Pair a jank cluster with recompositions over the " +
-        "same from/to window to see whether recomposition is the cause.\n\n" +
-        "Frames with firstDraw are a window being drawn for the first time and are expected to be " +
-        "slow. Needs API 24 or newer.",
-    inputSchema: {
-        sinceMs: z.number().int().positive().optional().describe("Only the last N milliseconds."),
-        from: z.number().int().optional().describe("Absolute start, device uptime clock."),
-        to: z.number().int().optional().describe("Absolute end, same clock."),
-        limit: z
-            .number()
-            .int()
-            .positive()
-            .max(200)
-            .optional()
-            .describe("Worst N frames. Default 20."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ sinceMs, from, to, limit }) => call("frames", { sinceMs, from, to, limit }, (report) => {
-    if (report.totalFrames === 0)
-        return "No frames observed yet.";
-    const rate = ((report.jankyFrames / report.totalFrames) * 100).toFixed(1);
-    const worst = report.worst[0];
-    const byPhase = {};
-    for (const frame of report.worst) {
-        byPhase[frame.worstPhase] = (byPhase[frame.worstPhase] ?? 0) + 1;
+    // ---------------------------------------------------------------------------
+    // GRA-58: why the app died, folded into porthole_status rather than a new tool
+    // ---------------------------------------------------------------------------
+    /** How many recent exits `porthole_status`'s `exits.recent` carries — a literal, not "however many fit". */
+    const EXITS_SECTION_CAP = 10;
+    /** How long after an exit it is still worth calling out as *why* the app is not connected right now. */
+    const RECENT_EXIT_MS = 5 * 60 * 1000;
+    /**
+     * `porthole_status`'s `exits` payload: the most recent deaths this
+     * process's ring still holds (the runtime's `ExitInfoCollector` put them
+     * there at install time — see `Protocol.kt#exit`), newest first, and the
+     * one fact that needs no ring content at all: whether the exit-reason API
+     * exists on this device. `hello.sdkInt` already answers that — the
+     * runtime emits nothing at all below API 30 (GRA-58's own ruling), so
+     * there is no event to read for it either way.
+     */
+    function exitsSection() {
+        const hello = device.hello ?? device.lastExited?.hello ?? null;
+        const sdkInt = hello?.sdkInt;
+        const apiUnavailable = sdkInt !== undefined && sdkInt < 30
+            ? `The exit-reason API needs Android 11 (API 30); this device reports API ${sdkInt}, so no exit history is available.`
+            : null;
+        const recent = timeline
+            .buffer()
+            .filter((e) => e.event === "exit")
+            .slice()
+            .sort((a, b) => num(b.data.timestamp) - num(a.data.timestamp))
+            .slice(0, EXITS_SECTION_CAP)
+            .map((e) => ({
+            reason: str(e.data.reason),
+            timestamp: num(e.data.timestamp),
+            at: new Date(num(e.data.timestamp)).toISOString(),
+            versionName: e.data.versionName != null ? str(e.data.versionName) : null,
+            versionAssumed: e.data.versionAssumed === true,
+            topAppFrame: str(e.data.mainStack).split("\n")[0] || null,
+        }));
+        return { apiUnavailable, recent };
     }
-    const phases = Object.entries(byPhase)
-        .sort((a, b) => b[1] - a[1])
-        .map(([phase, n]) => `${phase} ${n}`)
-        .join(", ");
-    return (`${report.jankyFrames} of ${report.totalFrames} frames janky (${rate}%), ` +
-        `budget ${report.frameIntervalMs}ms.` +
-        (worst
-            ? ` Worst ${worst.totalMs}ms, ${worst.missedFrames} refresh(es) missed, mostly ` +
-                `${worst.worstPhase}. Across the worst frames: ${phases}.`
-            : ""));
-}));
-server.registerTool("blocking", {
-    title: "Main thread blocking",
-    description: "What held the main thread: stalls longer than the threshold, with the stack the main " +
-        "thread was in at the time, and any database query that ran on it.\n\n" +
-        "Stalls are found by pinging the main looper and timing the reply, so the duration is how " +
-        "long everything queued ahead of the ping took. The stack is sampled once, when the ping " +
-        "goes overdue, and app frames are listed first because the top frame is usually a native " +
-        "read and the line you can change is a few frames down.\n\n" +
-        "Database work on the main thread is reported however fast it was: a 4ms disk read in the " +
-        "frame loop is a defect that has not bitten yet. For hitches shorter than the threshold, " +
-        "use `frames` instead — that measures every frame, this one catches the big stops.",
-    inputSchema: {
-        sinceMs: z.number().int().positive().optional().describe("Only the last N milliseconds."),
-        from: z.number().int().optional().describe("Absolute start, device uptime clock."),
-        to: z.number().int().optional().describe("Absolute end, same clock."),
-        limit: z
+    /**
+     * "the app is not connected because it died and why" (GRA-58's own
+     * wording): only when there is genuinely no live session right now, and
+     * only when the most recent exit is recent enough that it is plausibly
+     * *why* — an exit from an hour ago says nothing about a disconnect that
+     * just happened.
+     */
+    function exitDeathNotice(recent, stronglyConnected) {
+        if (stronglyConnected || recent.length === 0)
+            return "";
+        const latest = recent[0];
+        const ageMs = Date.now() - latest.timestamp;
+        if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs > RECENT_EXIT_MS)
+            return "";
+        const build = latest.versionName
+            ? `${latest.versionName}${latest.versionAssumed ? " (assumed)" : ""}`
+            : "an unknown build";
+        const frame = latest.topAppFrame ? ` Top app frame: ${latest.topAppFrame}.` : "";
+        return (`Not connected because the app died: ${latest.reason} (${build}) at ${latest.at}.` + frame + " ");
+    }
+    // ---------------------------------------------------------------------------
+    // windows
+    // ---------------------------------------------------------------------------
+    /**
+     * The same three parameters on every tool that looks at a span of time.
+     *
+     * They used to differ per tool — `timeline` took only `sinceMs`, which made it
+     * the one tool that could not be asked about a moment the others had just
+     * named. An agent that cannot carry a window between calls compares two
+     * different windows and does not notice.
+     *
+     * GRA-120: `sinceMs` anchors to `to` (explicit, or this host's own estimate
+     * of "now" below) rather than to a true "now" the way the runtime's own
+     * `Window.resolve` does — this host has no device clock, only the
+     * timestamps events arrive stamped with, so "now" here can only ever be
+     * "the newest thing we have seen", never the actual current instant. See
+     * `resolveWindow` below for exactly what that means and why it is the
+     * honest choice rather than an alignment gap.
+     */
+    const windowShape = {
+        sinceMs: z
             .number()
             .int()
             .positive()
-            .max(100)
-            .optional()
-            .describe("Worst N of each. Default 20."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ sinceMs, from, to, limit }) => call("blocking", { sinceMs, from, to, limit }, (report) => {
-    const parts = [];
-    if (report.stalls.length) {
-        const worst = report.stalls[0];
-        parts.push(`${report.stalls.length} stall(s) over ${report.stallThresholdMs}ms, worst ` +
-            `${worst.durationMs}ms in ${worst.stack.split("\n")[0]}`);
-    }
-    if (report.mainThreadQueries.length) {
-        const worst = report.mainThreadQueries[0];
-        parts.push(`${report.mainThreadQueries.length} database ${report.mainThreadQueries.length === 1 ? "query" : "queries"} ` +
-            `on the main thread, worst ${worst.elapsedMs}ms: ${worst.sql.slice(0, 80)}`);
-    }
-    return parts.length ? parts.join(". ") : "Nothing blocked the main thread in this window.";
-}));
-server.registerTool("logs", {
-    title: "App logs",
-    description: "The app's own logcat output, captured in-process and streamed over the same socket as " +
-        "everything else — no adb needed. Stack traces arrive attached to the line that started " +
-        "them rather than as loose fragments.\n\n" +
-        "Entries carry the same uptime clock as the timeline, so a log line can be placed against " +
-        "a recomposition burst or an HTTP call. Only the app's own output is visible, and the " +
-        "porthole's own tag is excluded.",
-    inputSchema: {
-        level: z
-            .enum(["V", "D", "I", "W", "E", "F"])
             .optional()
-            .describe("Minimum level. 'W' for warnings and worse, which is usually what you want."),
-        tag: z.string().optional().describe("Substring match on the tag."),
-        contains: z.string().optional().describe("Substring match on the message."),
-        sinceMs: z.number().int().positive().optional().describe("Only the last N milliseconds."),
+            .describe("Look back this many milliseconds from `to`. If `to` is omitted, from this host's best " +
+            "estimate of the device's current time (see `to`'s description), or from the device's " +
+            "own current time when nothing is buffered here yet. Ignored if `from` is given."),
         from: z
             .number()
             .int()
             .optional()
-            .describe("Absolute start, in the device uptime clock every event carries. Use this to ask " +
-            "about a moment seen on the timeline instead of guessing a lookback."),
-        to: z.number().int().optional().describe("Absolute end, same clock. Defaults to now."),
-        limit: z
+            .describe("Absolute start on the device uptime clock that every event carries. Quote the `window` " +
+            "from an earlier result to ask a second question about the same span."),
+        to: z
             .number()
             .int()
-            .positive()
-            .max(2000)
             .optional()
-            .describe("Newest N entries. Default 200."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ level, tag, contains, sinceMs, from, to, limit }) => call("logs", { level, tag, contains, sinceMs, from, to, limit }, (page) => {
-    if (!page.capturing) {
-        return page.notes.join(" ") || "Log capture is not running.";
-    }
-    if (page.entries.length === 0) {
-        return page.notes.join(" ") || "No log entries matched.";
-    }
-    const counts = {};
-    for (const entry of page.entries)
-        counts[entry.level] = (counts[entry.level] ?? 0) + 1;
-    const worst = page.entries
-        .filter((entry) => entry.level === "E" || entry.level === "F")
-        .at(-1);
-    return (`${page.entries.length} entries (` +
-        Object.entries(counts)
-            .map(([level, count]) => `${level} ${count}`)
-            .join(", ") +
-        ")" +
-        (worst
-            ? `. Latest error: ${worst.tag}: ${worst.message.split("\n")[0].slice(0, 120)}`
-            : "."));
-}));
-server.registerTool("timeline", {
-    title: "Event timeline",
-    description: "Raw event stream: recompositions, state writes, navigation, HTTP and database start/end. " +
-        "Use it to order events relative to each other — which write came before which navigation, " +
-        "what the app was doing while a call was open.",
-    inputSchema: {
-        sinceMs: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe("Only events from the last N milliseconds of device uptime."),
-        kinds: z
-            .array(z.string())
-            .optional()
-            .describe("Filter by event name: recompose, state_write, frame, nav, http_start, http_end, " +
-            "db_start, db_end, log."),
-        limit: z
-            .number()
-            .int()
-            .positive()
-            .max(5000)
+            .describe("Absolute end, same clock. Defaults to this host's best estimate of the device's current " +
+            "time: the newest event currently buffered, since the host has no clock of the device's " +
+            "own to read."),
+        // GRA-55: only consulted when none of sinceMs/from/to above are given —
+        // same precedence sinceMs already has against from/to. "last" is the
+        // default rather than a value someone has to ask for, because the whole
+        // point is that an agent should not have to guess a lookback.
+        since: z
+            .enum(["last", "all"])
             .optional()
-            .describe("Newest N events. Default 500."),
-    },
-    annotations: { readOnlyHint: true },
-}, async ({ sinceMs, kinds, limit }) => {
-    try {
-        // Prefer the local buffer: it holds more history than the device ring and
-        // survives the app being restarted underneath us.
-        let events = timeline.buffer();
+            .describe('"last" (the default when sinceMs/from/to are all omitted) starts where the previous ' +
+            "window-taking tool call on this session left off, so nothing since is missed and " +
+            'nothing already examined is re-read. On the very first call this session has ever made, ' +
+            '"last" behaves exactly like today\'s default (the whole buffer). "all" is the reset: the ' +
+            "whole buffer plus disk, same as every call before this existed, and it clears the " +
+            "watermark that \"last\" tracks."),
+    };
+    /**
+     * The span actually examined, resolved against the buffer so it can be
+     * quoted back.
+     *
+     * GRA-120: brought into line with the runtime's `Window.resolve` on the
+     * two points that were outright bugs — a negative `from` used to reach
+     * back before the device existed instead of clamping at 0 (`Window.kt`'s
+     * own words: "not `Long.MIN_VALUE`: a timestamp on this clock cannot be
+     * negative"), and an inverted window (`from` after `to`, or a `to` in the
+     * past that `sinceMs` does not reach) used to hand a tool a backwards span
+     * instead of being refused the way the tool already refuses "no window at
+     * all". Both are fixed here, once, rather than in every caller.
+     *
+     * `sinceMs` anchoring to `to` (explicit or defaulted) rather than to a
+     * true "now" is deliberately *not* changed to match the runtime bit for
+     * bit: the runtime reads its own clock, and this host cannot — its only
+     * source for "now" is the timestamp on the newest event it has seen,
+     * which is what `to` already defaults to below. So "anchor `sinceMs` to
+     * `to`" and "anchor it to the device's actual now" are the same rule
+     * here, applied with the one clock this process actually has access to.
+     * In the normal case this never surfaces as a disagreement anyway: every
+     * caller that resolves a window here (`resolveWindowSince`) sends the
+     * device *only* the resolved `from`/`to`, never a raw `sinceMs` — the
+     * device's own `sinceMs` handling in `Window.resolve` is exercised by a
+     * request that reaches it directly, not by anything this function
+     * produces.
+     */
+    function resolveWindow(w) {
+        const events = timeline.buffer();
         if (events.length === 0) {
-            const page = await device.request("timeline", {
-                limit: limit ?? 500,
-            });
-            events = page.events;
-        }
-        if (sinceMs !== undefined && events.length > 0) {
-            const newest = events[events.length - 1].t;
-            events = events.filter((event) => event.t >= newest - sinceMs);
-        }
-        if (kinds?.length) {
-            const wanted = new Set(kinds);
-            events = events.filter((event) => wanted.has(event.event));
-        }
-        events = events.slice(-(limit ?? 500));
-        const counts = {};
-        for (const event of events)
-            counts[event.event] = (counts[event.event] ?? 0) + 1;
-        const span = events.length > 1 ? events[events.length - 1].t - events[0].t : 0;
-        const summary = events.length === 0
-            ? "No events buffered yet. Interact with the app and try again."
-            : `${events.length} events over ${span}ms: ` +
-                Object.entries(counts)
-                    .map(([kind, count]) => `${kind} ${count}`)
-                    .join(", ");
-        return ok(summary, { events });
+            // GRA-53: an empty *live* buffer used to mean "no window at all" —
+            // right when the only source was memory. It no longer is: an agent
+            // quoting a `window` from an earlier answer (the pattern every tool
+            // description here recommends) is asking about a moment on the device
+            // uptime clock, which is exactly as answerable from disk after the MCP
+            // server restarts as it was from the ring before. Only the explicit
+            // case is widened — `sinceMs`-relative-to-"now" still has no "now"
+            // without a live buffer to take it from, so that shape still returns
+            // null exactly as before.
+            if (w.from !== undefined && w.to !== undefined) {
+                const from = Math.max(0, w.from);
+                const to = w.to;
+                // Refused the same way the tool already refuses a bad window:
+                // `resolveWindow` returning null, which every caller already treats
+                // as "nothing to answer from" rather than a distinct error path.
+                if (from > to)
+                    return null;
+                return { from, to, ms: Math.max(0, to - from) };
+            }
+            // GRA-120 QA round 1: `sinceMs` with an explicit `to` needs no "now"
+            // at all — the rule is `(to - sinceMs)..to` on both halves — so it is
+            // resolved here even on a cold buffer. Forwarding it raw would let the
+            // device anchor the lookback to its own clock instead, which is the
+            // disagreement this ticket exists to remove. Only `sinceMs` alone (no
+            // `to`) still returns null: that shape genuinely needs a "now", and the
+            // device's is the right one when this host has nothing buffered.
+            if (w.sinceMs !== undefined && w.to !== undefined) {
+                const to = w.to;
+                const from = Math.max(0, to - w.sinceMs);
+                if (from > to)
+                    return null;
+                return { from, to, ms: Math.max(0, to - from) };
+            }
+            return null;
+        }
+        const newest = events[events.length - 1].t;
+        const oldest = events[0].t;
+        const to = w.to ?? newest;
+        const from = Math.max(0, w.from ?? (w.sinceMs !== undefined ? to - w.sinceMs : oldest));
+        if (from > to)
+            return null;
+        return { from, to, ms: Math.max(0, to - from) };
+    }
+    /**
+     * The identity `fillWindowFromDisk` should look up sessions under: the
+     * currently-connected process's `hello`, or — the post-mortem case this
+     * whole ticket is about — the last one `device.ts` saw exit. Null only
+     * when neither has ever existed (never connected, this process's whole
+     * life).
+     */
+    function currentIdentity() {
+        const hello = device.hello ?? device.lastExited?.hello ?? null;
+        if (!hello)
+            return null;
+        return {
+            packageName: hello.packageName,
+            deviceId: hello.deviceId ?? UNKNOWN_DEVICE_ID,
+        };
+    }
+    /**
+     * `findings`/`what_was_happening`/`timeline`'s one shared call into
+     * `sessions.ts` — see that module's `fillWindowFromDisk` doc comment for
+     * why routing all three through the same function is the point, not an
+     * incidental convenience (GRA-163's history is full of what happens when
+     * three tools each hand-roll the same merge).
+     */
+    async function mergeWithDisk(from, to) {
+        return fillWindowFromDisk({
+            root: device.sessions?.root ?? sessionsRootPath(resolveProjectRoot().directory),
+            identity: currentIdentity(),
+            buffered: timeline.buffer(),
+            currentSessionDir: device.sessions?.currentDir() ?? null,
+            from,
+            to,
+        });
     }
-    catch (error) {
-        return fail(error);
+    /** The session directory `watermark` should currently be reading/writing — the same one `mergeWithDisk` already uses, so the two never disagree about which session is "current". */
+    function currentWatermarkDir() {
+        return device.sessions?.currentDir() ?? null;
     }
-});
-server.registerTool("open_timeline", {
-    title: "Open the timeline UI",
-    description: "Starts the local timeline UI and returns its URL. Lanes for recompositions, state writes, " +
-        "navigation, network and database, on a shared time axis. Open it in a browser; it updates " +
-        "live over a WebSocket.",
-    inputSchema: {},
-}, async () => {
-    try {
-        const url = await timeline.start();
-        return ok(`Timeline UI running at ${url}`, { url, events: timeline.buffer().length });
+    /**
+     * Folds `since` into `resolveWindow`, and records `lastExaminedT` on every
+     * resolution — the one chokepoint every window-taking tool (`findings`,
+     * `save_moment`, `recompositions`, `frames`, `blocking`, `logs`,
+     * `timeline`) calls instead of `resolveWindow` directly, so "since: last
+     * updates the watermark" cannot be true for six tools and forgotten by a
+     * seventh.
+     *
+     * Explicit `sinceMs`/`from`/`to` wins outright, exactly as it always has —
+     * `since` only ever supplies a default for when none of those were given.
+     *
+     * `since: "last"` with nothing yet in the watermark behaves exactly like
+     * today's default (AC5): the whole buffer, same as `resolveWindow({})`.
+     * With a watermark and new events since it, the window is `[lastExaminedT,
+     * newest]` — genuinely new material only. With a watermark and *nothing*
+     * new (the AC1 case: two calls back to back with no interaction between
+     * them), there is no new material to narrow to, and narrowing there
+     * anyway would return an empty window whose zero findings would then look
+     * exactly like "everything resolved" — the opposite of AC1's "the second
+     * call marks everything ongoing." So this falls back to re-asking the
+     * exact window the last `findings` call covered (its digest, if there is
+     * one): the same question again, honestly, which is what "nothing
+     * happened" actually means here.
+     */
+    async function resolveWindowSince(w) {
+        await watermark.open(currentWatermarkDir());
+        if (w.sinceMs !== undefined || w.from !== undefined || w.to !== undefined) {
+            const span = resolveWindow(w);
+            if (span)
+                await watermark.recordExamined(span.to);
+            return span ? { ...span, sinceLast: false, firstEver: false, nothingNew: false } : null;
+        }
+        const since = w.since ?? "last";
+        if (since === "all") {
+            await watermark.reset();
+            const span = resolveWindow({});
+            if (span)
+                await watermark.recordExamined(span.to);
+            return span ? { ...span, sinceLast: false, firstEver: false, nothingNew: false } : null;
+        }
+        const state = watermark.get();
+        if (state.lastExaminedT === null) {
+            // AC5: no watermark yet — the whole buffer, exactly as if `since` did
+            // not exist. `firstEver: true` is what lets the caller say so.
+            const span = resolveWindow({});
+            if (span)
+                await watermark.recordExamined(span.to);
+            // AC5's "says so": noted here, once, and consumed by `ok()` for
+            // whichever tool made this call — not narrated per tool, so the six
+            // other window-taking tools cannot each forget it.
+            if (span)
+                pendingFirstEverNote = FIRST_EVER_NOTE;
+            return span ? { ...span, sinceLast: true, firstEver: true, nothingNew: false } : null;
+        }
+        const buffered = timeline.buffer();
+        const liveNewest = buffered.length > 0 ? buffered[buffered.length - 1].t : null;
+        if (liveNewest !== null && liveNewest > state.lastExaminedT) {
+            // Exclusive lower bound: `lastExaminedT` was the `to` of whatever
+            // window was examined last, and every window here (like
+            // `resolveWindow`'s own) treats its bounds as inclusive. Starting the
+            // next one at the same value would re-examine that one boundary event
+            // twice across two consecutive since:"last" windows — harmless for a
+            // raw event count, but exactly the kind of double-count that would
+            // make a finding resting on that single event look "still happening"
+            // one call after it actually stopped.
+            const from = state.lastExaminedT + 1;
+            const span = { from, to: liveNewest, ms: Math.max(0, liveNewest - from) };
+            await watermark.recordExamined(span.to);
+            return { ...span, sinceLast: true, firstEver: false, nothingNew: false };
+        }
+        if (state.digest) {
+            const { from, to } = state.digest.window;
+            return { from, to, ms: Math.max(0, to - from), sinceLast: true, firstEver: false, nothingNew: false };
+        }
+        // GRA-189: nothing new, and nothing to fall back to (a window-taking
+        // tool other than `findings` was the only thing ever called before this
+        // — or, the device case, before an earlier MCP process this one's
+        // watermark.json survived). An honest zero-width window rather than a
+        // guess, and `nothingNew: true` so the caller skips analysing it and
+        // says so plainly instead of reporting "0s examined."
+        return {
+            from: state.lastExaminedT,
+            to: state.lastExaminedT,
+            ms: 0,
+            sinceLast: true,
+            firstEver: false,
+            nothingNew: true,
+        };
     }
-    catch (error) {
-        return fail(error);
+    /**
+     * The banner's actual construction: every error-severity finding produced
+     * by the events between `lastReportedErrorT` (exclusive, so nothing is
+     * ever shown twice) and the newest event this process currently knows
+     * about. Advances `lastReportedErrorT` whenever it looks — including when
+     * it finds nothing to report — so a quiet stretch does not get re-scanned
+     * from the same old boundary on every subsequent call.
+     */
+    async function errorBanner() {
+        const buffered = timeline.buffer();
+        const liveNewest = buffered.length > 0 ? buffered[buffered.length - 1].t : null;
+        const state = watermark.get();
+        if (liveNewest === null) {
+            // Nothing buffered at all yet — there is nothing to report on, and
+            // nothing to seed either (there is no `t` to seed it to). Left null,
+            // so the first call that actually has something buffered is the one
+            // that decides whether it is worth reporting.
+            return { banner: null, sinceLast: null };
+        }
+        if (state.lastReportedErrorT !== null && liveNewest <= state.lastReportedErrorT) {
+            return { banner: null, sinceLast: null };
+        }
+        // `lastReportedErrorT === null` (this process has never reported
+        // anything) is treated as "everything currently buffered counts as
+        // unreported" rather than silently seeding to now — a call whose very
+        // first look at the world finds an error already sitting there should
+        // say so, not swallow it just because no earlier call happened to check
+        // first. `from: 0` reaches back to the start of whatever this process
+        // can see (the live buffer, widened by `mergeWithDisk`'s own disk
+        // fallback), the same "no prior context" floor `resolveWindow`'s own
+        // default uses.
+        const from = state.lastReportedErrorT === null ? 0 : state.lastReportedErrorT + 1;
+        const merged = await mergeWithDisk(from, liveNewest);
+        const events = merged.events;
+        if (events.length === 0) {
+            await watermark.recordReportedErrorT(liveNewest);
+            return { banner: null, sinceLast: null };
+        }
+        const profile = resolveProfile({
+            liveEvents: buffered,
+            windowTo: liveNewest,
+            sessionProfile: device.sessions?.currentMeta()?.profile ?? null,
+            hello: device.hello ?? null,
+        });
+        const trace = buildTrace({
+            scenario: "since-last-banner",
+            events,
+            hello: device.hello ?? null,
+            durationMs: liveNewest - from,
+            withEvents: false,
+            profile,
+        });
+        const errorFindings = trace.findings.filter((f) => f.severity === "error");
+        await watermark.recordReportedErrorT(liveNewest);
+        if (errorFindings.length === 0) {
+            return { banner: null, sinceLast: null };
+        }
+        return {
+            banner: buildBanner(errorFindings),
+            sinceLast: {
+                errors: errorFindings.reduce((sum, f) => sum + (f.count ?? 1), 0),
+                firstAt: events[0].t,
+                lastAt: events[events.length - 1].t,
+            },
+        };
+    }
+    /**
+     * `ok()`'s actual work (see that function's own comment for why it is
+     * split out): opens the watermark for whichever session is current,
+     * builds the banner, prefixes it onto the summary, and attaches the
+     * structured `sinceLast` field to the payload — every payload here is a
+     * plain object, so the spread below always applies.
+     */
+    async function attachSinceLastAndBanner(summary, payload) {
+        await watermark.open(currentWatermarkDir());
+        const { banner, sinceLast } = await errorBanner();
+        const firstEver = pendingFirstEverNote;
+        pendingFirstEverNote = null;
+        const narrated = firstEver ? `${firstEver}${summary}` : summary;
+        const withBanner = banner ? `${banner}\n${narrated}` : narrated;
+        const withSinceLast = payload !== null && typeof payload === "object" && !Array.isArray(payload)
+            ? { ...payload, sinceLast }
+            : payload;
+        return { summary: withBanner, payload: withSinceLast };
+    }
+    // ---------------------------------------------------------------------------
+    // what to do next
+    // ---------------------------------------------------------------------------
+    /**
+     * The tool that shows a finding's evidence.
+     *
+     * Without this a finding is a dead end: it states a conclusion and leaves the
+     * agent to guess which of eleven tools substantiates it. Guessing is where the
+     * wandering starts, so each finding names its own next call.
+     */
+    const FOLLOW_UP = {
+        "db-on-main-thread": { tool: "blocking", why: "the queries, their SQL and how long each took" },
+        "main-thread-stall": { tool: "blocking", why: "the stack the main thread was sitting in" },
+        "http-failed": { tool: "inflight", why: "the failed calls with status and body previews" },
+        "frames-dropped": { tool: "frames", why: "which phase dominated the janky frames" },
+        "blocking-gc": {
+            tool: "timeline",
+            why: 'what allocated around each collection (kinds: ["gc"])',
+        },
+        "trim-memory": {
+            tool: "timeline",
+            why: 'the memory series around the trim (kinds: ["memory"])',
+        },
+        "work-retried": { tool: "inflight", why: "the jobs and their attempt counts" },
+        "recompose-hotspot": {
+            tool: "recompositions",
+            why: "the per-node counts and the state keys written just before",
+        },
+    };
+    function withFollowUp(finding) {
+        const next = FOLLOW_UP[finding.id];
+        return next
+            ? { ...finding, next: { tool: next.tool, window: "quote `window` above", shows: next.why } }
+            : finding;
     }
-});
+    // ---------------------------------------------------------------------------
+    // tools
+    // ---------------------------------------------------------------------------
+    server.registerTool("porthole_status", {
+        title: "Porthole status",
+        description: "Whether the porthole is connected to a running app, which collectors are active, and what to " +
+            "do if it is not. Call this when another tool reports it cannot reach the device.\n\n" +
+            "This tool answers 'is it plugged in', not 'is anything wrong'. For that, call `findings`.\n\n" +
+            "Also carries `exits`: the most recent process deaths Android recorded for this app, so " +
+            "'why did it just die' is answerable on the first call after a crash, not a tool an agent " +
+            "has to know to reach for.",
+        inputSchema: {
+            // GRA-188: `exits.recent` prints both an epoch-milliseconds
+            // `timestamp` and an ISO-8601 `at` for the same instant (device
+            // pass, 2026-09-15 — an agent's obvious next move, quoting the
+            // printed timestamp straight back, used to fail validation whenever
+            // it reached for `at`). Both forms are accepted here now; either
+            // one round-trips with no conversion the caller has to think of.
+            exitTrace: z
+                .union([z.number().int().positive(), z.string()])
+                .optional()
+                .describe("Fetch the full redacted ANR/native-crash trace for one entry in `exits` — pass either " +
+                "that entry's `timestamp` (epoch milliseconds) or its `at` (ISO-8601) verbatim; both " +
+                "are accepted and converted. Capped at 256 KB by the runtime, with a note in the text " +
+                "if it was truncated. Omit this to just see the `exits` summary."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ exitTrace }) => {
+        // GRA-119 AC5: name which SDK and which project root this run resolved
+        // to, and where each came from, so "adb resolved to the wrong SDK" is
+        // something this tool can actually diagnose instead of something an
+        // agent has to take on faith. resolveSdkDir()/resolveProjectRoot() in
+        // adb.ts already compute both; this just reports them.
+        const sdkDir = resolveSdkDir();
+        const projectRoot = resolveProjectRoot();
+        // GRA-157: DeviceClient now has a "handshaking" ConnectionState for the
+        // gap between the socket connecting and hello resolving, so this reads
+        // `device.state` alone — pendingMessage() names the disconnected and
+        // handshaking stories the same way `findings` does (AC3), and returns
+        // null only when state === "connected", which now guarantees `hello`
+        // is set, so the non-null assertion below is the invariant, not a hope.
+        const pending = device.pendingMessage();
+        const bufferedEvents = timeline.buffer().length;
+        // GRA-163: same structured field findings and what_was_happening carry
+        // — null once connected, otherwise the last confirmed process and when
+        // it exited, so an agent reading any of the three tools' JSON alone
+        // sees the same fact. QA round 1: `exitedProcessNotice()` builds the
+        // matching sentence from `bufferedEvents` above, so it can never claim
+        // buffered data this tool is not itself reporting any.
+        const exitedProcess = exitedProcessField();
+        const notice = exitedProcessNotice(exitedProcess, bufferedEvents > 0, pending === null);
+        const exits = exitsSection();
+        const deathNotice = exitDeathNotice(exits.recent, pending === null);
+        // GRA-58: a missing `exitTrace` fails zod validation before the
+        // handler ever runs when it is a negative or non-integer number
+        // (`exitTrace` is `z.union([z.number().int().positive(), z.string()])`);
+        // a numeric shape reaching here may still name a timestamp the
+        // runtime has never heard of, hence the `found` field in what comes
+        // back rather than a thrown error.
+        //
+        // GRA-188: a *string* shape is new — `exits.recent` prints both an
+        // epoch-milliseconds `timestamp` and an ISO-8601 `at` for the same
+        // instant, and an agent quoting either back should work. `Date.parse`
+        // covers `at`'s own format and every other syntax that reasonably
+        // names an instant; a string that parses to nothing (empty, garbage)
+        // is refused right here, with one line, rather than reaching
+        // `device.request` with `NaN`.
+        let exitTraceMs = null;
+        if (typeof exitTrace === "string") {
+            const parsed = Date.parse(exitTrace);
+            if (!Number.isFinite(parsed)) {
+                return fail(`exitTrace: ${JSON.stringify(exitTrace)} is not a valid epoch-milliseconds number or an ` +
+                    "ISO-8601 timestamp.");
+            }
+            exitTraceMs = parsed;
+        }
+        else if (exitTrace !== undefined) {
+            exitTraceMs = exitTrace;
+        }
+        let exitTraceResult = null;
+        if (exitTraceMs !== null) {
+            try {
+                exitTraceResult = await device.request("exit_trace", { timestamp: exitTraceMs });
+            }
+            catch (error) {
+                exitTraceResult = {
+                    timestamp: exitTraceMs,
+                    found: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        const payload = {
+            state: device.state,
+            host: HOST,
+            port: PORT,
+            app: device.hello,
+            timelineUi: timeline.isRunning() ? timeline.url() : null,
+            bufferedEvents,
+            lastError: device.lastError,
+            // GRA-96: null on a healthy handshake, otherwise the same sentence
+            // `summary` uses below — reported in the payload too so a caller
+            // reading structured data (not just the text) can branch on it
+            // without string-matching `summary`.
+            protocolMismatch: device.protocolMismatch,
+            sdkDir: sdkDir.directory,
+            sdkDirSource: sdkDir.source,
+            projectRoot: projectRoot.directory,
+            projectRootSource: projectRoot.source,
+            exitedProcess,
+            exits,
+            exitTrace: exitTraceResult,
+        };
+        // GRA-96: a protocol mismatch takes priority over the normal "here is
+        // what's connected" sentence — hello did land and the socket is fine,
+        // but the one thing worth saying is that the two sides disagree on the
+        // wire format, not the collector list a mismatched build may not even
+        // be able to report honestly. This is what turns AC1's "specific,
+        // actionable message... not a generic failure" into the actual summary
+        // text an agent reads, rather than a field it has to know to check.
+        const summary = notice +
+            deathNotice +
+            (pending ??
+                device.protocolMismatch ??
+                `Connected to ${device.hello.packageName} on ${device.hello.device} ` +
+                    `(API ${device.hello.sdkInt}). Collectors: ${device.hello.collectors.join(", ")}.`);
+        return ok(summary, payload);
+    });
+    server.registerTool("findings", {
+        title: "What is wrong right now",
+        description: "Start here. Everything the porthole can currently say is wrong, ranked, each with how " +
+            "strongly it can be claimed and which tool shows its evidence.\n\n" +
+            "The other tools return measurements and leave the conclusion to you. This one draws the " +
+            "conclusions the data actually supports, which is a shorter list than it looks: queries on " +
+            "the main thread, stalls, failed calls, dropped frames, blocking collections, memory trims, " +
+            "retried jobs, recomposition hotspots.\n\n" +
+            "`confidence` is load-bearing and worth repeating to whoever reads your answer. 'observed' " +
+            "means the device reported it: a query ran on the main thread, a frame missed its deadline. " +
+            "'correlated' means two things happened close together, which is ordering and not " +
+            "causation. Do not upgrade a correlated finding to a cause because it is the only one you " +
+            "have.\n\n" +
+            "`clippedMs` says how much of the window asked for fell outside what is still buffered. " +
+            "Non-zero means part of the question was never examined, which is a different answer from " +
+            "there being nothing there.\n\n" +
+            "An empty list means nothing crossed a threshold in this window. It does not mean the app " +
+            "is fast, and it does not mean the window contained the problem — check `window` against " +
+            "the moment you care about before concluding anything from silence.",
+        inputSchema: windowShape,
+        annotations: { readOnlyHint: true },
+    }, async ({ sinceMs, from, to, since }) => {
+        const span = await resolveWindowSince({ sinceMs, from, to, since });
+        if (!span) {
+            // resolveWindow returns null whenever the ring is empty, which is not
+            // the same thing as the device being unreachable — hello can have
+            // landed seconds ago with nothing collected yet. Printing the full
+            // troubleshooting wall in that case sends the first call after every
+            // install chasing a socket that was never the problem.
+            //
+            // GRA-157: "connected" here is the loose sense porthole_status also
+            // uses — the socket is up, whether or not hello has landed — because
+            // that is the fact an agent deciding whether to keep polling
+            // actually wants. GRA-162: isAttached() replaces the inline
+            // `=== "handshaking" || === "connected"` so a fifth ConnectionState
+            // fails `tsc` here instead of silently reading as not-connected.
+            // GRA-163: this loose sense is safe only because there is no ring
+            // content here to mislabel — an empty ring has nothing to claim is
+            // live. The non-empty branch below asks a stricter question; see its
+            // own comment for why the two cannot share one boolean.
+            const connected = isAttached(device.state);
+            const pending = device.pendingMessage();
+            // GRA-163 QA round 1: called on this branch too now — an empty ring
+            // can still have a `lastExited` behind it (reconnect, hello clears
+            // the ring, then the new process dies before emitting anything),
+            // and `porthole_status` was already reporting that unconditionally
+            // while this branch reported nothing at all, which is the exact
+            // cross-tool disagreement this ticket exists to remove.
+            // `hasBufferedData: false` because this branch is reached only when
+            // the ring is empty — the prose must not claim otherwise.
+            const exitedProcess = exitedProcessField();
+            // `connected: pending === null` (the strict sense) here, not the
+            // loose `connected` above — inert in practice since
+            // `hasBufferedData: false` short-circuits both of
+            // exitedProcessNotice()'s non-exited cases to "", but kept correct
+            // rather than passing whichever local happens to be in scope.
+            const notice = exitedProcessNotice(exitedProcess, false, pending === null);
+            if (pending !== null) {
+                return ok(notice + pending, { window: null, findings: [], connected, exitedProcess });
+            }
+            const summary = `Connected to ${device.hello.packageName}, nothing buffered yet. Ask again in a moment.`;
+            return ok(notice + summary, { window: null, findings: [], connected, exitedProcess });
+        }
+        const buffered = timeline.buffer();
+        // GRA-189: `since: "last"` resolved to a genuinely empty window — the
+        // watermark this call would advance from has nothing newer past it,
+        // and no previous `findings` digest to re-ask (see `nothingNew`'s own
+        // comment on `resolveWindowSince`). Running the analyser over that
+        // reports "0s examined," the least useful possible answer to exactly
+        // the question `since: "last"` exists to shortcut — so this skips the
+        // analysis entirely rather than dressing up an empty result. This is
+        // also the device case: a fresh MCP process that loads a watermark an
+        // earlier process left on disk lands here whenever nothing has
+        // arrived since, and the prose must say "nothing new," not "first
+        // call" — `firstEver` is false, because the watermark was not empty,
+        // it simply has nothing new past it.
+        if (span.nothingNew) {
+            const pending = device.pendingMessage();
+            const connected = pending === null;
+            const exitedProcess = exitedProcessField();
+            const notice = exitedProcessNotice(exitedProcess, buffered.length > 0, connected);
+            return ok(notice +
+                `Nothing new has arrived since the last call, which examined up to t=${span.to}. ` +
+                'Use since: "all", or an explicit window, for the whole picture.', {
+                window: { from: span.from, to: span.to, ms: 0 },
+                eventsExamined: 0,
+                findings: [],
+                connected,
+                exitedProcess,
+            });
+        }
+        // GRA-53: merges the live buffer with whatever sessions on disk
+        // overlap the window, deduplicated and sorted — see
+        // `fillWindowFromDisk`'s own doc comment in sessions.ts. `events` here
+        // used to be the live ring alone; it is now the same merge
+        // `what_was_happening` already uses, so a finding can be produced from
+        // a window that spans an MCP-server restart, not only from whatever
+        // survived in memory.
+        const merged = await mergeWithDisk(span.from, span.to);
+        const events = merged.events;
+        // GRA-163: a non-empty ring is not, on its own, proof the events in it
+        // are from what is running now — the ring only clears on a new hello
+        // (timeline.ts), so anything buffered while state has not reached
+        // "connected" could just as easily be a previous session's leftovers.
+        // `device.pendingMessage()` is the shared decision point GRA-157 built
+        // for exactly this question, and it used to be reachable only from the
+        // empty-ring branch above (`!span`) — the one input where a stale,
+        // still-buffered ring cannot appear at all. Calling it here too is
+        // what makes `connected` strict (true only once hello has actually
+        // landed for the session that is being reported on) instead of the
+        // loose isAttached() sense used above, where handshaking read as
+        // attached even when the ring's contents predated the handshake. That
+        // conflation was the measured bug: 34 hardware samples caught this
+        // tool reporting `connected: true` about a dead process during a later
+        // handshake, because handshaking alone was treated as good enough.
+        const pending = device.pendingMessage();
+        const connected = pending === null;
+        // Structured, not just prose (per the founder-pending assumption this
+        // ticket is built on): null once connected, otherwise the process
+        // `device` last confirmed and when it exited, so an agent can branch
+        // on this without parsing the summary text. `hasBufferedData: true`
+        // because this is the non-empty branch — the ring genuinely has
+        // events, even if the requested window clips around them.
+        const exitedProcess = exitedProcessField();
+        const notice = exitedProcessNotice(exitedProcess, true, connected);
+        // Asking about a moment the ring no longer holds returns nothing, which is
+        // indistinguishable from a moment when nothing happened. They are opposite
+        // answers and only one of them is about the app.
+        const liveOldest = buffered[0]?.t ?? span.from;
+        const liveNewest = buffered[buffered.length - 1]?.t ?? span.to;
+        // GRA-53: `clippedMs` is now a coverage question, answered against
+        // `merged.coveredFrom`/`coveredTo` (live buffer bounds unioned with
+        // every overlapping session's own recorded extent) rather than against
+        // the live buffer's bounds alone — see `fillWindowFromDisk`'s doc
+        // comment on why this must NOT be derived from which events actually
+        // matched: a quiet stretch inside a recorded session must read as
+        // covered, not as clipped, just because nothing happened in it. When
+        // neither the buffer nor any session on disk overlaps the window at
+        // all, `coveredFrom`/`coveredTo` are null and the whole window is
+        // honestly unrecorded.
+        // GRA-54: the same function `save_moment`'s trace carries this exact
+        // number under, so the two cannot drift apart the way two hand-rolled
+        // copies of this formula eventually would (see clippedMsOf's own
+        // comment in sessions.ts).
+        const clipped = clippedMsOf(span.from, span.to, merged.coveredFrom, merged.coveredTo);
+        // GRA-185: searched over the live ring (`buffered`), not `events`
+        // (which is windowed to `span`) — a profile event before `span.from`
+        // must still count. See `resolveProfile`'s own doc comment.
+        const profile = resolveProfile({
+            liveEvents: buffered,
+            windowTo: span.to,
+            sessionProfile: device.sessions?.currentMeta()?.profile ?? null,
+            hello: device.hello ?? null,
+        });
+        const trace = buildTrace({
+            // The same analyser the headless capture runs, pointed at the live
+            // buffer instead of a recorded scenario. One analyser, so a finding
+            // means the same thing in CI as it does in an editor.
+            scenario: "live",
+            events,
+            hello: device.hello ?? null,
+            durationMs: span.ms,
+            withEvents: false,
+            profile,
+        });
+        const findings = trace.findings.map(withFollowUp);
+        // GRA-55: classified against whatever the *previous* findings call
+        // left in the watermark, before this call's own digest overwrites it
+        // — order matters here, `recordDigest` below must come after reading
+        // `previousDigest`, not before.
+        const previousDigest = watermark.get().digest;
+        const classified = classify(findings, previousDigest, span.sinceLast, {
+            from: span.from,
+            to: span.to,
+        });
+        await watermark.recordDigest({
+            findings: trace.findings.map((f) => ({ id: f.id, count: f.count ?? 1 })),
+            window: { from: span.from, to: span.to },
+            sinceLast: span.sinceLast,
+        });
+        const classificationNote = classified.counts
+            ? ` (${classificationSummary(classified.counts)})`
+            : classified.skippedNote
+                ? ` (${classified.skippedNote})`
+                : "";
+        const payload = {
+            window: { from: span.from, to: span.to, ms: span.ms },
+            // The merged (disk + memory) recorded extent, clipped to the window
+            // — distinct from `buffered` below, which stays the live ring's own
+            // account of itself.
+            examined: { from: merged.coveredFrom ?? span.from, to: merged.coveredTo ?? span.from },
+            buffered: { from: liveOldest, to: liveNewest, events: buffered.length },
+            clippedMs: clipped,
+            eventsExamined: events.length,
+            metrics: trace.metrics,
+            // Classified findings (new/ongoing/resolved, per `classify()`'s own
+            // comment on when that runs) rather than the plain list — `resolved`
+            // entries can make this longer than `findings.length` below, which
+            // stays keyed on what is *currently* true, not on what changed.
+            findings: classified.findings,
+            connected,
+            exitedProcess,
+        };
+        const shortfall = clipped.start + clipped.end;
+        const missing = shortfall > 0
+            ? ` ${Math.round(shortfall / 100) / 10}s of the window asked for is older or newer than ` +
+                "anything buffered, so it was not examined at all."
+            : "";
+        if (findings.length === 0) {
+            return ok(notice +
+                (shortfall > span.ms * 0.5
+                    ? `Almost none of that window is in the buffer${missing} This is not a quiet app; ` +
+                        "it is a question the buffer cannot answer."
+                    : `Nothing crossed a threshold in the ${Math.round(span.ms / 1000)}s examined ` +
+                        `(${events.length} events). That is not the same as the app being fast.${missing}`) +
+                classificationNote, payload);
+        }
+        const worst = trace.findings[0];
+        const bySeverity = trace.findings.reduce((acc, f) => {
+            acc[f.severity] = (acc[f.severity] ?? 0) + 1;
+            return acc;
+        }, {});
+        const tally = Object.entries(bySeverity)
+            .map(([severity, n]) => `${n} ${severity}`)
+            .join(", ");
+        return ok(notice +
+            `${findings.length} finding(s) over ${Math.round(span.ms / 1000)}s (${tally}). ` +
+            `Worst: ${worst.title} [${worst.confidence}].${missing}${classificationNote}`, payload);
+    });
+    server.registerTool("system_context", {
+        title: "What the rest of the device was doing",
+        description: "Thermal state, CPU governor and clock, the busiest processes, and system memory pressure. " +
+            "Read straight off the device over adb.\n\n" +
+            "This is the half Porthole cannot see. It watches one process, so when `blocking` reports a " +
+            "stall whose stack bottoms out in a native read, or `frames` blames swapBuffers, the reason " +
+            "is usually below the app and none of the other tools can reach it. A throttled device, a " +
+            "governor holding the cores down, or another process eating the CPU explains a regression " +
+            "that no code change accounts for.\n\n" +
+            "Reports only what it read. Values are current, not historical — this says what is true now, " +
+            "not what was true during a window you are investigating, so take it while the problem is " +
+            "happening. Sources it could not parse are listed in `unavailable` rather than omitted, " +
+            "because a missing thermal reading and a cool device are not the same thing.\n\n" +
+            "It draws no conclusions. Two cores below maximum is a fact; that it is why your app is " +
+            "slow is a guess, and this tool does not know what your app was doing.",
+        inputSchema: {
+            serial: z
+                .string()
+                .optional()
+                .describe("Device serial, when more than one is attached. `adb devices` lists them."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ serial }) => {
+        const unavailable = [];
+        const read = (source, args) => {
+            const result = runAdb(args, serial);
+            if (!result.ok) {
+                unavailable.push({ source, reason: result.output.split("\n")[0].slice(0, 160) });
+                return null;
+            }
+            return result.output;
+        };
+        const thermalOut = read("thermalservice", ["shell", "dumpsys", "thermalservice"]);
+        const cpuOut = read("cpufreq", ["shell", CPU_PROBE]);
+        const topOut = read("cpuinfo", ["shell", "dumpsys", "cpuinfo"]);
+        const memOut = read("meminfo", ["shell", "dumpsys", "meminfo"]);
+        const context = {
+            thermal: thermalOut === null ? null : parseThermal(thermalOut),
+            cpu: cpuOut === null ? null : parseCpu(cpuOut),
+            top: topOut === null ? [] : parseTop(topOut),
+            memory: memOut === null ? null : parseMemory(memOut),
+            unavailable,
+        };
+        return ok(describeSystem(context), context);
+    });
+    server.registerTool("ask_system_trace", {
+        title: "Ask a system trace about a window",
+        description: "Runs a fixed set of questions against a recorded trace, scoped to one window and one " +
+            "process, and returns findings in the same vocabulary as everything else here.\n\n" +
+            "It performs, without a person, the steps someone otherwise does by hand in a trace " +
+            "viewer: find the moment worth looking at, drag out the window, pick the app out of the " +
+            "process list, and export. Porthole already holds all four — the window comes from a " +
+            "finding, the package from the handshake with the device — which is the only reason this " +
+            "can be automated at all.\n\n" +
+            "What it is for is ruling causes out. `findings` can say a frame was late and that " +
+            "composition dominated it. It cannot say whether the device was starving the app of CPU, " +
+            "blocking it on I/O, or compiling its own bytecode in the background. Answering no to " +
+            "each of those is what turns a suspicion into a conclusion, and answering yes to one " +
+            "means the app's own work was never the whole story.\n\n" +
+            "Deliberately not a SQL interface. The questions are fixed, because an agent handed a " +
+            "hundred tables and no guidance assembles an answer from whichever guess came back " +
+            "non-empty — which is the failure this whole surface was reshaped to avoid.\n\n" +
+            "Needs `trace_processor_shell`, which is not bundled — it is a large platform-specific " +
+            "binary — but is fetched on request: `./gradlew portholeTraceProcessor` downloads the " +
+            "pinned release, checks its SHA-256 and caches it where this tool looks.",
+        inputSchema: {
+            trace: z.string().describe("Path to a .pftrace, as returned by capture_system_trace."),
+            from: z
+                .number()
+                .int()
+                .optional()
+                .describe("Window start on the device uptime clock. Quote a finding's `window`."),
+            to: z.number().int().optional().describe("Window end, same clock."),
+            packageName: z
+                .string()
+                .optional()
+                .describe("Defaults to the app the porthole is attached to."),
+            traceProcessor: z.string().optional().describe("Path to trace_processor_shell."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ trace, from, to, packageName, traceProcessor }) => {
+        // GRA-157: connection state checked before the trace_processor lookup,
+        // not after. A device still mid-handshake is not the caller's fault and
+        // not fixed by anything on this machine, so naming that first means a
+        // caller who has not connected yet is never told to go install a
+        // binary when the real, more immediate blocker is the device.
+        const app = packageName ?? device.hello?.packageName;
+        if (!app) {
+            // "Connect to the app" was printed even while the socket was already
+            // connected and just waiting on hello — telling someone to do a
+            // thing that is already in progress. Naming the handshake instead of
+            // the generic advice is the whole fix; the advice itself (pass
+            // `packageName`) still applies either way.
+            // GRA-162: isHandshaking() instead of `=== "handshaking"` — same
+            // exhaustiveness argument as isAttached() above.
+            const because = isHandshaking(device.state)
+                ? "the app is still waiting on its first check-in — try again in a moment, "
+                : "connect to the app, ";
+            return fail(`No package to scope to: ${because}or pass \`packageName\` — without it the questions ` +
+                "answer for the whole device, which is a different question.");
+        }
+        const binary = traceProcessor ?? process.env.PORTHOLE_TRACE_PROCESSOR ?? findTraceProcessor();
+        if (!binary) {
+            return fail("No trace_processor_shell found. Run `./gradlew portholeTraceProcessor` in the app's " +
+                "project: it downloads the pinned Perfetto release, verifies its checksum and caches " +
+                "it where this tool looks, so nothing further needs configuring. An existing copy " +
+                "works too — set PORTHOLE_TRACE_PROCESSOR or pass `traceProcessor`. Either way the " +
+                "trace itself is already readable at ui.perfetto.dev.");
+        }
+        // The window arrives in Porthole's clock and the trace is stamped in the
+        // boot clock, so it has to be converted before it means anything here.
+        const events = timeline.buffer();
+        const span = resolveWindow({ from, to });
+        if (!span) {
+            // GRA-154 (absorbed into GRA-157 AC7): this used to say "Nothing
+            // buffered" unconditionally — a third, different vocabulary from
+            // findings/what_was_happening for the identical empty-ring
+            // condition. pendingMessage() brings the wording in line with
+            // theirs. This one stays an error result rather than switching to
+            // `ok` like the other two: there is genuinely no window here to ask
+            // trace_processor about, nothing partial to return the way an empty
+            // findings list or a "nothing happened here" moment still can.
+            const pending = device.pendingMessage();
+            return fail(pending ??
+                "Connected, but nothing buffered yet, so there is no window to scope the trace to. " +
+                    "Ask again in a moment.");
+        }
+        // GRA-113: the one conversion, through moment.ts's toBoot — this used
+        // to read whichever `clocks` sample `events.find()` happened to
+        // return first and apply it to both bounds, the same open-coded bug
+        // that ticket fixed in timeline.ts. toBoot picks the sample actually
+        // in force at each boundary separately (so a sleep that happened
+        // between `from` and `to` is reflected correctly instead of averaged
+        // away), and hands back the offset it used so this tool can still
+        // report `sleepMs` the way its payload always has.
+        const bootFrom = toBoot(events, span.from);
+        const bootTo = toBoot(events, span.to);
+        const { findings: traceFindings, unanswered } = await askTrace({
+            binary,
+            trace,
+            packageName: app,
+            fromNs: bootFrom.ns,
+            toNs: bootTo.ns,
+        });
+        const findings = traceFindings.map(withFollowUp);
+        const payload = {
+            trace,
+            app,
+            // bootTo's offset, not bootFrom's: if the device slept between the
+            // two, the more recent sample is the more representative one to
+            // report.
+            window: { from: span.from, to: span.to, sleepMs: bootTo.sleepMs },
+            asked: QUESTIONS.map((q) => q.asks),
+            unanswered,
+            findings,
+        };
+        const failures = unanswered;
+        const summary = findings.length
+            ? `${findings.length} finding(s) from the trace. ${findings[0].title}.`
+            : "The trace had nothing to add about that window.";
+        return ok(summary + (failures.length ? ` ${failures.length} question(s) failed.` : ""), payload);
+    });
+    server.registerTool("capture_system_trace", {
+        title: "Record a Perfetto trace",
+        description: "Records a system trace on the device, pulls it to disk, and returns the path. Does not " +
+            "return the trace itself: a ten-second capture is tens of megabytes of protobuf, and it is " +
+            "not something to read — it is something to open.\n\n" +
+            "The reason to take one here rather than by hand is that the app's own spans are already " +
+            "inside it. The runtime writes navigations, HTTP calls, queries and main-thread stalls as " +
+            "atrace sections, so the capture arrives annotated with what the app was doing and not only " +
+            "what the kernel was doing. The result says how many Porthole labels it found, which is how " +
+            "you know the annotation actually happened.\n\n" +
+            "Use it when Porthole has found something it cannot explain — a stall whose stack bottoms " +
+            "out below the app, or jank blamed on swapBuffers — and you need to see what the rest of " +
+            "the system was doing at that moment. `findings` gives you the window worth looking at; " +
+            "this gives you the depth at it.\n\n" +
+            "`restartApp` force-stops and relaunches the target app right after the capture starts — " +
+            "needed on builds that only read the app trace tag at process start (seen on a Pixel 9 " +
+            "Pro Fold, Android 17), where an already-running process's own sections would otherwise " +
+            "be silently missing, at the cost of the trace containing a cold start.\n\n" +
+            "Blocks for the requested duration. Reproduce the problem while it runs.",
+        inputSchema: {
+            seconds: z
+                .number()
+                .int()
+                .positive()
+                .max(120)
+                .optional()
+                .describe("How long to record. Default 10."),
+            categories: z
+                .array(z.string())
+                .optional()
+                .describe("atrace categories. Defaults to a set aimed at jank. `app` is always included, " +
+                "since without it none of Porthole's own sections are recorded."),
+            outputDir: z
+                .string()
+                .optional()
+                .describe("Where to write it. Defaults to .porthole/traces under the working directory."),
+            packages: z
+                .array(z.string())
+                .optional()
+                .describe("Packages whose app-tag sections to record. Defaults to the app the porthole is " +
+                "attached to. Without one, the trace has no Porthole slices in it."),
+            serial: z.string().optional().describe("Device serial, when more than one is attached."),
+            restartApp: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Force-stop and relaunch the target app right after the capture starts, since on " +
+                "builds that only read the app trace tag at process start (seen on a Pixel 9 Pro " +
+                "Fold, Android 17) an already-running process's own sections never appear — the " +
+                "trade-off is a cold start inside the trace. The package is the first entry of " +
+                "`packages`, or the attached app when `packages` is omitted. Default false."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ seconds, categories, outputDir, packages, serial, restartApp }) => {
+        // GRA-157: `device.hello ? [...] : []` used to fall through to an
+        // unscoped capture — silently, with nothing in the result saying so —
+        // whenever this landed in the handshake window, since state was
+        // already "connected" there under the old model. An unscoped capture
+        // has none of Porthole's own slices in it, which defeats the point of
+        // this tool, so when we can name the actual reason (a hello is
+        // genuinely on its way) this fails and says so instead of guessing.
+        // Fully disconnected keeps the old permissive behaviour: apps: []
+        // captures the whole device, same as always.
+        // GRA-162: isHandshaking() instead of `=== "handshaking"`.
+        if (!packages?.length && isHandshaking(device.state)) {
+            return fail("Still waiting on the app's first check-in, so there is no package to scope this " +
+                "capture to yet. Try again in a moment, or pass `packages` explicitly to capture " +
+                "unscoped right now.");
+        }
+        // Default to whatever app the porthole is attached to: that is the one
+        // whose sections are worth recording, and asking for it again is friction.
+        const apps = packages?.length ? packages : device.hello ? [device.hello.packageName] : [];
+        const plan = planCapture({ seconds, categories, apps });
+        const adbCallOptions = { serial, env: adbEnv, binary: adbBinary };
+        // GRA-89: async, awaited spawn for all three adb calls below, not
+        // `runAdb`'s `spawnSync` — that used to freeze the whole MCP server
+        // for the entire recording (up to two minutes at this tool's own
+        // 120s maximum): nothing read the device socket, nothing answered
+        // another tool call, and the timeline WebSocket went silent for as
+        // long as each call took. The recording gets its own, longer timeout
+        // (the plan's own duration plus room for adb's own startup and
+        // teardown) rather than `runAdbAsync`'s short default, which exists
+        // for calls — the pull, the cleanup — that are supposed to be quick.
+        //
+        // GRA-186: not awaited here any more. `restartApp: true` has to act
+        // *during* this recording, not after it — awaiting first would mean
+        // "restarting" only once the whole window is already over, which is
+        // the exact bug this option exists to work around.
+        const recordingPromise = runAdbAsync(captureArgs(plan), {
+            ...adbCallOptions,
+            timeoutMs: plan.seconds * 1000 + CAPTURE_ADB_TIMEOUT_BUFFER_MS,
+            onProgress: (elapsedMs) => process.stderr.write(`[porthole] capture_system_trace: recording, ${Math.round(elapsedMs / 1000)}s of ` +
+                `${plan.seconds}s elapsed...\n`),
+        });
+        // GRA-186: on a build that only reads ATRACE_TAG_APP at process
+        // attach (Pixel 9 Pro Fold, Android 17), a process already running
+        // when the session starts never picks the tag up — a process that
+        // (re)starts after the session has begun does. Restarting here, once
+        // `waitForCaptureToStart` has the best available signal that the
+        // session is live, is the fix; see systrace.ts's zero-label sentence
+        // for the diagnosis this is a remedy for.
+        let restarted = false;
+        const restartNotes = [];
+        if (restartApp) {
+            const target = apps[0];
+            if (!target) {
+                restartNotes.push("Could not restart the app for this capture: no package is attached or named, so " +
+                    "there is nothing to restart.");
+            }
+            else {
+                await waitForCaptureToStart(plan.devicePath, adbCallOptions);
+                const restartResult = await restartAppAsync(target, adbCallOptions);
+                restarted = restartResult.ok;
+                if (!restartResult.ok) {
+                    restartNotes.push(`Could not restart ${target} for this capture: ${restartResult.output}`);
+                }
+            }
+        }
+        const recorded = await recordingPromise;
+        if (!recorded.ok) {
+            return fail(`Could not record: ${recorded.output}\n` +
+                "On-device Perfetto needs Android 9 or newer, and the traced service must be running.");
+        }
+        // Default under .porthole/, which the project's gitignore already covers —
+        // a multi-megabyte trace should not be a candidate for committing.
+        const dir = resolve(outputDir ?? join(process.cwd(), ".porthole", "traces"));
+        mkdirSync(dir, { recursive: true });
+        const local = join(dir, plan.devicePath.split("/").pop());
+        const pulled = await runAdbAsync(["pull", plan.devicePath, local], adbCallOptions);
+        // Tidy up regardless: the device's trace directory is not ours to fill.
+        await runAdbAsync(["shell", "rm", "-f", plan.devicePath], adbCallOptions);
+        if (!pulled.ok)
+            return fail(`Recorded, but could not pull it: ${pulled.output}`);
+        const bytes = statSync(local).size;
+        const result = {
+            path: local,
+            bytes,
+            seconds: plan.seconds,
+            categories: plan.categories,
+            apps: plan.apps,
+            restarted,
+            // GRA-89: streamed in chunks by countPortholeLabels itself now, not
+            // a whole-file readFileSync handed to it — see systrace.ts.
+            portholeLabels: await countPortholeLabels(local),
+            notes: [...plan.notes, ...restartNotes],
+        };
+        return ok(describeCapture(result), result);
+    });
+    server.registerTool("save_moment", {
+        title: "Save what just happened",
+        description: "Turns a window of what already happened into a named trace file on disk, in exactly the " +
+            "format `capture` writes — `porthole report` and `porthole compare` work on it with no " +
+            "changes. For when the developer pokes the app, something bad happens, and only then wants " +
+            "to keep it: no need to reproduce it again with a recording running.\n\n" +
+            "Give it a window the way every other windowed tool takes one — `sinceMs`, or `from`/`to` " +
+            "quoted from a `findings` result — plus an optional `scenario` name. `scenario` defaults to " +
+            "`moment-<from>-<to>` on the uptime clock when omitted, and `out` defaults to " +
+            "`.porthole/traces/<scenario>.json`, the same directory `capture_system_trace` uses.\n\n" +
+            "The events come from the same merged live-buffer-plus-disk view `findings` and " +
+            "`what_was_happening` already use, so a save over a window quoted from a `findings` result " +
+            "produces the same findings `findings` reported for it. `clippedMs` in the result says how " +
+            "much of the requested window was never actually recorded — a window reaching before the " +
+            "session started reports that honestly rather than silently writing a shorter trace.",
+        inputSchema: {
+            ...windowShape,
+            scenario: z
+                .string()
+                .optional()
+                .describe("What to call this. Defaults to moment-<from>-<to> on the uptime clock."),
+            out: z
+                .string()
+                .optional()
+                .describe("Where to write the trace. Defaults to .porthole/traces/<scenario>.json."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ sinceMs, from, to, since, scenario, out }) => {
+        const span = await resolveWindowSince({ sinceMs, from, to, since });
+        if (!span) {
+            // Same shape as ask_system_trace's empty-ring refusal: there is
+            // genuinely no window to save here, nothing partial to write.
+            return fail("No window to save: nothing is buffered live and no absolute `from`/`to` was given. " +
+                "Quote a `window` from an earlier `findings` result, or pass `from`/`to` directly.");
+        }
+        const merged = await mergeWithDisk(span.from, span.to);
+        const events = merged.events;
+        // Post-mortem is the whole point of this tool, so `device.hello` alone
+        // is not enough — the app may well have exited since the moment being
+        // saved. Falls back to the last confirmed process's own hello, the
+        // same source `currentIdentity()` already trusts for exactly this.
+        const helloLike = device.hello ?? device.lastExited?.hello ?? null;
+        const hello = helloLike ?? null;
+        let resolvedScenario;
+        let outPath;
+        try {
+            resolvedScenario = scenario === undefined ? defaultScenarioName(span.from, span.to) : validateScenario(scenario);
+            outPath = out ?? defaultOutPath(resolveProjectRoot().directory, resolvedScenario);
+        }
+        catch (error) {
+            if (error instanceof InvalidScenarioError)
+                return fail(`save_moment: ${error.message}`);
+            throw error;
+        }
+        // GRA-185: same resolution `findings` uses — searched over the live
+        // ring, not `events` (windowed to `span`), so a profile before
+        // `span.from` still counts.
+        const profile = resolveProfile({
+            liveEvents: timeline.buffer(),
+            windowTo: span.to,
+            sessionProfile: device.sessions?.currentMeta()?.profile ?? null,
+            hello,
+        });
+        const trace = buildSavedTrace({
+            events,
+            hello,
+            window: { from: span.from, to: span.to },
+            coveredFrom: merged.coveredFrom,
+            coveredTo: merged.coveredTo,
+            scenario: resolvedScenario,
+            profile,
+        });
+        await writeSavedTrace(trace, outPath);
+        const findings = trace.findings.map(withFollowUp);
+        return ok(`Saved "${resolvedScenario}" (${trace.findings.length} finding(s)) to ${outPath}.` +
+            coverageNote(trace.clippedMs), {
+            scenario: resolvedScenario,
+            out: outPath,
+            window: { from: span.from, to: span.to, ms: span.ms },
+            clippedMs: trace.clippedMs,
+            metrics: trace.metrics,
+            findings,
+        });
+    });
+    server.registerTool("what_was_happening", {
+        title: "What was happening at a moment",
+        description: "The narrative for one instant: which screen, with what arguments, what was in flight, what " +
+            "the main thread was doing, and what state had just been written.\n\n" +
+            "Built for the question a system trace cannot answer. Perfetto will tell you which threads " +
+            "ran at 00:42.318 and for how long; it has no idea that you had just opened the cart, that " +
+            "a checkout call had been open for 600ms, or that the query blocking the frame was on the " +
+            "main thread. Paste the timestamp here and get the part Perfetto is missing.\n\n" +
+            "Give it `at` in the device uptime clock every Porthole event carries, or `bootMs` for a " +
+            "CLOCK_BOOTTIME reading taken from a Perfetto trace — the two differ by however long the " +
+            "device has been in deep sleep, and the conversion uses the clock sample in force at that " +
+            "moment rather than the newest one.\n\n" +
+            "Durations are as they were then, not as they turned out. A call open for 600ms at the " +
+            "moment asked about reports 600ms even if it ran for four seconds, because the question is " +
+            "what was true then. A span that never finished says so.\n\n" +
+            "Bounded by what the timeline server still holds. A moment older than the buffer cannot be " +
+            "answered and will say so rather than return an empty one, which would read as 'nothing " +
+            "was happening'.",
+        inputSchema: {
+            at: z
+                .number()
+                .int()
+                .optional()
+                .describe("The moment, in the device uptime clock. Omit if giving `bootMs`."),
+            bootMs: z
+                .number()
+                .int()
+                .optional()
+                .describe("The moment as CLOCK_BOOTTIME milliseconds, which is what a Perfetto trace stamps with."),
+            spreadMs: z
+                .number()
+                .int()
+                .positive()
+                .max(60_000)
+                .optional()
+                .describe("How far either side to look for context. Default 2000."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ at, bootMs, spreadMs }) => {
+        const events = timeline.buffer();
+        if (events.length === 0) {
+            // GRA-154, absorbed into GRA-157 as AC7: an empty ring is not the
+            // same as a disconnected device — hello can have landed seconds ago
+            // with nothing collected yet, and printing the "Not connected" wall
+            // in that case blames the connection for a buffer that is merely
+            // young. Same distinction `findings` and `porthole_status` make,
+            // through the same method, so all three tell the same story about
+            // an empty-but-attached device instead of each guessing separately.
+            //
+            // GRA-166 item 3 / GRA-163: `connected` is the loose sense (mirrors
+            // findings' own empty-ring arm — handshaking counts as attached,
+            // not just connected). Safe here for the same reason it is safe
+            // there: an empty ring has no content to mislabel. The non-empty
+            // branch below asks the strict question instead.
+            const connected = isAttached(device.state);
+            const pending = device.pendingMessage();
+            // GRA-163 QA round 1: same fix as findings' empty-ring arm — an
+            // empty ring can still have a `lastExited` behind it, and
+            // `porthole_status` was already reporting that unconditionally
+            // while this branch reported nothing, the same cross-tool
+            // disagreement. `hasBufferedData: false`: this branch is reached
+            // only when the ring is empty.
+            const exitedProcess = exitedProcessField();
+            // Inert in practice (see findings' identical comment above) but the
+            // strict sense, correctly, not whichever local is in scope.
+            const notice = exitedProcessNotice(exitedProcess, false, pending === null);
+            // GRA-53: this is AC1's exact shape — the MCP server was just
+            // (re)started, so the live ring is empty by construction, but the
+            // moment being asked about may still be sitting on disk from before
+            // the restart. Tried before falling back to either "not connected"
+            // or "nothing buffered yet", since a real answer beats both.
+            if (at !== undefined) {
+                const merged = await mergeWithDisk(0, at + (spreadMs ?? 2_000));
+                if (merged.coveredFrom !== null && merged.coveredTo !== null && at >= merged.coveredFrom && at <= merged.coveredTo) {
+                    const moment = { ...momentOf(merged.events, at, spreadMs ?? 2_000), clock: null };
+                    return ok(notice + describeMoment(moment), { ...moment, connected, exitedProcess });
+                }
+            }
+            if (pending !== null) {
+                return ok(notice + pending, { moment: null, connected, exitedProcess });
+            }
+            return ok(notice +
+                `Connected to ${device.hello.packageName}, nothing buffered yet. Ask again in a moment.`, { moment: null, connected, exitedProcess });
+        }
+        // GRA-163: from here on the ring has content, so — exactly as in
+        // findings — the ring's contents are only guaranteed to belong to the
+        // running process once its hello has actually landed. Consulting
+        // pendingMessage() here (previously unreached from this branch) is
+        // what stops this tool from agreeing with findings' old bug: reporting
+        // `connected: true` for a moment that was really a previous session's,
+        // just because the socket happened to be handshaking again by the
+        // time someone asked.
+        const pending = device.pendingMessage();
+        const connected = pending === null;
+        const exitedProcess = exitedProcessField();
+        let moment_at = at;
+        let clock = null;
+        if (moment_at === undefined && bootMs !== undefined) {
+            const converted = fromBootMs(events, bootMs);
+            if (!converted) {
+                return ok("No clock sample in the buffer, so a boot-clock timestamp cannot be placed. " +
+                    "The app must have been running with Porthole attached for that to exist.", { moment: null, bootMs, connected, exitedProcess });
+            }
+            moment_at = converted.at;
+            // Keep the boot reading that was asked about, so the answer shows both
+            // ends of the conversion rather than only the result.
+            clock = { bootMs, sleepMs: converted.sleepMs, sampledAt: converted.sampledAt };
+        }
+        if (moment_at === undefined) {
+            return ok("Give either `at` or `bootMs`.", { moment: null, connected, exitedProcess });
+        }
+        // The same shared sentence findings uses, so an agent reading both
+        // tools about the same stale window sees the same story — not two
+        // hand-written near-duplicates that can drift apart from each other.
+        // `hasBufferedData: true`: this is the non-empty branch.
+        const notice = exitedProcessNotice(exitedProcess, true, connected);
+        // Outside the buffer is a different answer from "nothing happened", and
+        // conflating them is how an agent concludes the app was idle.
+        const oldest = events[0].t;
+        const newest = events[events.length - 1].t;
+        if (moment_at < oldest || moment_at > newest) {
+            // GRA-53: the ticket's headline scenario — the buffer rolled or the
+            // process restarted since, but the moment may still be on disk.
+            // `from: 0` rather than `oldest`: momentOf() needs the full nav
+            // history up to `moment_at` to say which screen was current (the
+            // last nav at-or-before the moment, not merely one inside the
+            // spread window), so the merge has to reach back further than the
+            // window actually returned.
+            const merged = await mergeWithDisk(0, moment_at + (spreadMs ?? 2_000));
+            if (merged.coveredFrom !== null &&
+                merged.coveredTo !== null &&
+                moment_at >= merged.coveredFrom &&
+                moment_at <= merged.coveredTo) {
+                const moment = { ...momentOf(merged.events, moment_at, spreadMs ?? 2_000), clock };
+                return ok(notice + describeMoment(moment), { ...moment, connected, exitedProcess });
+            }
+            return ok(notice +
+                `That moment is outside what is buffered (${oldest}–${newest} on the uptime clock). ` +
+                "Not that nothing was happening — it is no longer held.", {
+                moment: null,
+                asked: moment_at,
+                buffered: { from: oldest, to: newest },
+                clock,
+                connected,
+                exitedProcess,
+            });
+        }
+        const moment = { ...momentOf(events, moment_at, spreadMs ?? 2_000), clock };
+        return ok(notice + describeMoment(moment), { ...moment, connected, exitedProcess });
+    });
+    server.registerTool("recompositions", {
+        title: "Recomposition counts",
+        description: "How many times each instrumented composable recomposed, and which state keys were written " +
+            "just before each recomposition. Use it to find the composable doing needless work and the " +
+            "state that keeps invalidating it.\n\n" +
+            "Two limits worth holding in mind: only call sites wrapped in PortholeScreen or " +
+            "Modifier.portholeNode are counted, so an absent composable is uninstrumented rather than " +
+            "idle; and triggeredBy is a temporal correlation within a ~32ms window, not a causal read " +
+            "of the invalidation graph, so several states changing in one frame all get listed.\n\n" +
+            "Keys like 'unnamed#3f2a1c' are state objects nobody named. In a Compose app most of them " +
+            "belong to the framework — ripples, scroll offsets, focus, animation clocks — and are not " +
+            "worth chasing. A key that is yours and still unnamed means its owner was never registered: " +
+            "Porthole.registerViewModel for a ViewModel, collectAsNamedState for a Flow, " +
+            "rememberNamedState for state a composable creates for itself.\n\n" +
+            "A key carrying 'holds' is anonymous state that was found holding one of the app's own " +
+            "types, so it is definitely the app's and definitely unregistered — that one is worth " +
+            "chasing. Its absence proves nothing: an unregistered Int is indistinguishable from a " +
+            "ripple, so most of the app's own unnamed state will not be flagged.",
+        inputSchema: {
+            screen: z
+                .string()
+                .optional()
+                .describe("Only nodes on this screen, matched against the enclosing PortholeScreen name."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Busiest N nodes. Default 50; the tail is rarely what you are looking for."),
+            ...windowShape,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ screen, sinceMs, from, to, limit, since }) => {
+        // GRA-55: resolved here, on the MCP side, rather than forwarding
+        // sinceMs/since to the device — `since: "last"` needs the watermark,
+        // which only this process holds. Falls back to the caller's own raw
+        // sinceMs/from/to, unchanged, when nothing can be resolved (an empty
+        // buffer, no watermark yet) — exactly today's behaviour for that case.
+        const resolved = await resolveWindowSince({ sinceMs, from, to, since });
+        const windowArgs = resolved ? { from: resolved.from, to: resolved.to } : { sinceMs, from, to };
+        return call("recompositions", { screen, ...windowArgs, limit: limit ?? 50 }, (report) => {
+            if (report.nodes.length === 0) {
+                return "No instrumented composable recomposed in that window.";
+            }
+            const top = report.nodes[0];
+            const cause = top.triggeredBy[0];
+            const total = report.nodes.reduce((sum, node) => sum + node.count, 0);
+            // A capped list that does not say it is capped reads as the whole
+            // truth, which is how "only three composables recomposed" gets believed.
+            const cut = report.truncated
+                ? ` Busiest ${report.nodes.length} of ${report.totalNodes ?? report.nodes.length} nodes shown.`
+                : "";
+            return (`${total} recompositions across ${report.nodes.length} nodes. ` +
+                `Worst: ${top.name} at ${top.count}` +
+                (cause ? `, most often after a write to ${cause.key} (${cause.count} of them).` : ".") +
+                cut);
+        });
+    });
+    server.registerTool("semantics_tree", {
+        title: "Semantics tree",
+        description: "The Compose semantics tree with a stable id per node. stableId is a structural path hash: " +
+            "the same UI produces the same id across captures and across process restarts, so two " +
+            "captures can be diffed. Nodes carrying a porthole node id line up with the ids in the " +
+            "recompositions report.\n\n" +
+            "A snapshot of what is on screen now. It says nothing about cost — a large tree is not a slow one — so do not infer performance from its shape; use `frames` for that.",
+        inputSchema: {
+            merged: z
+                .boolean()
+                .optional()
+                .describe("Merged tree (what accessibility services see). Default true."),
+            maxDepth: z.number().int().positive().optional().describe("Depth cap. Default 40."),
+            maxNodes: z.number().int().positive().optional().describe("Node budget. Default 1500."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ merged, maxDepth, maxNodes }) => call("semantics_tree", { merged, maxDepth, maxNodes }, (tree) => tree.error ? tree.error : tree.root ? "Captured the semantics tree." : "Empty tree."));
+    server.registerTool("nav_state", {
+        title: "Navigation state",
+        description: "The current back stack with each entry's route, arguments and lifecycle state, plus the " +
+            "deep link that opened the app if there was one. Answers 'how did I get to this screen' " +
+            "and 'what arguments is it actually holding', which is usually where the bug is.\n\n" +
+            'Present tense only. This is the stack as it is now, not how it got that way — for the order things happened in, ask `timeline` with kinds: ["nav"].',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => call("nav_state", {}, (nav) => nav.error ??
+        `At ${nav.current?.route ?? "an unnamed destination"} with ${nav.backStack.length} entries on the stack.`));
+    server.registerTool("state", {
+        title: "ViewModel state",
+        description: "Current values of the state held by registered ViewModels. Each field says whether writes " +
+            "to it are attributable — meaning snapshot state the recomposition report can name. A " +
+            "StateFlow is never attributable on its own; collectAsNamedState is what makes the State " +
+            "it produces nameable.\n\n" +
+            "Only registered owners appear. An empty result means nothing was registered, not that the app holds no state, so do not read absence here as evidence about the app.",
+        inputSchema: {
+            viewModel: z
+                .string()
+                .optional()
+                .describe("Registered name or class name. Omit for every registered owner."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ viewModel }) => call("state", { viewModel }, (dump) => {
+        if (dump.owners.length === 0) {
+            return 'No ViewModels registered. Call Porthole.registerViewModel("CartViewModel", vm) where you obtain it.';
+        }
+        return dump.owners
+            .map((owner) => `${owner.name} (${owner.fields.length} fields)`)
+            .join(", ");
+    }));
+    server.registerTool("inflight", {
+        title: "In-flight work",
+        description: "Open HTTP calls with the phase each is stuck in, database queries currently executing and " +
+            "the thread running them, and enqueued or running WorkManager jobs. This is the tool for " +
+            "'why is this screen still spinning'.\n\n" +
+            "Also returns recentHttp: the last 25 finished calls with status, headers and — when the " +
+            "app opted in via BodyCapture — request and response body previews. A body with text:null " +
+            "carries an omittedReason saying why it was not captured (disabled, wrong content type, " +
+            "one-shot stream); that is different from the call having had no body at all.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => call("inflight", {}, (flight) => {
+        const parts = [];
+        if (flight.http.length) {
+            const worst = flight.http[0];
+            parts.push(`${flight.http.length} HTTP call(s), oldest ${worst.method} ${worst.url} ` +
+                `in '${worst.phase}' for ${worst.elapsedMs}ms`);
+        }
+        if (flight.queries.length) {
+            const writes = flight.queries.filter((q) => q.kind === "write").length;
+            parts.push(`${flight.queries.length} query(ies) running on ${flight.queries[0].thread}` +
+                (writes ? ` (${writes} write)` : ""));
+        }
+        if (flight.work.length)
+            parts.push(`${flight.work.length} work job(s)`);
+        const recent = flight.recentHttp ?? [];
+        const failed = recent.filter((c) => c.status !== null && c.status >= 400);
+        if (recent.length) {
+            parts.push(`${recent.length} recent call(s)` +
+                (failed.length ? `, ${failed.length} with a ${failed[0].status}` : ""));
+        }
+        return parts.length ? parts.join("; ") : "Nothing in flight.";
+    }));
+    server.registerTool("frames", {
+        title: "Frame timing",
+        description: "How many frames the app dropped, and where the time went in the worst ones. This is the " +
+            "outcome every other collector is a proxy for: a recomposition count only matters because " +
+            "of what it does to frame time.\n\n" +
+            "worstPhase names the stage that dominated a janky frame, which is what decides where to " +
+            "look: layoutMeasure or draw points at composition doing too much, gpu or swapBuffers at " +
+            "overdraw or an expensive shader, unknownDelay at the main thread being busy with " +
+            "something that is not drawing at all. Pair a jank cluster with recompositions over the " +
+            "same from/to window to see whether recomposition is the cause.\n\n" +
+            "Frames with firstDraw are a window being drawn for the first time and are expected to be " +
+            "slow. Needs API 24 or newer.",
+        inputSchema: {
+            ...windowShape,
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(200)
+                .optional()
+                .describe("Worst N frames. Default 20."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ sinceMs, from, to, limit, since }) => {
+        const resolved = await resolveWindowSince({ sinceMs, from, to, since });
+        const windowArgs = resolved ? { from: resolved.from, to: resolved.to } : { sinceMs, from, to };
+        // GRA-185's "second, smaller thing": `frames` used to print its own
+        // truncated `frameIntervalMs` with no Hz named at all ("budget 8ms"),
+        // while `findings` — resolving the same profile through
+        // `resolveProfile` — said "8.3ms at 120Hz" for the identical panel.
+        // The prose below now goes through `describeBudget`, the same
+        // function `findingsOf`'s `frames-dropped` title uses, so the two
+        // cannot drift apart again. `frameIntervalMs` itself, in the payload
+        // below, stays exactly as the runtime sends it — only the prose
+        // changes.
+        const profile = resolveProfile({
+            liveEvents: timeline.buffer(),
+            windowTo: resolved?.to ?? Number.POSITIVE_INFINITY,
+            sessionProfile: device.sessions?.currentMeta()?.profile ?? null,
+            hello: device.hello ?? null,
+        });
+        return call("frames", { ...windowArgs, limit }, (report) => {
+            if (report.totalFrames === 0)
+                return "No frames observed yet.";
+            const rate = ((report.jankyFrames / report.totalFrames) * 100).toFixed(1);
+            const worst = report.worst[0];
+            const byPhase = {};
+            for (const frame of report.worst) {
+                byPhase[frame.worstPhase] = (byPhase[frame.worstPhase] ?? 0) + 1;
+            }
+            const phases = Object.entries(byPhase)
+                .sort((a, b) => b[1] - a[1])
+                .map(([phase, n]) => `${phase} ${n}`)
+                .join(", ");
+            return (`${report.jankyFrames} of ${report.totalFrames} frames janky (${rate}%), ` +
+                `budget ${describeBudget(profile)}.` +
+                (worst
+                    ? ` Worst ${worst.totalMs}ms, ${worst.missedFrames} refresh(es) missed, mostly ` +
+                        `${worst.worstPhase}. Across the worst frames: ${phases}.`
+                    : ""));
+        });
+    });
+    server.registerTool("blocking", {
+        title: "Main thread blocking",
+        description: "What held the main thread: stalls longer than the threshold, with the stack the main " +
+            "thread was in at the time, and any database query that ran on it.\n\n" +
+            "Stalls are found by pinging the main looper and timing the reply, so the duration is how " +
+            "long everything queued ahead of the ping took. The stack is sampled once, when the ping " +
+            "goes overdue, and app frames are listed first because the top frame is usually a native " +
+            "read and the line you can change is a few frames down.\n\n" +
+            "Database work on the main thread is reported however fast it was: a 4ms disk read in the " +
+            "frame loop is a defect that has not bitten yet. For hitches shorter than the threshold, " +
+            "use `frames` instead — that measures every frame, this one catches the big stops.",
+        inputSchema: {
+            ...windowShape,
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("Worst N of each. Default 20."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ sinceMs, from, to, limit, since }) => {
+        const resolved = await resolveWindowSince({ sinceMs, from, to, since });
+        const windowArgs = resolved ? { from: resolved.from, to: resolved.to } : { sinceMs, from, to };
+        return call("blocking", { ...windowArgs, limit }, (report) => {
+            const parts = [];
+            if (report.stalls.length) {
+                const worst = report.stalls[0];
+                parts.push(`${report.stalls.length} stall(s) over ${report.stallThresholdMs}ms, worst ` +
+                    `${worst.durationMs}ms in ${worst.stack.split("\n")[0]}`);
+            }
+            if (report.mainThreadQueries.length) {
+                const worst = report.mainThreadQueries[0];
+                parts.push(`${report.mainThreadQueries.length} database ${report.mainThreadQueries.length === 1 ? "query" : "queries"} ` +
+                    `on the main thread, worst ${worst.elapsedMs}ms: ${worst.sql.slice(0, 80)}`);
+            }
+            return parts.length ? parts.join(". ") : "Nothing blocked the main thread in this window.";
+        });
+    });
+    server.registerTool("logs", {
+        title: "App logs",
+        description: "The app's own logcat output, captured in-process and streamed over the same socket as " +
+            "everything else — no adb needed. Stack traces arrive attached to the line that started " +
+            "them rather than as loose fragments.\n\n" +
+            "Entries carry the same uptime clock as the timeline, so a log line can be placed against " +
+            "a recomposition burst or an HTTP call. Only the app's own output is visible, and the " +
+            "porthole's own tag is excluded.",
+        inputSchema: {
+            level: z
+                .enum(["V", "D", "I", "W", "E", "F"])
+                .optional()
+                .describe("Minimum level. 'W' for warnings and worse, which is usually what you want."),
+            tag: z.string().optional().describe("Substring match on the tag."),
+            contains: z.string().optional().describe("Substring match on the message."),
+            ...windowShape,
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(2000)
+                .optional()
+                .describe("Newest N entries. Default 200."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ level, tag, contains, sinceMs, from, to, limit, since }) => {
+        const resolved = await resolveWindowSince({ sinceMs, from, to, since });
+        const windowArgs = resolved ? { from: resolved.from, to: resolved.to } : { sinceMs, from, to };
+        return call("logs", { level, tag, contains, ...windowArgs, limit }, (page) => {
+            if (!page.capturing) {
+                return page.notes.join(" ") || "Log capture is not running.";
+            }
+            if (page.entries.length === 0) {
+                return page.notes.join(" ") || "No log entries matched.";
+            }
+            const counts = {};
+            for (const entry of page.entries)
+                counts[entry.level] = (counts[entry.level] ?? 0) + 1;
+            const worst = page.entries
+                .filter((entry) => entry.level === "E" || entry.level === "F")
+                .at(-1);
+            return (`${page.entries.length} entries (` +
+                Object.entries(counts)
+                    .map(([level, count]) => `${level} ${count}`)
+                    .join(", ") +
+                ")" +
+                (worst
+                    ? `. Latest error: ${worst.tag}: ${worst.message.split("\n")[0].slice(0, 120)}`
+                    : "."));
+        });
+    });
+    server.registerTool("timeline", {
+        title: "Event timeline",
+        description: "Raw event stream: recompositions, state writes, navigation, HTTP and database start/end. " +
+            "Use it to order events relative to each other — which write came before which navigation, " +
+            "what the app was doing while a call was open.",
+        inputSchema: {
+            ...windowShape,
+            kinds: z
+                .array(z.string())
+                .optional()
+                .describe("Filter by event name: recompose, state_write, frame, nav, http_start, http_end, " +
+                "db_start, db_end, log."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(5000)
+                .optional()
+                .describe("Newest N events. Default 500."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ sinceMs, from, to, since, kinds, limit }) => {
+        try {
+            // Absolute bounds first, so a window quoted from another tool selects the
+            // same span here. sinceMs stays as the convenience for "recently".
+            const span = await resolveWindowSince({ sinceMs, from, to, since });
+            // GRA-53: the third consumer of the same merge `findings` and
+            // `what_was_happening` already use — deliberately not a third
+            // mechanism. A resolved span (the ordinary case, or an explicit
+            // `{from, to}` quoted from an earlier answer) goes through
+            // `mergeWithDisk`, which already returns events filtered to the
+            // window; the un-resolved case (no span at all — nothing to bound
+            // a disk lookup by) keeps the previous behaviour of asking the
+            // device's own much-smaller ring directly.
+            let events;
+            if (span) {
+                const merged = await mergeWithDisk(span.from, span.to);
+                events = merged.events;
+            }
+            else {
+                // Prefer the local buffer: it holds more history than the device
+                // ring and survives the app being restarted underneath us.
+                events = timeline.buffer();
+                if (events.length === 0) {
+                    const page = await device.request("timeline", {
+                        limit: limit ?? 500,
+                    });
+                    events = page.events;
+                }
+            }
+            if (kinds?.length) {
+                const wanted = new Set(kinds);
+                events = events.filter((event) => wanted.has(event.event));
+            }
+            const matched = events.length;
+            const cap = limit ?? 500;
+            events = events.slice(-cap);
+            const truncated = matched > events.length;
+            const counts = {};
+            for (const event of events)
+                counts[event.event] = (counts[event.event] ?? 0) + 1;
+            const covered = events.length > 1 ? events[events.length - 1].t - events[0].t : 0;
+            // Say when the answer was cut. Silent truncation is how an agent
+            // concludes something did not happen when it simply fell off the end.
+            const note = truncated
+                ? ` ${matched} matched, newest ${events.length} returned — raise \`limit\` or narrow the window.`
+                : "";
+            const summary = events.length === 0
+                ? "No events matched. Interact with the app, widen the window, or check `kinds`."
+                : `${events.length} events over ${covered}ms: ` +
+                    Object.entries(counts)
+                        .map(([kind, count]) => `${kind} ${count}`)
+                        .join(", ") +
+                    "." +
+                    note;
+            return ok(summary, {
+                window: span ? { from: span.from, to: span.to, ms: span.ms } : null,
+                matched,
+                returned: events.length,
+                truncated,
+                events,
+            });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("open_timeline", {
+        title: "Open the timeline UI",
+        description: "Starts the local timeline UI and returns its URL. Lanes for recompositions, state writes, " +
+            "navigation, network and database, on a shared time axis. Open it in a browser; it updates " +
+            "live over a WebSocket.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const url = await timeline.start();
+            return ok(`Timeline UI running at ${url}`, { url, events: timeline.buffer().length });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    return { server, device, timeline };
+}
 // ---------------------------------------------------------------------------
 // boot
 // ---------------------------------------------------------------------------
-device.start();
-// stdout belongs to the MCP transport; anything we say goes to stderr.
-device.on("state", (state) => process.stderr.write(`[porthole] device ${state}\n`));
-const shutdown = () => {
-    device.stop();
-    timeline.stop();
-    process.exit(0);
-};
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-await server.connect(new StdioServerTransport());
-process.stderr.write(`[porthole] MCP server ready, device target ${HOST}:${PORT}\n`);
+/**
+ * True only when this file is the process's actual entry point (`node
+ * dist/index.js`, or the `porthole-mcp` bin it is published as) — never when
+ * it is merely imported, which is what every test does, and what `cli.ts`
+ * now does too (it calls `bootPortholeServer()` explicitly instead of
+ * relying on this guard). Importing this module must never open a socket,
+ * attach to stdio, or install signal handlers; only running it as a program,
+ * or explicitly asking it to boot, may.
+ */
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    return pathToFileURL(process.argv[1]).href === import.meta.url;
+}
+/**
+ * The one boot path: create the server, start the device, wire shutdown, and
+ * connect stdio. `node dist/index.js` and `porthole mcp` (`cli.ts`) both call
+ * this instead of each having their own copy — `porthole mcp` used to boot by
+ * `import("./index.js")`ing this module for its side effect, which broke the
+ * moment that side effect moved behind `isMainModule()`: `argv[1]` is
+ * `cli.js` when the CLI does the importing, so the guard can never see
+ * itself as the entry point and nothing started. Calling this function is
+ * the boot; the `isMainModule()` block below is just the one caller that
+ * also happens to be `node dist/index.js` itself.
+ */
+export async function bootPortholeServer(options = {}) {
+    const rig = createPortholeServer(options);
+    const { server, device, timeline } = rig;
+    device.start();
+    // stdout belongs to the MCP transport; anything we say goes to stderr.
+    device.on("state", (state) => process.stderr.write(`[porthole] device ${state}\n`));
+    const shutdown = () => {
+        device.stop();
+        timeline.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.connect(new StdioServerTransport());
+    process.stderr.write(`[porthole] MCP server ready, device target ${HOST}:${PORT}\n`);
+    return rig;
+}
+if (isMainModule()) {
+    await bootPortholeServer();
+}
 //# sourceMappingURL=index.js.map