@keepsnappy/mcp 0.1.0-alpha.13 → 0.1.0-alpha.16

package/README.md

@@ -7,6 +7,8 @@ writes or recomputes anything (plan 48 §4).
 It gives the same answers as the `keepsnappy` CLI (`keepsnappy findings | finding | compare | history | commits | layers`):
 both use this package's API client and answer layout, so a person and an agent read the same words.
 
+Which question needs which tool, and how to read the answers: [docs/agents.md](../../docs/agents.md) ("KeepSnappy for coding agents").
+
 ## Set it up in an app repo (TapIn)
 
 1. Ask the KeepSnappy owner for a project key with **read** scope (`bun run create-key -- <org> <app> read` in
@@ -20,7 +22,7 @@ both use this package's API client and answer layout, so a person and an agent r
   "mcpServers": {
     "keepsnappy": {
       "command": "npx",
-      "args": ["-y", "@keepsnappy/mcp"],
+      "args": ["-y", "@keepsnappy/mcp@0.1.0-alpha.16"],
       "env": {
         "KEEPSNAPPY_KEY": "${KEEPSNAPPY_KEY}",
         "KEEPSNAPPY_API": "https://keepsnappy-api-922918702810.europe-west1.run.app"
@@ -31,16 +33,18 @@ both use this package's API client and answer layout, so a person and an agent r
 ```
 
 Claude Code expands `${KEEPSNAPPY_KEY}` from your environment. `KEEPSNAPPY_API` is optional (the hosted API is the default).
-From a KeepSnappy checkout instead of npm: `"command": "bun", "args": ["<keepsnappy>/packages/mcp/src/bin.ts"]`.
+Use 0.1.0-alpha.16 or later (all eleven tools, with `pr_status` and `form`; alpha.15 has ten, alpha.13 six). From a KeepSnappy checkout instead of npm: `"command": "bun", "args": ["<keepsnappy>/packages/mcp/src/bin.ts"]`.
 
 ## Tools
 
 | Tool | Answers | API |
 |---|---|---|
+| `pr_status` | Is this branch ok, in one call: blocked, nothing blocks with results to look at, or ok; per journey × phone the deciding word, whether it blocks, the worst present findings (ids for `get_finding`) and the dashboard link. A branch never measured, whose newest run set was not judged, or that could not be compared yet is not ok: the answer says which, with its reason. | `GET /v1/branches/status` |
 | `list_findings` | Whether and when the branch was measured (`measured`: run sets, the newest set of each journey × phone with its commit, word and runs), then what got worse (Worse / Warning) or better, worst first. Filters: `branch` or `main`, `journey`, `phone`, `state` (`present` default, `not-judged`, `resolved`, `all`), `limit` (≤ 200), `offset` (the answer gives `next_offset`). | `GET /v1/findings` |
 | `get_finding` | One finding by id: what changed, where (journey, phone, branch, commit title and author, PR), how sure (runs per side, session spread, measured differently / not blocking, setup notes), why (components that rendered longer with their cause, counts that moved), what to do (a prompt for a coding agent), lifecycle (first and last seen; present, resolved, or not judged when the newest run set did not judge the measure; seen in N PRs). The prompt ends with the finding's id and page. | `GET /v1/findings/:id` |
 | `compare_runs` | Two runs side by side, window by window, and what differs in how they were measured. No statistics. | `GET /v1/compare?a=&b=` |
 | `window_history` | One window (screen, tap, scroll) of a journey on main over time, run by run, with commit titles, plus the findings on it. | `GET /v1/history` |
+| `session_places` | Every place (screen, tap, scroll) of one session (a run set of one journey on one phone) from its stored statistics: per measure the median, MAD, p10/p90 and range, and the components with the most own time. Not a verdict, not a comparison. Pick with `run_set`, or `journey` (+ `phone`, `branch`; default: the app's baseline branch (main)) for the newest closed run set with a valid run; rank by `measure` (default `render_ms`) and `sort` (`median`, `p90`, `mad`), narrow with `window`, page with `limit` / `offset` (the answer gives `next_offset`), `top_components` (default 5). A session with no stored statistics says `not_computed`, one with another version's `stale`: never zero. | `GET /v1/sessions/places` |
 | `commits_between` | The commits KeepSnappy measured between two points (run set ids or commit hashes), one entry per commit with its sessions. | `GET /v1/commits` |
 | `explain_layers` | Which of KeepSnappy's layers answers which question, and each layer's certificate (none issued yet). | `GET /v1/layers` |
 
@@ -52,14 +56,17 @@ An empty list is a clean result only when `measured.newest` exists and was judge
 KeepSnappy measurement on branch X" or "the newest run set was not judged" otherwise. Query parameters the API does not know
 are dropped, not refused (there is no `?commit=` filter).
 
-Every tool returns the text the CLI prints and the API's JSON as structured content. Every finding names its layer
+Every tool returns the text the CLI prints and the API's JSON as structured content. The answer tools (`pr_status`, `list_findings`, `get_finding`, `session_places`, `main_sessions`, `main_vs_previous`,
+`place_trend`, `window_history`) take `form`: `full` (the default, the whole text) or `short` (the CLI's `--short`). Short is
+the full text with lines left out, in the same order, and ends with one line of its own that says what it left out (with
+counts); nothing left out, no line. Each tool's description says what its short form leaves out. The JSON is the same in
+both forms. Every finding names its layer
 (4 = PR vs main, 5 = main over time), its certificate (null until plan 51 certifies the layer) and its limits.
 
 ## Words
 
-The one word table of `packages/verdicts/src/headline.ts` (REQ-VER-24): **Worse / Warning / Better / No change /
-Can't compare / Not enough data yet**, and "not blocking" as a badge on a Worse measured differently from main
-("Worse (not blocking)"). The evidence ranks likely causes; it does not prove them.
+The one word table of `packages/present/src/states.ts` (REQ-VER-24): **Worse / Slightly worse / Better / No change /
+Can’t tell**, and "not blocking" as a badge on a Worse measured differently from main ("Worse (not blocking)"). The evidence ranks likely causes; it does not prove them.
 
 ## Develop
 

package/dist/keepsnappy-mcp.js

@@ -14067,9 +14067,13 @@ class ApiError extends Error {
 }
 async function get(t, path, query = {}) {
   const u = new URL(path, t.url.endsWith("/") ? t.url : `${t.url}/`);
-  for (const [k, v] of Object.entries(query))
-    if (v !== undefined && v !== "")
+  for (const [k, v] of Object.entries(query)) {
+    if (Array.isArray(v))
+      for (const value of v)
+        u.searchParams.append(k, value);
+    else if (v !== undefined && v !== "")
       u.searchParams.set(k, String(v));
+  }
   const r = await (t.fetch ?? fetch)(u, { headers: { "x-keepsnappy-key": t.key, accept: "application/json" } });
   const text = await r.text();
   const body = text ? JSON.parse(text) : {};
@@ -14082,11 +14086,32 @@ async function get(t, path, query = {}) {
   return body;
 }
 var listFindings = (t, f = {}) => get(t, "v1/findings", { branch: f.branch, main: f.main ? "true" : undefined, journey: f.journey, phone: f.phone, state: f.state, limit: f.limit, offset: f.offset || undefined });
+var branchStatus = (t, branch) => get(t, "v1/branches/status", { branch });
 var getFinding = (t, id) => get(t, `v1/findings/${encodeURIComponent(id)}`);
 var compareRuns = (t, a, b) => get(t, "v1/compare", { a, b });
 var windowHistory = (t, q) => get(t, "v1/history", q);
 var commitsBetween = (t, q) => get(t, "v1/commits", q);
 var layers = (t) => get(t, "v1/layers");
+var sessionPlaces = (t, f) => get(t, "v1/sessions/places", {
+  run_set: f.run_set,
+  journey: f.journey,
+  phone: f.phone,
+  branch: f.branch,
+  measure: f.measure,
+  sort: f.sort,
+  window: f.window,
+  limit: f.limit,
+  offset: f.offset || undefined,
+  top_components: f.top_components
+});
+var SESSION_SORTS = ["median", "p90", "mad"];
+var mainSessions = (t, q) => get(t, "v1/main/sessions", { ...q });
+var mainSessionPlaces = (t, runSetId, q) => get(t, `v1/main/sessions/${encodeURIComponent(runSetId)}/places`, { ...q });
+var mainVsPrevious = (t, q) => {
+  const { run_set, ...query } = q;
+  return get(t, `v1/main/sessions/${encodeURIComponent(run_set ?? "latest")}/vs-previous`, query);
+};
+var placeTrend = (t, q) => get(t, "v1/places/trend", { ...q });
 
 // node_modules/.bun/zod@4.6.7/node_modules/zod/v3/helpers/util.js
 var util;
@@ -22924,6 +22949,13 @@ var NOT_FACTS = {
     decimals: 0,
     what: "Whether the test cleaned up the app’s memory once at the end of the journey, outside any measured window, before the end reading"
   },
+  "sdk.end_read": {
+    unit: "flag",
+    label: "End memory read taken on request after the clean-up (1 = yes)",
+    short: "end memory read on request",
+    decimals: 0,
+    what: "Whether the end memory reading is the one the app took when the test asked for it right after the clean-up (1), or the clean-up’s own reading (0, an app or run without the request)"
+  },
   "sdk.appstate_changes": {
     unit: "count",
     label: "App went to the background or came back",
@@ -22963,29 +22995,43 @@ var NOT_FACTS = {
 };
 var isNotFactId = (id) => Object.hasOwn(NOT_FACTS, id);
 var fieldDef = (id) => isMeasureId(id) ? MEASURES[id] : isNotFactId(id) ? NOT_FACTS[id] : undefined;
-// packages/facts/dist/src/frame.js
-var LIMIT_FRAME_MS = 1000 / 60;
-// packages/present/dist/src/places.js
-var PLACE_KIND_WORDS = {
-  screen: "Screen",
-  launch: "Launch screen",
-  tap: "Tap",
-  scroll: "Scroll",
-  step: "Test step",
-  journey: "Whole journey",
-  background: "Background",
-  after3s: "3 s after"
+var DIMENSIONS = {
+  component: { label: "Component", rankBy: "self_ms" },
+  updater: { label: "Update scheduled by", rankBy: "share_of_commits" },
+  slow_commit_component: { label: "Component in the slowest commit", rankBy: "self_ms" },
+  slow_commit_updater: { label: "Update of the slowest commit scheduled by", rankBy: "scheduled" }
 };
-var KIND_WORD = {
-  journey: PLACE_KIND_WORDS.journey,
-  screen: PLACE_KIND_WORDS.screen,
-  launch: PLACE_KIND_WORDS.launch,
-  press: PLACE_KIND_WORDS.tap,
-  drag: PLACE_KIND_WORDS.scroll,
-  step: PLACE_KIND_WORDS.step,
-  background: PLACE_KIND_WORDS.background
+var BREAKDOWN_MEASURES = {
+  self_ms: { unit: "ms", worse: "higher", label: "render time", decimals: 1 },
+  rolled_up_ms: { unit: "ms", worse: "none", label: "render time from libraries", decimals: 1 },
+  total_ms: { unit: "ms", worse: "higher", label: "total render time", decimals: 1 },
+  renders: { unit: "count", worse: "higher", label: "renders", decimals: 0 },
+  mounts: { unit: "count", worse: "higher", label: "mounts", decimals: 0 },
+  share_of_commits: { unit: "share", worse: "none", label: "share of commits", decimals: 0 },
+  scheduled: { unit: "count", worse: "none", label: "updates scheduled", decimals: 0 }
 };
+var HEAT_METRIC = "sampler.thermal.heats_up";
+var HEAT_LABEL = MEASURES[HEAT_METRIC].label;
+// packages/facts/dist/src/frame.js
+var LIMIT_FRAME_MS = 1000 / 60;
+// packages/present/dist/src/capital.js
+var upperFirst = (s) => s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+
+// packages/present/dist/src/placeWords.js
 var GENERIC_GROUPS = new Set(["app", "tabs", "root"]);
+
+// packages/present/dist/src/states.js
+var STATE_WORDS = {
+  worse: "Worse",
+  warning: "Slightly worse",
+  better: "Better",
+  "no-change": "No change",
+  "cant-tell": "Can’t tell"
+};
+var INFO_WORDS = { heat: "Phone heated up" };
+var isWorseState = (state) => state === "worse";
+var NOT_BLOCKING = "not blocking";
+
 // packages/present/dist/src/values.js
 var NO_VALUE = "–";
 var FALLBACK_DECIMALS = 1;
@@ -23022,42 +23068,250 @@ function format(unit, decimals, v) {
   const text = String(roundTo(v * shown.scale, decimals) + 0);
   return shown.unit ? `${text} ${shown.unit}` : text;
 }
+function valueText(measure, v) {
+  const def = isMeasureId(measure) ? MEASURES[measure] : BREAKDOWN_MEASURES[measure];
+  return format(def.unit, def.decimals, v);
+}
 var KEY_SEPARATOR = ":";
+function breakdownMeasure(field) {
+  const at = field.indexOf(KEY_SEPARATOR);
+  if (at < 0 || !Object.hasOwn(DIMENSIONS, field.slice(0, at)))
+    return null;
+  const measure = field.slice(field.lastIndexOf(".") + 1);
+  return Object.hasOwn(BREAKDOWN_MEASURES, measure) ? measure : null;
+}
 function fieldValueText(field, v) {
+  const breakdown = breakdownMeasure(field);
+  if (breakdown)
+    return valueText(breakdown, v);
   const def = fieldDef(field.split(KEY_SEPARATOR)[0]);
   return format(def?.unit, def?.decimals ?? FALLBACK_DECIMALS, v);
 }
+
+// packages/present/dist/src/rowWords.js
+var GONE_TAILS = {
+  branch: { notInRun: "on main, not in this run", removed: "on main, not rendered in this run" },
+  journey: { notInRun: "in the sessions before, not in the newest session", removed: "in the sessions before, not rendered in the newest session" }
+};
+var ROW_STATE_WORDS = {
+  new: "New in this PR: not compared with main",
+  notInRun: upperFirst(GONE_TAILS.branch.notInRun),
+  removed: upperFirst(GONE_TAILS.branch.removed)
+};
+var JOURNEY_ROW_WORDS = {
+  new: "New in the newest session: not compared with the sessions before",
+  notInRun: upperFirst(GONE_TAILS.journey.notInRun),
+  removed: upperFirst(GONE_TAILS.journey.removed)
+};
+
+// packages/present/dist/src/places.js
+var PLACE_KIND_WORDS = {
+  screen: "Screen",
+  launch: "Launch screen",
+  tap: "Tap",
+  scroll: "Scroll",
+  step: "Test step",
+  journey: "Whole journey",
+  background: "Background",
+  after3s: "3 s after"
+};
+var KIND_WORD = {
+  journey: PLACE_KIND_WORDS.journey,
+  screen: PLACE_KIND_WORDS.screen,
+  launch: PLACE_KIND_WORDS.launch,
+  press: PLACE_KIND_WORDS.tap,
+  drag: PLACE_KIND_WORDS.scroll,
+  step: PLACE_KIND_WORDS.step,
+  background: PLACE_KIND_WORDS.background
+};
+// packages/present/dist/src/words.js
+var REASON_WORDS = {
+  "no-baseline": "there are no main runs on this phone and journey yet",
+  "too-few-runs": "there are too few valid runs on a side",
+  "judged-measures-missing": "the judged measures are missing on a side",
+  "measured-differently": "the sides were measured differently",
+  "runs-unknown": "a change that would count has no value in some runs, so it cannot be confirmed in every run",
+  "facts-version-mismatch": "the sides were derived with different versions",
+  "not-judged-on-simulators": "timing is not judged on simulators",
+  "platforms-differ": "the sides ran on different platforms (iOS and Android are never compared)",
+  "not-enough-main": "main does not have enough sessions on this phone and journey yet"
+};
+var waitingWords = (runs) => `${runs} main ${runs === 1 ? "run waits" : "runs wait"} for a reprocess`;
+// packages/present/dist/src/stability.js
+var UNSTABLE_WORDS = {
+  short: "main varies too much here",
+  label: `${STATE_WORDS["cant-tell"]} · main varies too much here`,
+  line: "Main varies too much here to tell",
+  ratioTip: "1.0 = main’s run-to-run noise alone would pass the warning step about once in 100 comparisons.",
+  what: "Main’s own runs vary too much here to tell, so a comparison there would mostly measure noise. It is shown with its values, never judged, never blocks and is never counted. It is judged again once main settles."
+};
+// packages/present/dist/src/present.js
+var ASPECT_WORDS = {
+  renderer: "React renderer",
+  reactExport: "React export",
+  causeSplit: "work split by its cause",
+  windowModel: "window model",
+  screenWindowModel: "screen window model",
+  cpuSource: "CPU source",
+  sdk: "SDK version",
+  driver: "driver",
+  driverVersion: "driver version",
+  journeyVersion: "journey version",
+  actionGc: "memory clean-up before each step",
+  endGc: "memory clean-up at the journey end",
+  cpuProfiling: "CPU profiling"
+};
+// packages/present/dist/src/main-history.js
+var MAIN_TIER_WORDS = {
+  same: "In norm",
+  better: STATE_WORDS.better,
+  cant: STATE_WORDS["cant-tell"],
+  slight: STATE_WORDS.warning,
+  worse: STATE_WORDS.worse
+};
+var MAIN_TIER_RANK = { worse: 0, slight: 1, cant: 2, better: 3, same: 4 };
+function mainCantWords(reason, config) {
+  if (!reason)
+    return "";
+  return reason.kind === "noisy_main" ? "main’s runs vary too much there" : `main has ${reason.earlier_sessions}${config.baseline.sessions === undefined ? "" : ` of ${config.baseline.sessions}`} earlier sessions${reason.since_label ? ` on ${reason.since_label}` : ""}`;
+}
+var waitingSessionsWords = (sessions) => `${sessions} older main ${sessions === 1 ? "session waits" : "sessions wait"} for a reprocess`;
+function mainPlaceReasonWords(reason, config) {
+  switch (reason.kind) {
+    case "no_baseline":
+    case "noisy_main":
+      return mainCantWords(reason, config);
+    case "higher":
+      return "Higher than main’s earlier sessions";
+    case "lower":
+      return "Lower than main’s earlier sessions";
+    case "missing_value":
+      return REASON_WORDS["runs-unknown"];
+    case "measured_differently":
+      return REASON_WORDS["measured-differently"];
+    case "core":
+      return reason.codes.map((code) => REASON_WORDS[code]).join("; ");
+  }
+}
+var MAIN_SUMMARY_PENDING = "Runs received; the summary is not computed yet.";
+var MAIN_NEWEST_SUMMARY_PENDING = `Newest: ${MAIN_SUMMARY_PENDING}`;
+var SHORT_ASPECT_WORDS = {
+  ...ASPECT_WORDS,
+  sdk: "SDK",
+  renderer: "Renderer",
+  endGc: "End GC",
+  causeSplit: "Cause split",
+  driver: "Driver",
+  driverVersion: "Driver",
+  journeyVersion: "Journey"
+};
+function mainSessionCantWords(places, reason, config) {
+  return `${STATE_WORDS["cant-tell"]} at ${places} place${places === 1 ? "" : "s"}: ${mainCantWords(reason, config)}`;
+}
+var KIND_PLURAL = {
+  screen: "screens",
+  press: "taps",
+  drag: "scrolls",
+  launch: "launch screens",
+  step: "test steps",
+  background: "background work",
+  other: "other places"
+};
+var listWords = (kinds) => {
+  const words = kinds.map((k) => KIND_PLURAL[k] ?? "other places");
+  return words.length < 2 ? words.join("") : `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
+};
+function mainCutWords(v) {
+  const parts = [];
+  if (v.cuts.length)
+    parts.push(`Starts a new ${v.cuts.join(" and ")} baseline.`);
+  if (v.partial_render) {
+    const cut = listWords(v.partial_render.cut);
+    parts.push(`${cut[0].toUpperCase()}${cut.slice(1)} start a new render baseline; ${listWords(v.partial_render.kept)} keep theirs.`);
+  }
+  return parts.length ? parts.join(" ") : "Measures alike; no baseline cut.";
+}
 // packages/mcp/src/answer.ts
+var ANSWER_FORMS = ["short", "full"];
+var SHORT_SESSIONS = 3;
+var SHORT_POINTS = 5;
+var SHORT_PLACES = 5;
+var SHORT_FORM_NOTES = {
+  list_findings: "the how-sure lines, the place lines of findings that are not Worse and the lanes that were judged",
+  get_finding: "the why, seen and layer lines, the component lines and the prompt",
+  session_places: "the component lines",
+  main_sessions: `the sessions older than the newest ${SHORT_SESSIONS}, the main changes of all but the newest session and, for one run_set, the places in norm`,
+  main_vs_previous: `the movers after the first ${SHORT_PLACES} (every new, gone or multi-device place stays)`,
+  place_trend: `the sessions older than the newest ${SHORT_SESSIONS} and the history restarts among them (unknown restarts always stay)`,
+  window_history: `the runs older than the newest ${SHORT_POINTS}`,
+  pr_status: "the per-journey dashboard links and the heat note"
+};
+var andList = (xs) => xs.length < 2 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
+
+class Rows {
+  rows = [];
+  add(short, ...texts) {
+    for (const t of texts)
+      for (const l of t.split(`
+`))
+        this.rows.push({ text: l, short });
+    return this;
+  }
+  both(...texts) {
+    return this.add(true, ...texts);
+  }
+  full(...texts) {
+    return this.add(false, ...texts);
+  }
+  render(form, left = []) {
+    if (form !== "short")
+      return this.rows.map((r) => r.text).join(`
+`);
+    const kept = [];
+    for (const r of this.rows) {
+      if (!r.short)
+        continue;
+      if (r.text === "" && (!kept.length || kept[kept.length - 1] === ""))
+        continue;
+      kept.push(r.text);
+    }
+    if (kept[kept.length - 1] === "")
+      kept.pop();
+    if (this.rows.some((r) => !r.short && r.text.trim() !== ""))
+      kept.push(`Short form: ${andList(left.length ? left : ["other lines"])} left out; the full form shows them.`);
+    return kept.join(`
+`);
+  }
+}
 var LABEL_W = 14;
 var line = (label, text) => `  ${label.padEnd(LABEL_W)}${text}`;
 var plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+var promptText = (f) => f.what_to_do.prompt ?? "No prompt: this finding is an improvement.";
 function formatFinding(f, opts = {}) {
-  const out = [
-    f.answer.headline,
-    line("What changed", f.answer.what_changed),
-    line("Where", f.answer.where),
-    line("How sure", f.answer.how_sure),
-    line("Why", f.answer.why),
-    line("What to do", f.answer.what_to_do),
-    line("Seen", f.answer.lifecycle),
-    line("Layer", `${f.layer.id} · ${f.layer.name} (${f.certificate ? "certified" : "uncertified"})${f.limits.length ? `; limits: ${f.limits.join("; ")}` : ""}`),
-    line("Id", f.id)
-  ];
-  if (f.why.components.length > 1) {
-    out.push(line("Components", ""));
+  const r = new Rows;
+  r.both(f.answer.headline, line("What changed", f.answer.what_changed), line("Where", f.answer.where), line("How sure", f.answer.how_sure));
+  r.full(line("Why", f.answer.why));
+  r.both(line("What to do", f.answer.what_to_do));
+  r.full(line("Seen", f.answer.lifecycle), line("Layer", `${f.layer.id} · ${f.layer.name} (${f.certificate ? "certified" : "uncertified"})${f.limits.length ? `; limits: ${f.limits.join("; ")}` : ""}`));
+  r.both(line("Id", f.id));
+  if (f.why.components.length) {
+    r.full(line("Components", ""));
     for (const c of f.why.components) {
-      out.push(`    ${c.component}: ${c.self_ms_before} → ${c.self_ms_after} ms own time, renders ${c.renders_before} → ${c.renders_after}${c.cause ? `; ${c.cause}` : ""}${c.flagged ? "" : " (not certain)"}`);
+      r.full(`    ${c.component}: ${c.self_ms_before ?? "–"} → ${c.self_ms_after} ms own time, renders ${c.renders_before ?? "–"} → ${c.renders_after ?? "–"}${c.cause ? `; ${c.cause}` : ""}${c.flagged ? "" : " (not certain)"}`);
     }
   }
   if (opts.prompt)
-    out.push("", f.what_to_do.prompt ?? "No prompt: this finding is an improvement.");
-  return out.join(`
-`);
+    r.full("", promptText(f));
+  return r.render(opts.form, [
+    "the why, seen and layer lines",
+    ...f.why.components.length ? [plural(f.why.components.length, "component line")] : [],
+    ...opts.prompt ? ["the prompt"] : []
+  ]);
 }
 var when = (iso) => iso.slice(0, 16).replace("T", " ");
 var LANES_SHOWN = 8;
 var STATE_WORDS2 = { present: "still present", resolved: "resolved", "not-judged": "not judged in the newest run set" };
-function measuredLine(l) {
+function measuredLines(l, r) {
   const f = l.filters;
   const scope = [f.branch ?? "all branches", f.journey, f.phone].filter(Boolean).join(" · ");
   const m = l.measured;
@@ -23065,58 +23319,107 @@ function measuredLine(l) {
   if (!n) {
     const on = f.branch ? f.branch === l.baseline_branch ? f.branch : `branch ${f.branch}` : "any branch";
     const narrow = [f.journey, f.phone ? `phone “${f.phone}”` : null].filter(Boolean).join(", ");
-    return m.run_sets ? `${scope}: ${plural(m.run_sets, "run set")} measured, but no verdict yet: nothing is known about its performance.` : `No KeepSnappy measurement on ${on}${narrow ? ` for ${narrow}` : ""}: nothing is known about its performance.`;
+    r.both(m.run_sets ? `${scope}: ${plural(m.run_sets, "run set")} measured, but no verdict yet: nothing is known about its performance.` : `No KeepSnappy measurement on ${on}${narrow ? ` for ${narrow}` : ""}: nothing is known about its performance.`);
+    return [];
   }
   const lane = (x) => {
     const runs = x.runs.after !== null && x.runs.before !== null ? x.branch === l.baseline_branch ? `, ${x.runs.after} latest runs vs ${x.runs.before} earlier` : `, ${x.runs.after} branch runs vs ${x.runs.before} on ${l.baseline_branch}` : "";
-    return `${x.commit?.sha ? `commit ${x.commit.sha.slice(0, 7)}` : "commit not recorded"} (${when(x.at)}): ${x.word}${runs}`;
+    return `${x.commit?.sha ? `commit ${x.commit.sha.slice(0, 7)}` : "commit not recorded"} (${when(x.at)}): ${x.word}${runs}${x.waiting_for_reprocess ? `; ${waitingWords(x.waiting_for_reprocess)}` : ""}`;
   };
-  if (m.lanes.length === 1)
-    return `${scope}: newest measured ${f.branch ? "" : `on ${n.branch}, `}${lane(n)}; ${plural(m.run_sets, "run set")} measured.`;
+  if (m.lanes.length === 1) {
+    r.both(`${scope}: newest measured ${f.branch ? "" : `on ${n.branch}, `}${lane(n)}; ${plural(m.run_sets, "run set")} measured.`);
+    return [];
+  }
   const shown = m.lanes.slice(0, LANES_SHOWN);
-  return [
-    `${scope}: ${plural(m.run_sets, "run set")} measured; the newest of each journey × phone:`,
-    ...shown.map((x) => `  ${x.journey} on ${x.phone_name}${f.branch ? "" : ` (${x.branch})`}: ${lane(x)}`),
-    ...m.lanes.length > shown.length ? [`  … ${m.lanes.length - shown.length} more (--journey / --phone narrow it)`] : []
-  ].join(`
-`);
+  const unjudged = shown.filter((x) => !x.judged);
+  r.add(unjudged.length > 0, `${scope}: ${plural(m.run_sets, "run set")} measured; the newest of each journey × phone:`);
+  for (const x of shown)
+    r.add(!x.judged, `  ${x.journey} on ${x.phone_name}${f.branch ? "" : ` (${x.branch})`}: ${lane(x)}`);
+  if (m.lanes.length > shown.length)
+    r.full(`  … ${m.lanes.length - shown.length} more (--journey / --phone narrow it)`);
+  return [...shown.length > unjudged.length ? [plural(shown.length - unjudged.length, "judged lane")] : [], ...m.lanes.length > shown.length ? [plural(m.lanes.length - shown.length, "lane") + " beyond the eighth"] : []];
 }
 function countsLine(l) {
   const c = l.counts;
   const parts = [
-    c.worse ? `${c.worse} worse${c.not_blocking ? ` (${c.not_blocking} not blocking)` : ""}` : "",
-    c.warn ? plural(c.warn, "warning") : "",
-    c.better ? `${c.better} better` : ""
+    c.worse ? `${c.worse} ${STATE_WORDS.worse.toLowerCase()}${c.not_blocking ? ` (${c.not_blocking} not blocking)` : ""}` : "",
+    c.warn ? `${c.warn} ${STATE_WORDS.warning.toLowerCase()}` : "",
+    c.better ? `${c.better} ${STATE_WORDS.better.toLowerCase()}` : ""
   ].filter(Boolean);
   const state = l.filters.state;
   const unjudged = l.measured.lanes.filter((x) => !x.judged);
-  const head = parts.length ? `${parts.join(", ")}${state === "all" ? "" : `, ${STATE_WORDS2[state] ?? state}`}` : state !== "present" && state !== "all" ? `No finding ${STATE_WORDS2[state] ?? state}` : unjudged.length === l.measured.lanes.length ? `No finding, but nothing was compared yet (${[...new Set(unjudged.map((x) => x.word))].join(", ")}): measure again before calling it clean` : "Nothing worse, no warning, nothing better";
+  const head = parts.length ? `${parts.join(", ")}${state === "all" ? "" : `, ${STATE_WORDS2[state] ?? state}`}` : state !== "present" && state !== "all" ? `No finding ${STATE_WORDS2[state] ?? state}` : unjudged.length === l.measured.lanes.length ? `No finding, but nothing was compared yet (${[...new Set(unjudged.map((x) => x.word))].join(", ")}): measure again before calling it clean` : `Nothing ${STATE_WORDS.worse.toLowerCase()}, nothing ${STATE_WORDS.warning.toLowerCase()}, nothing ${STATE_WORDS.better.toLowerCase()}`;
   const heated = c.heat_runs ?? 0;
-  const never = c.unsettled ?? 0;
   const more = [
-    never ? `${plural(never, "finding")} about taps or scrolls that never settle, so their time cannot be measured (information, layer 3)` : "",
-    heated ? `${plural(heated, "run")} heated up the phone (run health, layer 3)` : "",
+    heated ? `${INFO_WORDS.heat.toLowerCase()} in ${plural(heated, "run")} (run health, layer 3)` : "",
     state === "present" && l.states.not_judged ? `${l.states.not_judged} more not judged in the newest run set (state not-judged)` : ""
   ].filter(Boolean);
   const line = `${head}${more.length ? `; ${more.join("; ")}` : ""}.`;
   return line.charAt(0).toUpperCase() + line.slice(1);
 }
-function formatFindingList(l) {
-  const out = [measuredLine(l)];
+function formatFindingList(l, opts = {}) {
+  const r = new Rows;
+  const lanesLeft = measuredLines(l, r);
   if (l.measured.newest || l.total)
-    out.push(countsLine(l));
+    r.both(countsLine(l));
   l.findings.forEach((f, i) => {
-    out.push("", `${l.offset + i + 1}. ${f.answer.headline}`, `   ${f.answer.where}`, `   ${f.answer.how_sure}`, `   ${f.answer.lifecycle} Id ${f.id}`);
+    r.both("", `${l.offset + i + 1}. ${f.answer.headline}`);
+    r.add(isWorseState(f.state), `   ${f.answer.where}`);
+    r.full(`   ${f.answer.how_sure}`);
+    r.both(`   ${f.answer.lifecycle} Id ${f.id}`);
   });
   const shown = l.findings.length ? `Showing ${l.offset + 1}–${l.offset + l.findings.length} of ${l.total}` : "";
   if (l.next_offset !== null)
-    out.push("", `${shown || `Showing none of ${l.total}`}; the rest from offset ${l.next_offset} (--offset ${l.next_offset}).`);
+    r.both("", `${shown || `Showing none of ${l.total}`}; the rest from offset ${l.next_offset} (--offset ${l.next_offset}).`);
   else if (l.offset > 0)
-    out.push("", shown ? `${shown}.` : `Offset ${l.offset} is past the last of ${l.total}.`);
+    r.both("", shown ? `${shown}.` : `Offset ${l.offset} is past the last of ${l.total}.`);
   if (l.findings.length)
-    out.push("", "One finding with its evidence and a prompt: keepsnappy finding <id> --prompt");
-  return out.join(`
-`);
+    r.both("", "One finding with its evidence and a prompt: keepsnappy finding <id> --prompt");
+  const notWorse = l.findings.filter((f) => !isWorseState(f.state)).length;
+  return r.render(opts.form, [
+    ...l.findings.length ? [plural(l.findings.length, "how-sure line")] : [],
+    ...notWorse ? [plural(notWorse, "place line")] : [],
+    ...lanesLeft
+  ]);
+}
+var STATUS_LEAD = {
+  ok: "ok",
+  warns: "nothing blocks, results to look at",
+  blocks: "blocked",
+  "cant-tell": "not ok yet, nothing was compared",
+  "not-judged": "not ok yet, the newest run set was not judged",
+  "never-measured": "not ok yet, never measured"
+};
+function formatBranchStatus(s, opts = {}) {
+  const r = new Rows;
+  r.both(`${s.branch}: ${STATUS_LEAD[s.result]}`, s.reason);
+  if (s.lanes.length)
+    r.both("");
+  for (const l of s.lanes) {
+    const badge = l.result === "blocks" ? " (blocks)" : l.word === STATE_WORDS.worse ? ` (${NOT_BLOCKING})` : "";
+    const sha = l.commit?.sha?.slice(0, 7);
+    r.both(`  ${l.journey_title ?? l.journey} on ${l.phone_name}: ${l.word}${badge} · ${sha ? `commit ${sha}` : "commit not recorded"} (${when(l.at)})${l.in_newest_run_set ? "" : " · older run set"}${l.waiting_for_reprocess ? `; ${waitingWords(l.waiting_for_reprocess)}` : ""}`);
+    for (const f of l.worst)
+      r.both(`    ${f.id}  ${f.headline}`);
+    if (l.present_findings > l.worst.length)
+      r.both(`    … ${l.present_findings - l.worst.length} more: keepsnappy findings --branch ${s.branch}`);
+    if (l.link)
+      r.full(`    ${l.link}`);
+  }
+  const links = s.lanes.filter((l) => l.link).length;
+  const heated = s.counts.heat_runs ?? 0;
+  const more = [
+    [false, heated ? `${INFO_WORDS.heat.toLowerCase()} in ${plural(heated, "run")} (information, never blocks)` : ""],
+    [true, s.not_judged_findings ? `${plural(s.not_judged_findings, "finding")} not judged in the newest run set; they may still be there: keepsnappy findings --branch ${s.branch} --state not-judged` : ""],
+    [true, s.links.overview ? `Dashboard: ${s.links.overview}` : ""],
+    [true, s.worst.length ? "One finding with its evidence and a prompt: keepsnappy finding <id> --prompt" : ""]
+  ];
+  const shownMore = more.filter(([, text]) => text);
+  if (shownMore.length)
+    r.both("");
+  for (const [short, text] of shownMore)
+    r.add(short, text);
+  return r.render(opts.form, [...links ? [plural(links, "dashboard link")] : [], ...heated ? ["the heat note"] : []]);
 }
 var commitText = (c) => !c ? "commit not recorded" : c.title ? `“${c.title}”${c.author ? ` by ${c.author}` : ""}${c.sha ? ` (${c.sha.slice(0, 7)})` : ""}` : c.sha ? c.sha.slice(0, 7) : "commit not recorded";
 function formatCompare(r) {
@@ -23138,19 +23441,20 @@ function formatCompare(r) {
   return out.join(`
 `);
 }
-function formatHistory(h) {
-  const out = [`${h.window_name} in ${h.journey_title ?? h.journey} on ${h.branch}: ${h.points.length ? `${plural(h.points.length, "run")}, oldest first` : h.note ?? "no runs"}`];
+function formatHistory(h, opts = {}) {
+  const r = new Rows;
+  r.both(`${h.window_name} in ${h.journey_title ?? h.journey} on ${h.branch}: ${h.points.length ? `${plural(h.points.length, "run")}, oldest first` : h.note ?? "no runs"}`);
   const ms = h.measures.slice(0, 4);
   if (h.points.length) {
-    out.push(`  ${"when".padEnd(17)}${ms.map((m) => (m.label.length > 22 ? `${m.label.slice(0, 21)}…` : m.label).padStart(24)).join("")}  commit`);
-    for (const p of h.points) {
-      out.push(`  ${(p.at ?? "").slice(0, 16).replace("T", " ").padEnd(17)}${ms.map((m) => fieldValueText(m.metric, p.values[m.metric]).padStart(24)).join("")}  ${commitText(p.commit)}`);
-    }
+    r.both(`  ${"when".padEnd(17)}${ms.map((m) => (m.label.length > 22 ? `${m.label.slice(0, 21)}…` : m.label).padStart(24)).join("")}  commit`);
+    h.points.forEach((p, i) => {
+      r.add(i >= h.points.length - SHORT_POINTS, `  ${(p.at ?? "").slice(0, 16).replace("T", " ").padEnd(17)}${ms.map((m) => fieldValueText(m.metric, p.values[m.metric]).padStart(24)).join("")}  ${commitText(p.commit)}`);
+    });
   }
   if (h.findings.length)
-    out.push("", "Findings on this window:", ...h.findings.map((f) => `  ${f.answer.headline} — ${f.where.branch} (${f.id})`));
-  return out.join(`
-`);
+    r.both("", "Findings on this window:", ...h.findings.map((f) => `  ${f.answer.headline} — ${f.where.branch} (${f.id})`));
+  const older = Math.max(0, h.points.length - SHORT_POINTS);
+  return r.render(opts.form, older ? [plural(older, "older run")] : []);
 }
 function formatCommits(c) {
   return [
@@ -23160,6 +23464,55 @@ function formatCommits(c) {
   ].join(`
 `);
 }
+var list = (xs) => xs.join(", ");
+function versionText(label, counts) {
+  const values = Object.keys(counts).sort((a, b) => a === "unknown" ? -1 : b === "unknown" ? 1 : a < b ? -1 : a > b ? 1 : 0);
+  const name = (k) => k === "unknown" ? "not recorded" : k;
+  if (values.length === 0)
+    return "";
+  if (values.length === 1)
+    return `${label} ${name(values[0])}`;
+  return `${label} mixed: ${values.map((k) => `${name(k)} ×${counts[k]}`).join(", ")}`;
+}
+function formatSessionPlaces(p, opts = {}) {
+  const s = p.session;
+  const sha = s.commit?.sha?.slice(0, 7);
+  const commit = s.commit ? `${s.commit.title ? `“${s.commit.title}”${s.commit.author ? ` by ${s.commit.author}` : ""}` : sha ?? "commit not recorded"}${s.commit.title && sha ? ` (${sha})` : ""}` : "commit not recorded";
+  const v = s.versions;
+  const codes = Object.keys(s.runs.invalid_codes);
+  const r = new Rows().both(`Session ${s.completed_at ? `${when(s.completed_at)} ` : ""}on ${s.branch}: ${commit}${s.pull_request?.number ? `, PR #${s.pull_request.number}` : ""}; ${s.journey.title ?? s.journey.key} on ${s.phone.model}${s.phone.os ? ` · ${s.phone.os}` : ""}${s.status === "processed" ? "" : ` (run set ${s.status})`}.`, `Runs: ${s.runs.valid} valid${s.runs.invalid ? `, ${s.runs.invalid} invalid${codes.length ? ` (${list(codes)})` : ""}` : ""}. ${[
+    versionText("SDK", v.sdk),
+    versionText("driver", v.driver),
+    versionText("driver version", v.driver_version),
+    versionText("app", v.app_build),
+    versionText("journey version", v.journey_version),
+    `derivation ${v.derivation}`,
+    `stats ${v.stats}`
+  ].filter(Boolean).join(", ")}.`);
+  if (s.not_computed)
+    return r.both("Not computed: this session has no stored statistics yet; nothing is known about its places (not zero).").render(opts.form);
+  if (s.stale)
+    return r.both("Stale: its statistics are of another derivation or stats version and are not served until the next recompute rewrites them; nothing is known about its places (not zero).").render(opts.form);
+  const by = p.filters.measure;
+  const byLabel = p.places.flatMap((x) => x.measures).find((m) => m.measure === by)?.label ?? by;
+  r.both(`Stored per-session statistics: no verdict, no comparison. Places by ${byLabel} (${p.filters.sort}), highest first${p.filters.window ? `, matching “${p.filters.window}”` : ""}${p.without_measure ? `; ${p.without_measure} of ${p.total} places ${p.without_measure === 1 ? "has" : "have"} no value for it` : ""}.`, "");
+  let componentLines = 0;
+  p.places.forEach((place, i) => {
+    const m = place.measures.find((x) => x.measure === by);
+    const value = m ? `${fieldValueText(by, m.median)} (p90 ${fieldValueText(by, m.p90)}, n ${m.n})` : `no ${by}`;
+    const comps = place.components.map((c) => `${c.name} ${valueText("self_ms", c.self_ms.median)} (p90 ${valueText("self_ms", c.self_ms.p90)}${c.renders_median !== null ? `, ${plural(c.renders_median, "render")}` : ""})`);
+    r.both(`${p.offset + i + 1}. ${place.window_name}: ${value}`);
+    if (comps.length) {
+      r.full(`   Components: ${list(comps)}`);
+      componentLines++;
+    }
+  });
+  if (!p.places.length)
+    r.both(p.total ? `Offset ${p.offset} is past the last of ${p.total} places.` : "No place with stored statistics in this session matches.");
+  else if (p.next_offset !== null)
+    r.both("", `Showing ${p.offset + 1}–${p.offset + p.places.length} of ${p.total}; the rest from offset ${p.next_offset} (--offset ${p.next_offset}).`);
+  return r.render(opts.form, componentLines ? [plural(componentLines, "component line")] : []);
+}
 function formatLayers(l) {
   return [
     l.note,
@@ -23169,6 +23522,100 @@ function formatLayers(l) {
   ].join(`
 `);
 }
+var MAIN_TIERS_WORST_FIRST = Object.keys(MAIN_TIER_RANK).sort((a, b) => MAIN_TIER_RANK[a] - MAIN_TIER_RANK[b]);
+function formatMainSessions(h, opts = {}) {
+  const baseline = { baseline: { sessions: h.baseline_sessions } };
+  const r = new Rows().both(`Main sessions: tiers are verdicts vs ${h.baseline_sessions === undefined ? "earlier sessions" : `the ${h.baseline_sessions} sessions before`}.`);
+  if (!h.sessions.length)
+    r.both("No main sessions measured for this journey and phone.");
+  const recent = new Set(h.sessions.slice(-SHORT_SESSIONS));
+  const latest = h.sessions[h.sessions.length - 1];
+  let otherChanges = 0;
+  for (const s of h.sessions) {
+    const k = recent.has(s);
+    r.add(k, `${when(s.at)}  ${s.run_set_id}  ${commitText(s.commit ? { ...s.commit, author: null } : null)} (${plural(s.runs, "run")})`);
+    if (!s.places)
+      r.add(k, `  ${MAIN_SUMMARY_PENDING}${s.summary_reason ? ` (${s.summary_reason})` : ""}`);
+    else
+      r.add(k, `  ${MAIN_TIERS_WORST_FIRST.map((tier) => `${MAIN_TIER_WORDS[tier]}: ${s.places[tier]}`).join("; ")}${s.cant_reason ? `; ${mainSessionCantWords(s.places.cant, s.cant_reason, baseline)}` : ""}`);
+    if (s.waiting_sessions)
+      r.add(k, `  ${waitingSessionsWords(s.waiting_sessions)}`);
+    if (s.memory)
+      r.add(k, `  Memory: ${MAIN_TIER_WORDS[s.memory.tier]}, ${s.memory.median} MB (n ${s.memory.n})${s.memory.cant_reason ? `; ${mainCantWords(s.memory.cant_reason, baseline)}` : ""}`);
+    for (const v of h.versions.filter((v) => v.from_run_set_id === s.run_set_id))
+      r.add(k, `  Version: ${v.label}; ${mainCutWords(v)}`);
+    for (const c of h.changes.filter((c) => c.from_run_set_id === s.run_set_id)) {
+      r.add(s === latest, `  Main change: ${c.place} ${c.ref}, ${c.before_median ?? "–"} → ${c.after_median ?? "–"}`);
+      if (k && s !== latest)
+        otherChanges++;
+    }
+  }
+  const older = h.sessions.length - recent.size;
+  return r.render(opts.form, [...older ? [plural(older, "older session")] : [], ...otherChanges ? [plural(otherChanges, "main change") + " of the other recent sessions"] : []]);
+}
+function formatMainSessionPlaces(p, opts = {}) {
+  const r = new Rows;
+  if (p.status !== "ok")
+    return r.both(`${MAIN_SUMMARY_PENDING}${p.summary_reason ? ` (${p.summary_reason})` : ""}`).render(opts.form);
+  const baselineSessions = p.baseline_sessions;
+  r.both(`Main session places: tiers are verdicts vs ${p.baseline_sessions === undefined ? "earlier sessions" : `the ${p.baseline_sessions} sessions before`}.`);
+  for (const x of p.places)
+    r.add(x.tier !== "same", `  ${x.place} ${x.ref}: ${MAIN_TIER_WORDS[x.tier]}${x.reason ? `; ${mainPlaceReasonWords(x.reason, { baseline: { sessions: baselineSessions } })}` : ""}`);
+  const inNorm = p.places.filter((x) => x.tier === "same").length;
+  return r.render(opts.form, inNorm ? [plural(inNorm, "place") + " in norm"] : []);
+}
+var signed = (n) => `${n > 0 ? "+" : ""}${Number(n.toFixed(3))}`;
+var previousLine = (p) => `  ${p.place} ${p.ref}${p.devices ? ` [devices ${p.devices.before.join(", ") || "–"} → ${p.devices.after.join(", ") || "–"}]` : ""}: ${p.status === "compared" ? "" : `${p.status}; `}${p.before ?? "–"} → ${p.after ?? "–"}; delta ${p.delta === null ? "–" : signed(p.delta)}; ${p.percent_change === null ? "change undefined" : `${signed(p.percent_change)}%`}; n ${p.n.before ?? "–"} → ${p.n.after ?? "–"}`;
+function formatMainVsPrevious(m, opts = {}) {
+  const r = new Rows().both(`Information only: main session ${m.run_set_id} vs ${m.previous_run_set_id ?? "no previous session"}.`, `Measure: ${m.measure}; ${m.status}.`);
+  if (m.cut === "unknown")
+    r.both("History restart: unknown; current summaries unavailable.");
+  else if (m.cut)
+    r.both(`History restart: ${m.cut.label}; ${m.cut.cuts.join(", ")}. Numbers cross this restart.`);
+  if (m.not_computed.length)
+    r.both(`not_computed: ${m.not_computed.join(", ")}`);
+  if (m.stale.length)
+    r.both(`stale: ${m.stale.join(", ")}`);
+  if (m.journey)
+    r.both("Whole journey:", previousLine(m.journey));
+  m.places.forEach((p, i) => r.add(i < SHORT_PLACES || p.status !== "compared", previousLine(p)));
+  if (m.next_offset !== null)
+    r.both(`Showing ${m.offset + 1}–${m.offset + m.places.length} of ${m.total}; next offset ${m.next_offset}.`);
+  const smaller = m.places.filter((p, i) => i >= SHORT_PLACES && p.status === "compared").length;
+  return r.render(opts.form, smaller ? [plural(smaller, "smaller mover")] : []);
+}
+function formatPlaceTrend(t, opts = {}) {
+  const r = new Rows().both(`${t.journey} · ${t.phone.model} · ${t.baseline_branch}: stored per-session statistics`);
+  const newest = new Set(t.sessions.slice(-SHORT_SESSIONS).map((s) => s.run_set_id));
+  const olderSessions = new Set;
+  let olderRestarts = 0;
+  for (const session of t.sessions) {
+    const k = newest.has(session.run_set_id);
+    if (session.restarts_known === false)
+      r.both(`History restarts unknown: ${session.run_set_id} (no current main summary in the history window)`);
+    for (const restart of t.restarts.filter((x) => x.from_run_set_id === session.run_set_id)) {
+      r.add(k, `History restarts: ${restart.label} (${restart.cuts.join(", ")})`);
+      if (!k)
+        olderRestarts++;
+    }
+    for (const place of t.places) {
+      const value = place.sessions.find((s) => s.run_set_id === session.run_set_id);
+      if (!value)
+        continue;
+      const unit = place.unit ? ` ${place.unit}` : "";
+      if (!k)
+        olderSessions.add(session.run_set_id);
+      r.add(k, `${session.completed_at?.slice(0, 10) ?? "date unknown"} ${session.commit.sha?.slice(0, 7) ?? "commit unknown"} · ${place.window} · ${place.label} (${place.ref}): median ${value.median}${unit}, MAD ${value.mad}${unit}, n=${value.n}`);
+    }
+  }
+  if (!t.sessions.length)
+    r.both("No main sessions.");
+  if (t.not_computed.length)
+    r.both(`Not computed: ${t.not_computed.join(", ")}`);
+  if (t.stale.length)
+    r.both(`Stale: ${t.stale.join(", ")}`);
+  return r.render(opts.form, [...olderSessions.size ? [plural(olderSessions.size, "older session")] : [], ...olderRestarts ? [plural(olderRestarts, "older restart marker")] : []]);
+}
 
 // packages/mcp/src/server.ts
 var SERVER_NAME = "keepsnappy";
@@ -23188,7 +23635,7 @@ function createServer(target) {
   const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
   server.registerTool("list_findings", {
     title: "List performance findings",
-    description: "What got worse (Worse / Warning) or better in the app, worst first, as KeepSnappy measured it on real phones. The answer starts with whether and when the branch was measured and how its newest run set read: an empty list on a branch that was never measured, or whose newest run set was not judged, is not a clean result. Filter by a PR branch or main, journey, phone, and state (present by default; not-judged = the newest run set did not judge it, so it may still be there). Each finding says what changed, where, how sure, and has an id for get_finding. Page with offset.",
+    description: "What got worse (Worse / Slightly worse) or better in the app, worst first, as KeepSnappy measured it on real phones. The answer starts with whether and when the branch was measured and how its newest run set read: an empty list on a branch that was never measured, or whose newest run set was not judged, is not a clean result. Filter by a PR branch or main, journey, phone, and state (present by default; not-judged = the newest run set did not judge it, so it may still be there). Each finding says what changed, where, how sure, and has an id for get_finding. Page with offset." + ` ${shortNote("list_findings")}`,
     inputSchema: {
       branch: string2().optional().describe("A PR branch, e.g. feat/keepsnappy-integration"),
       main: boolean2().optional().describe("Findings of main over time instead of a branch"),
@@ -23196,16 +23643,17 @@ function createServer(target) {
       phone: string2().optional().describe('Part of the phone model, e.g. "iPhone 15"'),
       state: _enum(["present", "resolved", "not-judged", "all"]).optional(),
       limit: number2().int().min(1).max(200).optional(),
-      offset: number2().int().min(0).optional().describe("Skip this many findings; the answer gives next_offset")
+      offset: number2().int().min(0).optional().describe("Skip this many findings; the answer gives next_offset"),
+      form: formInput
     },
     annotations: READ_ONLY
-  }, async (a) => answer(() => listFindings(target, a), formatFindingList));
+  }, async ({ form, ...a }) => answer(() => listFindings(target, a), (l) => formatFindingList(l, { form })));
   server.registerTool("get_finding", {
     title: "One finding with evidence and a prompt",
-    description: "One finding by id: what changed, where (journey, phone, branch, commit, PR), how sure (runs, spread, measured differently / not blocking), why (components that rendered longer and their causes, counts that moved), what to do (a prompt for a coding agent), and since when it is seen. The evidence ranks likely causes; it does not prove them.",
-    inputSchema: { id: string2().regex(/^f_[0-9a-f]{16}$/).describe("Finding id from list_findings") },
+    description: `One finding by id: what changed, where (journey, phone, branch, commit, PR), how sure (runs, spread, measured differently / not blocking), why (components that rendered longer and their causes, counts that moved), what to do (a prompt for a coding agent), and since when it is seen. The evidence ranks likely causes; it does not prove them. why.status: ok = stored evidence is attached; none = no stored evidence for this place, or a memory/heat finding where React evidence does not explain the measure; no-profiles = the input runs explicitly recorded React export off; no-timings = profiles have no usable component timings; not-enough-runs = too few runs for component evidence. The last two values are reserved: the current stored-judgement reader does not infer them from missing evidence. Null component values were not stored; a new component has a null baseline. Counts are evidence, never a verdict. ${shortNote("get_finding")}`,
+    inputSchema: { id: string2().regex(/^f_[0-9a-f]{16}$/).describe("Finding id from list_findings"), form: formInput },
     annotations: READ_ONLY
-  }, async ({ id }) => answer(() => getFinding(target, id), (f) => formatFinding(f, { prompt: true })));
+  }, async ({ id, form }) => answer(() => getFinding(target, id), (f) => formatFinding(f, { prompt: form !== "short", form })));
   server.registerTool("compare_runs", {
     title: "Compare two runs",
     description: "Two runs side by side, window by window, with what differs in how they were measured. One run against one run: no statistics; use findings for verdicts.",
@@ -23214,29 +23662,97 @@ function createServer(target) {
   }, async ({ a, b }) => answer(() => compareRuns(target, a, b), formatCompare));
   server.registerTool("window_history", {
     title: "One window on main over time",
-    description: "Every recent main run of one window (a screen, tap or scroll) of a journey, oldest first, with commit titles, and the findings on that window.",
+    description: `Every recent main run of one window (a screen, tap or scroll) of a journey, oldest first, with commit titles, and the findings on that window. ${shortNote("window_history")}`,
     inputSchema: {
       journey: string2().describe("Journey key, e.g. live-ui"),
-      window: string2().describe("Window id (press:live.chat.send) or name (Tap: live chat send)"),
+      window: string2().describe("Exact window id (press:live.chat.send); display names are not identifiers"),
       phone: string2().optional(),
-      limit: number2().int().min(1).max(200).optional()
+      limit: number2().int().min(1).max(200).optional(),
+      form: formInput
     },
     annotations: READ_ONLY
-  }, async (a) => answer(() => windowHistory(target, a), formatHistory));
+  }, async ({ form, ...a }) => answer(() => windowHistory(target, a), (h) => formatHistory(h, { form })));
   server.registerTool("commits_between", {
     title: "Measured commits between two points",
     description: "The commits KeepSnappy measured between two points of a branch (run set ids or commit hashes), one entry per commit with its measuring sessions, title, author and time. Only measured commits; git log gives the rest.",
     inputSchema: { from: string2().min(7), to: string2().min(7).optional(), branch: string2().optional().describe("Default: main") },
     annotations: READ_ONLY
   }, async (a) => answer(() => commitsBetween(target, a), formatCommits));
+  server.registerTool("session_places", {
+    title: "Every place of one session",
+    description: `The overall performance of one measuring session (a run set of one journey on one phone), place by place (a screen, tap or scroll), from the statistics stored for that session: per measure its median, spread (MAD), p10/p90 and range over the session's valid runs, and the components with the most own render time. Use it to find places worth optimising. It is not a verdict and not a comparison: for what got worse use list_findings, for one place over time window_history. Pick the session with run_set, or with journey (+ phone, + branch; default: the app's baseline branch (main)) for its newest closed run set that has a valid run. Places are ranked by measure (default render_ms) and sort (median, p90 or mad, highest first); window narrows by id or name; places without the measure are listed last. Page with offset (the answer gives next_offset). A session with no stored statistics says not_computed, one with statistics of another version says stale: both mean nothing is known about its places, not that they are fine. ${shortNote("session_places")}`,
+    inputSchema: {
+      run_set: string2().optional().describe("Run set id (the answer of other tools names it); otherwise journey picks the newest closed one"),
+      journey: string2().optional().describe("Journey key, e.g. live-ui"),
+      phone: string2().optional().describe('Part of the phone model, e.g. "iPhone 15", or a device id'),
+      branch: string2().optional().describe("With journey: the branch of the run set (default: the app's baseline branch); not with run_set"),
+      measure: string2().optional().describe("The measure places are ranked by (default render_ms), e.g. commit_max_ms, renders, dur_ms"),
+      sort: _enum(SESSION_SORTS).optional().describe("The statistic of the measure to rank by (default median)"),
+      window: string2().optional().describe('Only places whose id or name contains this, e.g. "chat send"'),
+      limit: number2().int().min(1).max(200).optional(),
+      offset: number2().int().min(0).optional().describe("Skip this many places; the answer gives next_offset"),
+      top_components: number2().int().min(0).max(20).optional().describe("Components with the most own time listed per place (default 5)"),
+      form: formInput
+    },
+    annotations: READ_ONLY
+  }, async ({ form, ...a }) => answer(() => sessionPlaces(target, a), (r) => formatSessionPlaces(r, { form })));
   server.registerTool("explain_layers", {
     title: "Which layer answers which question",
     description: "KeepSnappy’s decision layers (instrument, execution, single value, run health, PR vs main, main over time, access), the questions each answers, where to read it, and each layer’s certificate.",
     inputSchema: {},
     annotations: READ_ONLY
   }, async () => answer(() => layers(target), formatLayers));
+  const mainLane = {
+    journey: string2().min(1).describe("Journey key or id"),
+    phone: string2().min(1).describe("Exact device model, as in the dashboard, e.g. iPhone 15")
+  };
+  const mainDescription = "Main session tiers are verdicts vs the earlier sessions (baseline_sessions in the API answer); vs-previous is information, not a verdict.";
+  server.registerTool("main_sessions", {
+    title: "Main sessions and their tiers",
+    description: `${mainDescription} List sessions with tier counts, memory and history restarts, or give run_set for that session’s places and reasons. sessions cannot be combined with run_set. ${shortNote("main_sessions")}`,
+    inputSchema: { ...mainLane, sessions: number2().int().min(1).max(20).optional(), run_set: string2().min(1).optional(), form: formInput },
+    annotations: READ_ONLY
+  }, async ({ run_set, form, ...q }) => {
+    if (run_set && q.sessions !== undefined)
+      return { isError: true, content: [{ type: "text", text: "400: sessions cannot be combined with run_set" }] };
+    return run_set ? answer(() => mainSessionPlaces(target, run_set, { journey: q.journey, phone: q.phone }), (p) => formatMainSessionPlaces(p, { form })) : answer(() => mainSessions(target, q), (h) => formatMainSessions(h, { form }));
+  });
+  server.registerTool("main_vs_previous", {
+    title: "Main session vs previous: stored medians",
+    description: `${mainDescription} Before, after, delta, percent change and n from stored medians in one phone-model lane, with device ids per side; multiple devices on a side return devices_differ without pooling. new/gone are missing on one side, never zero. Flags history restarts. Latest session by default. Sorted by absolute percent change for measure. ${shortNote("main_vs_previous")}`,
+    inputSchema: {
+      ...mainLane,
+      run_set: string2().min(1).optional(),
+      measure: string2().min(1).max(300).optional(),
+      limit: number2().int().min(1).max(200).optional(),
+      offset: number2().int().min(0).optional(),
+      form: formInput
+    },
+    annotations: READ_ONLY
+  }, async ({ form, ...q }) => answer(() => mainVsPrevious(target, q), (m) => formatMainVsPrevious(m, { form })));
+  server.registerTool("place_trend", {
+    title: "One place over main sessions",
+    description: `Stored per-session statistics of one place over main’s sessions, oldest first, with history restart markers. No verdict: use list_findings for a verdict, or session_places for every place in one session. Defaults to every stored measure at the place; request component refs explicitly. ${shortNote("place_trend")}`,
+    inputSchema: {
+      journey: string2().min(1).describe("Journey key or id"),
+      phone: string2().min(1).describe("Device id or part of the phone model; ambiguous matches are rejected"),
+      window: array(string2().min(1)).min(1).max(50).describe("Place ids or names"),
+      ref: array(string2().min(1)).min(1).max(200).optional().describe("Refs, e.g. m:render_ms or b:component:<key>:self_ms"),
+      sessions: number2().int().min(1).max(30).optional().describe("Newest main sessions, default 10"),
+      form: formInput
+    },
+    annotations: READ_ONLY
+  }, async ({ form, ...a }) => answer(() => placeTrend(target, a), (t) => formatPlaceTrend(t, { form })));
+  server.registerTool("pr_status", {
+    title: "Is my PR ok?",
+    description: `Is this branch ok, in one call. The answer is blocked, nothing blocks with results to look at, or ok; per journey × phone it gives the deciding word and whether it blocks, the worst present findings with ids for get_finding, and dashboard links. A branch that was never measured, whose newest run set was not judged, or that could not be compared yet is not ok: the answer says which, with its reason. Use list_findings for every finding. ${shortNote("pr_status")}`,
+    inputSchema: { branch: string2().min(1).describe("The PR branch, e.g. feat/keepsnappy-integration"), form: formInput },
+    annotations: READ_ONLY
+  }, async ({ branch, form }) => answer(() => branchStatus(target, branch), (s) => formatBranchStatus(s, { form })));
   return server;
 }
+var formInput = _enum(ANSWER_FORMS).optional().describe("full (default): the whole answer. short: what decides, without the evidence detail; its last line says what it left out. The same JSON either way");
+var shortNote = (tool) => `form short leaves out ${SHORT_FORM_NOTES[tool]}, and ends with a line saying so.`;
 
 // packages/mcp/src/bin.ts
 var key = process.env.KEEPSNAPPY_KEY;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepsnappy/mcp",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.16",
   "description": "KeepSnappy MCP server (stdio, read-only): performance findings, compare, window history and commits for coding agents.",
   "type": "module",
   "license": "UNLICENSED",