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

package/README.md

@@ -41,6 +41,7 @@ From a KeepSnappy checkout instead of npm: `"command": "bun", "args": ["<keepsna
 | `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` |
 
@@ -57,9 +58,8 @@ Every tool returns the text the CLI prints and the API's JSON as structured cont
 
 ## 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) : {};
@@ -14087,6 +14091,26 @@ 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 +22948,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,6 +22994,22 @@ var NOT_FACTS = {
 };
 var isNotFactId = (id) => Object.hasOwn(NOT_FACTS, id);
 var fieldDef = (id) => isMeasureId(id) ? MEASURES[id] : isNotFactId(id) ? NOT_FACTS[id] : undefined;
+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 BREAKDOWN_MEASURES = {
+  self_ms: { unit: "ms", worse: "higher", label: "render time", 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/places.js
@@ -22986,6 +23033,15 @@ var KIND_WORD = {
   background: PLACE_KIND_WORDS.background
 };
 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" };
 // packages/present/dist/src/values.js
 var NO_VALUE = "–";
 var FALLBACK_DECIMALS = 1;
@@ -23022,11 +23078,104 @@ 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/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"
+};
+// 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}` : ""}`;
+}
+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"
+};
 // packages/mcp/src/answer.ts
 var LABEL_W = 14;
 var line = (label, text) => `  ${label.padEnd(LABEL_W)}${text}`;
@@ -23043,10 +23192,10 @@ function formatFinding(f, opts = {}) {
     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) {
+  if (f.why.components.length) {
     out.push(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)"}`);
+      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)"}`);
     }
   }
   if (opts.prompt)
@@ -23084,18 +23233,16 @@ function measuredLine(l) {
 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("; ")}` : ""}.`;
@@ -23160,6 +23307,61 @@ 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(r) {
+  const s = r.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 head = [
+    `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 [...head, "Not computed: this session has no stored statistics yet; nothing is known about its places (not zero)."].join(`
+`);
+  if (s.stale)
+    return [...head, "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)."].join(`
+`);
+  const by = r.filters.measure;
+  const byLabel = r.places.flatMap((p) => p.measures).find((m) => m.measure === by)?.label ?? by;
+  const ranked = r.places.map((p, i) => {
+    const m = p.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 = p.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")}` : ""})`);
+    return [`${r.offset + i + 1}. ${p.window_name}: ${value}`, ...comps.length ? [`   Components: ${list(comps)}`] : []];
+  });
+  const out = [
+    ...head,
+    `Stored per-session statistics: no verdict, no comparison. Places by ${byLabel} (${r.filters.sort}), highest first${r.filters.window ? `, matching “${r.filters.window}”` : ""}${r.without_measure ? `; ${r.without_measure} of ${r.total} places ${r.without_measure === 1 ? "has" : "have"} no value for it` : ""}.`,
+    "",
+    ...ranked.flat()
+  ];
+  if (!r.places.length)
+    out.push(r.total ? `Offset ${r.offset} is past the last of ${r.total} places.` : "No place with stored statistics in this session matches.");
+  else if (r.next_offset !== null)
+    out.push("", `Showing ${r.offset + 1}–${r.offset + r.places.length} of ${r.total}; the rest from offset ${r.next_offset} (--offset ${r.next_offset}).`);
+  return out.join(`
+`);
+}
 function formatLayers(l) {
   return [
     l.note,
@@ -23169,6 +23371,83 @@ 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) {
+  const baseline = { baseline: { sessions: h.baseline_sessions } };
+  const out = [`Main sessions: tiers are verdicts vs ${h.baseline_sessions === undefined ? "earlier sessions" : `the ${h.baseline_sessions} sessions before`}.`];
+  if (!h.sessions.length)
+    out.push("No main sessions measured for this journey and phone.");
+  for (const s of h.sessions) {
+    out.push(`${when(s.at)}  ${s.run_set_id}  ${commitText(s.commit ? { ...s.commit, author: null } : null)} (${plural(s.runs, "run")})`);
+    if (!s.places)
+      out.push(`  ${MAIN_SUMMARY_PENDING}${s.summary_reason ? ` (${s.summary_reason})` : ""}`);
+    else
+      out.push(`  ${MAIN_TIERS_WORST_FIRST.map((tier) => `${MAIN_TIER_WORDS[tier]}: ${s.places[tier]}`).join("; ")}${s.cant_reason ? `; ${mainCantWords(s.cant_reason, baseline)}` : ""}`);
+    if (s.memory)
+      out.push(`  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))
+      out.push(`  Version: ${v.label}${v.cuts.length ? `; history restart: ${v.cuts.join(", ")}` : ""}`);
+    for (const c of h.changes.filter((c) => c.from_run_set_id === s.run_set_id))
+      out.push(`  Main change: ${c.place} ${c.ref}, ${c.before_median ?? "–"} → ${c.after_median ?? "–"}`);
+  }
+  return out.join(`
+`);
+}
+function formatMainSessionPlaces(p) {
+  if (p.status !== "ok")
+    return `${MAIN_SUMMARY_PENDING}${p.summary_reason ? ` (${p.summary_reason})` : ""}`;
+  const baselineSessions = p.baseline_sessions;
+  return [
+    `Main session places: tiers are verdicts vs ${p.baseline_sessions === undefined ? "earlier sessions" : `the ${p.baseline_sessions} sessions before`}.`,
+    ...p.places.map((p) => `  ${p.place} ${p.ref}: ${MAIN_TIER_WORDS[p.tier]}${p.reason ? `; ${mainPlaceReasonWords(p.reason, { baseline: { sessions: baselineSessions } })}` : ""}`)
+  ].join(`
+`);
+}
+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(r) {
+  const out = [`Information only: main session ${r.run_set_id} vs ${r.previous_run_set_id ?? "no previous session"}.`, `Measure: ${r.measure}; ${r.status}.`];
+  if (r.cut === "unknown")
+    out.push("History restart: unknown; current summaries unavailable.");
+  else if (r.cut)
+    out.push(`History restart: ${r.cut.label}; ${r.cut.cuts.join(", ")}. Numbers cross this restart.`);
+  if (r.not_computed.length)
+    out.push(`not_computed: ${r.not_computed.join(", ")}`);
+  if (r.stale.length)
+    out.push(`stale: ${r.stale.join(", ")}`);
+  if (r.journey)
+    out.push("Whole journey:", previousLine(r.journey));
+  out.push(...r.places.map(previousLine));
+  if (r.next_offset !== null)
+    out.push(`Showing ${r.offset + 1}–${r.offset + r.places.length} of ${r.total}; next offset ${r.next_offset}.`);
+  return out.join(`
+`);
+}
+function formatPlaceTrend(t) {
+  const out = [`${t.journey} · ${t.phone.model} · ${t.baseline_branch}: stored per-session statistics`];
+  for (const session of t.sessions) {
+    if (session.restarts_known === false)
+      out.push(`History restarts unknown: ${session.run_set_id} (no current main summary in the history window)`);
+    for (const restart of t.restarts.filter((r) => r.from_run_set_id === session.run_set_id)) {
+      out.push(`History restarts: ${restart.label} (${restart.cuts.join(", ")})`);
+    }
+    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}` : "";
+      out.push(`${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)
+    out.push("No main sessions.");
+  if (t.not_computed.length)
+    out.push(`Not computed: ${t.not_computed.join(", ")}`);
+  if (t.stale.length)
+    out.push(`Stale: ${t.stale.join(", ")}`);
+  return out.join(`
+`);
+}
 
 // packages/mcp/src/server.ts
 var SERVER_NAME = "keepsnappy";
@@ -23188,7 +23467,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.",
     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"),
@@ -23202,7 +23481,7 @@ function createServer(target) {
   }, async (a) => answer(() => listFindings(target, a), formatFindingList));
   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.",
+    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.",
     inputSchema: { id: string2().regex(/^f_[0-9a-f]{16}$/).describe("Finding id from list_findings") },
     annotations: READ_ONLY
   }, async ({ id }) => answer(() => getFinding(target, id), (f) => formatFinding(f, { prompt: true })));
@@ -23229,12 +23508,68 @@ function createServer(target) {
     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.",
+    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)")
+    },
+    annotations: READ_ONLY
+  }, async (a) => answer(() => sessionPlaces(target, a), formatSessionPlaces));
   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.`,
+    inputSchema: { ...mainLane, sessions: number2().int().min(1).max(20).optional(), run_set: string2().min(1).optional() },
+    annotations: READ_ONLY
+  }, async ({ run_set, ...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 }), formatMainSessionPlaces) : answer(() => mainSessions(target, q), formatMainSessions);
+  });
+  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.`,
+    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()
+    },
+    annotations: READ_ONLY
+  }, async (q) => answer(() => mainVsPrevious(target, q), formatMainVsPrevious));
+  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.",
+    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")
+    },
+    annotations: READ_ONLY
+  }, async (a) => answer(() => placeTrend(target, a), formatPlaceTrend));
   return server;
 }
 

package/package.json

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