@gleapai/kai-bridge 0.2.9 → 0.5.0

package/src/selfupdate.mjs

@@ -71,6 +71,32 @@ export function decideUpdate({ current, latest, running = 0, autoUpdate = true,
   return { action: "update", reason: "newer" };
 }
 
+/**
+ * A daemon that keeps running after `npm i -g` replaced its files executes
+ * the OLD code until something restarts it — Luca's machine ran 0.2.1
+ * for a week with 0.2.7 on disk (2026-09-08): every fix shipped in
+ * between was invisible, and this very self-updater never ran. Decide
+ * whether the loaded version and the version on disk disagree and, if so,
+ * whether we may restart right now.
+ *   skip    — same version (or one side unknown)
+ *   defer   — differ, but a turn is running: restart when it ends
+ *   restart — differ and idle: hand the machine to the code on disk
+ */
+export function decideRestart({ loaded, installed, running = 0 }) {
+  if (!loaded || !installed || String(loaded) === String(installed)) return { action: "skip", reason: "same_version" };
+  if (running > 0) return { action: "defer", reason: "busy" };
+  return { action: "restart", reason: "stale_code" };
+}
+
+/** installedVersion() that answers null instead of throwing (mid-install, deleted prefix). */
+export function installedVersionOrNull(root = PACKAGE_ROOT) {
+  try {
+    return installedVersion(root);
+  } catch {
+    return null;
+  }
+}
+
 /** The npm that belongs to the node running us — same global prefix as the install. */
 export function npmBinary(execPath = process.execPath, os = platform()) {
   const candidate = join(dirname(execPath), os === "win32" ? "npm.cmd" : "npm");

package/src/service.mjs

@@ -60,6 +60,13 @@ ${envXml}
 `;
 }
 
+/** The desktop-session variables a headed browser needs (Linux only). */
+export function displayEnv(env = process.env) {
+  const out = {};
+  for (const k of ["DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"]) if (env[k]) out[k] = env[k];
+  return out;
+}
+
 export function renderSystemdUnit({ program, args, env = {} }) {
   const q = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
   return `[Unit]
@@ -95,6 +102,10 @@ export function install({ binPath, logDir, env = {} }) {
     PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
     HOME: homedir(),
     ...(process.env.SSH_AUTH_SOCK ? { SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK } : {}),
+    // Linux: a systemd --user unit starts without the desktop session's
+    // display — the headed sign-in window (preview-login.mjs) needs it.
+    // Captured at install time, like PATH.
+    ...(os === "linux" ? displayEnv(process.env) : {}),
     ...env,
   };
   if (os === "darwin") {

package/src/setup.mjs

@@ -3,7 +3,8 @@
 //   1. pair this machine with the user's Gleap account
 //   2. offer the background service (start at login, restart on crash)
 //   3. offer harness sign-ins (Claude Code / Codex / Cursor), inline
-//   4. say it's done, nicely
+//   4. make sure a browser exists for previews / Verify (Chrome, else Chromium)
+//   5. say it's done, nicely
 //
 // Runs from `kai-bridge setup`, from a bare `kai-bridge` on an unpaired
 // machine, and (when npm shows script output — `--foreground-scripts`)
@@ -245,7 +246,34 @@ export async function runSetup({ binPath, prompter = makePrompter() } = {}) {
     }
     out("");
 
-    // 4 ── Done -------------------------------------------------------
+    // 4 ── Browser for previews --------------------------------------
+    // Verify turns drive the preview in a real browser. System Chrome
+    // needs nothing; otherwise Playwright's Chromium is downloaded once
+    // here (the daemon would do it lazily before the first verify turn,
+    // which is a bad moment to wait for 150 MB).
+    out("Step 4 — browser for previews:");
+    try {
+      const { ensurePreviewBrowser } = await import("./preview.mjs");
+      const { createLogger } = await import("./daemon.mjs");
+      let announced = false;
+      const res = await ensurePreviewBrowser({
+        log: (level, event, data) => {
+          createLogger()(level, event, data);
+          if (event === "browser.install.start" && !announced) {
+            announced = true;
+            out("  Downloading Chromium for previews (one time, ~150 MB)…");
+          }
+        },
+      });
+      if (res.browser === "chrome") out("  Using Google Chrome on this machine.");
+      else if (res.ok) out(res.installed ? "  Chromium installed." : "  Bundled Chromium already installed.");
+      else out(`  No browser yet — previews will try again later (${res.error}).`);
+    } catch (err) {
+      out(`  Skipped (${err?.message || err}).`);
+    }
+    out("");
+
+    // 5 ── Done -------------------------------------------------------
     const name = config.device?.name ?? "This machine";
     out("──────────────────────────────────────────────────────────────");
     out(`🎉 All set. ${name} now shows up in Kai Code.`);

package/src/verify.mjs

@@ -0,0 +1,387 @@
+// Kai Code "Verify" — the daemon side of a kai-verifier turn.
+//
+// The runner's `verify_report` event carries LOCAL artifact paths (what
+// the Playwright MCP wrote into the turn's `--output-dir`). Nothing here
+// talks to the network: these are the pure pieces the daemon composes —
+// sweep the output dir, union it with what the agent listed (the agent may
+// forget the recording; the sweep guarantees it), derive labels / kinds /
+// content types, build the payload the Server's
+// `POST /gleapcode/bridge/turns/:turnId/verification` expects, and write
+// the dotenv secrets file for `--secrets`.
+
+import { readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
+
+import { redactDeep } from "./preview-login.mjs";
+
+export const ARTIFACT_EXTENSIONS = new Set([".webm", ".png", ".jpg", ".jpeg", ".zip", ".jsonl"]);
+export const VERIFY_STATUSES = new Set(["passed", "failed", "blocked"]);
+/** What the AGENT may say about a `blocked` verdict (V3: `not_verifiable` = nothing to exercise). `stopped` is derived server-side on turn end. */
+export const REPORT_BLOCKED_CODES = new Set(["needs_login", "preview_unreachable", "not_verifiable", "other"]);
+/** The daemon's own blocked code for a report that carries no check at all (V3 honesty: green only with proof). */
+export const NO_REPORT_CODE = "no_report";
+/** Evidence dirs older than this are swept on daemon start (kept only for failed uploads / doctor). */
+export const ARTIFACT_MAX_AGE_MS = 48 * 60 * 60_000;
+
+/** `https://x/login?next=/a#f` or `/login?x` → `/login`; null for junk. Never carries a query (tokens ride there). */
+export function sanitizeLoginPath(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const text = raw.trim();
+  try {
+    const path = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? new URL(text).pathname : new URL(text, "http://localhost").pathname;
+    return path && path.length <= 200 ? path : null;
+  } catch {
+    return null;
+  }
+}
+
+const CONTENT_TYPES = {
+  ".webm": "video/webm",
+  ".mp4": "video/mp4",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".zip": "application/zip",
+  ".jsonl": "application/x-ndjson",
+};
+
+export function contentTypeFor(filePath) {
+  return CONTENT_TYPES[extname(String(filePath)).toLowerCase()] ?? "application/octet-stream";
+}
+
+/** Artifact kind by extension — the report's own `kind` wins when present. */
+export function kindFor(filePath, declared) {
+  const ext = extname(String(filePath)).toLowerCase();
+  // The HTTP transcript is always `requests`, whatever the agent called it.
+  if (ext === ".jsonl") return "requests";
+  if (declared === "screenshot" || declared === "video" || declared === "trace") return declared;
+  if (ext === ".webm" || ext === ".mp4") return "video";
+  if (ext === ".zip") return "trace";
+  return "screenshot";
+}
+
+/** `requests.jsonl` → "HTTP transcript (12 requests)". */
+export function requestsLabel(filePath) {
+  try {
+    const rows = readFileSync(filePath, "utf8").split("\n").filter((l) => l.trim()).length;
+    return `HTTP transcript (${rows} request${rows === 1 ? "" : "s"})`;
+  } catch {
+    return "HTTP transcript";
+  }
+}
+
+/**
+ * Redact every JSON line of a `.jsonl` transcript in place (bodies and
+ * headers may echo an injected cookie / token). Unparseable lines are
+ * scrubbed as plain text. No-op without secrets.
+ */
+export function redactJsonlFile(filePath, secrets) {
+  if (!secrets || secrets.size === 0) return false;
+  let text;
+  try {
+    text = readFileSync(filePath, "utf8");
+  } catch {
+    return false;
+  }
+  const out = text
+    .split("\n")
+    .map((line) => {
+      if (!line.trim()) return line;
+      try {
+        return JSON.stringify(redactDeep(JSON.parse(line), secrets));
+      } catch {
+        return redactDeep(line, secrets);
+      }
+    })
+    .join("\n");
+  if (out !== text) writeFileSync(filePath, out);
+  return out !== text;
+}
+
+/**
+ * The `KAI_VERIFY_AUTH_HEADER` value for `http_request`: dev.yaml
+ * `auth.apiToken` says where the app keeps its API credential (a
+ * localStorage key or a cookie on one of the preview services); the value
+ * is read from the INJECTED storage state. Returns `{ header, value, token }`
+ * or null (no token config, no state, key absent). `services` =
+ * `[{ name, url }]` of the running preview (to find the origin by name).
+ */
+export function deriveApiAuthHeader(apiToken, state, services = []) {
+  if (!apiToken?.key || !state) return null;
+  let token = null;
+  if (apiToken.from === "cookie") {
+    const c = (state.cookies || []).find((x) => x?.name === apiToken.key && typeof x.value === "string" && x.value);
+    token = c?.value ?? null;
+  } else {
+    const svc = (services || []).find((s) => s?.name === apiToken.origin) ?? null;
+    const origin = svc?.url ? new URL(svc.url).origin.toLowerCase() : null;
+    const candidates = (state.origins || []).filter((o) => !origin || String(o?.origin || "").toLowerCase() === origin);
+    for (const o of candidates) {
+      const entry = (o?.localStorage || []).find((e) => e?.name === apiToken.key && typeof e.value === "string" && e.value);
+      if (entry) {
+        token = entry.value;
+        break;
+      }
+    }
+    // Apps often persist `{ token: "…" }` JSON under the key — unwrap one level.
+    if (token && /^\s*[{\[]/.test(token)) {
+      try {
+        const parsed = JSON.parse(token);
+        const inner = parsed && typeof parsed === "object" ? parsed.token ?? parsed.accessToken ?? parsed.access_token ?? parsed.jwt ?? null : null;
+        if (typeof inner === "string" && inner) token = inner;
+      } catch {
+        /* keep the raw string */
+      }
+    }
+  }
+  if (!token) return null;
+  const prefix = typeof apiToken.prefix === "string" ? apiToken.prefix : "Bearer ";
+  return { header: apiToken.header || "Authorization", value: `${apiToken.header || "Authorization"}: ${prefix}${token}`, token };
+}
+
+/**
+ * Remove evidence dirs under `root` whose mtime is older than `maxAgeMs`
+ * (kept dirs from failed uploads that nobody retried). Returns the removed
+ * names. Never throws.
+ */
+export function sweepOldArtifacts(root, { maxAgeMs = ARTIFACT_MAX_AGE_MS, now = Date.now() } = {}) {
+  const removed = [];
+  let names;
+  try {
+    names = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return removed;
+  }
+  for (const d of names) {
+    if (!d.isDirectory()) continue;
+    const path = join(root, d.name);
+    try {
+      if (now - statSync(path).mtimeMs > maxAgeMs) {
+        rmSync(path, { recursive: true, force: true });
+        removed.push(d.name);
+      }
+    } catch {
+      /* vanished */
+    }
+  }
+  return removed;
+}
+
+/** `02-after-reload.png` → "after reload"; `verification.webm` → "verification". */
+export function labelFor(filePath) {
+  if (extname(String(filePath)).toLowerCase() === ".jsonl") return requestsLabel(filePath);
+  const stem = basename(String(filePath)).replace(/\.[^.]+$/, "");
+  const words = stem.replace(/^\d+[-_ ]*/, "").replace(/[-_]+/g, " ").trim();
+  return words || stem || basename(String(filePath));
+}
+
+/**
+ * Every uploadable file under `dir` (one level — the MCP writes flat),
+ * oldest first so a multi-video run keeps its order. Missing dir → [].
+ */
+export function sweepArtifacts(dir) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const name of names) {
+    if (!ARTIFACT_EXTENSIONS.has(extname(name).toLowerCase())) continue;
+    const path = join(dir, name);
+    try {
+      const st = statSync(path);
+      if (!st.isFile() || st.size === 0) continue;
+      files.push({ path, mtimeMs: st.mtimeMs, size: st.size });
+    } catch {
+      /* vanished between readdir and stat */
+    }
+  }
+  return files.sort((a, b) => a.mtimeMs - b.mtimeMs || a.path.localeCompare(b.path)).map((f) => f.path);
+}
+
+/** `{ count }` for a requests transcript = recorded calls (non-empty lines); nothing for other kinds. */
+function requestCount(path, kind) {
+  if (kind !== "requests") return {};
+  try {
+    const count = readFileSync(path, "utf8").split("\n").filter((l) => l.trim()).length;
+    return count > 0 ? { count } : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The report's `artifacts[]` (agent-declared) ∪ the swept files, matched
+ * by resolved path. The MCP prints paths RELATIVE TO THE CLIENT WORKSPACE
+ * (the repo worktree — `../../.kai/artifacts/<turn>/01-home.png`), the
+ * agent may echo an absolute path or just the name: a declared path is
+ * tried as absolute, relative to `workDir`, relative to `outputDir`, and
+ * finally by basename against the sweep (the MCP writes flat). Declared
+ * entries keep their order, label and kind; files the agent did not list
+ * follow, labelled from their filename. Declared paths that match nothing
+ * on disk, or that are not media (`CONTENT_TYPES`), are dropped. Returns
+ * `[{ path, label, kind, contentType, declared }]`.
+ */
+export function unionArtifacts(report, sweptPaths, { outputDir, workDir } = {}) {
+  const out = [];
+  const seen = new Set();
+  const swept = new Set(sweptPaths.map((p) => resolve(p)));
+  const byName = new Map();
+  for (const p of swept) byName.set(basename(p), byName.has(basename(p)) ? null : p); // null = ambiguous
+  const isFile = (p) => {
+    try {
+      return statSync(p).isFile();
+    } catch {
+      return false;
+    }
+  };
+  const locate = (raw) => {
+    const candidates = isAbsolute(raw)
+      ? [resolve(raw)]
+      : [workDir ? resolve(workDir, raw) : null, outputDir ? resolve(outputDir, raw) : null].filter(Boolean);
+    for (const c of candidates) if (swept.has(c) || isFile(c)) return c;
+    return byName.get(basename(raw)) ?? null;
+  };
+  for (const a of Array.isArray(report?.artifacts) ? report.artifacts : []) {
+    const raw = typeof a?.path === "string" ? a.path.trim() : "";
+    if (!raw) continue;
+    const path = locate(raw);
+    if (!path || seen.has(path)) continue;
+    // Media only: a declared path that exists but is not evidence (the
+    // final browser-state JSON in the same dir, a log) never uploads.
+    if (!(extname(path).toLowerCase() in CONTENT_TYPES)) continue;
+    seen.add(path);
+    out.push({
+      path,
+      label: typeof a.label === "string" && a.label.trim() ? a.label.trim().slice(0, 120) : labelFor(path),
+      kind: kindFor(path, a.kind),
+      contentType: contentTypeFor(path),
+      ...requestCount(path, kindFor(path, a.kind)),
+      declared: true,
+    });
+  }
+  for (const p of sweptPaths) {
+    const path = resolve(p);
+    if (seen.has(path)) continue;
+    seen.add(path);
+    out.push({ path, label: labelFor(path), kind: kindFor(path), contentType: contentTypeFor(path), ...requestCount(path, kindFor(path)), declared: false });
+  }
+  return out;
+}
+
+/**
+ * The Server payload: the agent's report (clamped, status coerced) with
+ * `artifacts` rewritten to the uploaded `{label, url, contentType, kind}`.
+ * `uploads` = `[{ artifact, url }]` for the files that made it up. No
+ * report (agent never filed one, turn died) → `blocked` with the given
+ * fallback reason and NO `blockedCode` — the swept evidence still travels.
+ */
+export function buildVerificationPayload(report, uploads, { fallbackReason = "Kai finished without filing a verification report", evidence = null, readOnly = null } = {}) {
+  const artifacts = (uploads || [])
+    .filter((u) => u && typeof u.url === "string" && u.url)
+    .map((u) => ({ label: u.artifact.label, url: u.url, contentType: u.artifact.contentType, kind: u.artifact.kind, ...(u.artifact.count > 0 ? { count: u.artifact.count } : {}) }));
+  // `evidence` = what could not be uploaded; `readOnly` = the run's write policy (dev.yaml `verify.readOnly`, auto for API runs).
+  const withEvidence = (payload) => ({ ...payload, ...(evidence && typeof evidence === "object" ? { evidence } : {}), ...(typeof readOnly === "boolean" ? { readOnly } : {}) });
+  if (!report || typeof report !== "object") {
+    // No report from the agent. The CODE is the Server's to derive on turn
+    // end (`stopped` / `no_report` from the turn outcome); a cancelled turn
+    // differs only in the reason text the caller passes.
+    return withEvidence({ status: "blocked", reason: fallbackReason, checks: [], untested: [], artifacts });
+  }
+  const checks = (Array.isArray(report.checks) ? report.checks : [])
+    .filter((c) => c && typeof c.label === "string" && c.label.trim())
+    .slice(0, 50)
+    .map((c) => ({ label: c.label.trim().slice(0, 200), status: c.status === "failed" ? "failed" : "passed" }));
+  const untested = (Array.isArray(report.untested) ? report.untested : [])
+    .filter((u) => typeof u === "string" && u.trim())
+    .slice(0, 50)
+    .map((u) => u.trim().slice(0, 200));
+  // Verdict: the agent's `blocked` stands; otherwise a failed check fails
+  // the run even when the agent said `passed`; and a report without a
+  // single check is never green — it is `blocked` / `no_report` (V3
+  // honesty: proof or nothing).
+  const noChecks = checks.length === 0 && report.status !== "blocked";
+  const status = report.status === "blocked" || noChecks ? "blocked" : checks.some((c) => c.status === "failed") ? "failed" : VERIFY_STATUSES.has(report.status) ? report.status : "passed";
+  const payload = { status, checks, untested, artifacts };
+  if (typeof report.scope === "string" && report.scope.trim()) payload.scope = report.scope.trim().slice(0, 300);
+  if (noChecks) payload.reason = `Kai reported ${report.status === "failed" ? "a failure" : "success"} without a single check — nothing was verified.${typeof report.reason === "string" && report.reason.trim() ? ` ${report.reason.trim().slice(0, 800)}` : ""}`;
+  else if (typeof report.reason === "string" && report.reason.trim()) payload.reason = report.reason.trim().slice(0, 1000);
+  else if (status === "blocked") payload.reason = fallbackReason;
+  if (status === "blocked") {
+    // The V2 sign-in flow keys off these: a login wall the agent hit is
+    // `needs_login` + the wall's path (path only — never a URL with tokens).
+    payload.blockedCode = noChecks ? NO_REPORT_CODE : REPORT_BLOCKED_CODES.has(report.blockedCode) ? report.blockedCode : "other";
+    const loginPath = sanitizeLoginPath(report.loginPath);
+    if (loginPath && !noChecks) payload.loginPath = loginPath;
+  }
+  return withEvidence(payload);
+}
+
+/**
+ * dotenv for the Playwright MCP's `--secrets`: one `NAME="value"` per line,
+ * double-quoted with `\`, `"` and newlines escaped (the dotenv grammar the
+ * MCP parses). Names are restricted to identifier characters — anything
+ * else is dropped rather than risk a malformed file. Mode 0600. Returns the
+ * names written (what the task note tells the agent to type).
+ */
+export function writeSecretsFile(path, secrets) {
+  const names = [];
+  const lines = [];
+  for (const [rawName, rawValue] of Object.entries(secrets && typeof secrets === "object" ? secrets : {})) {
+    const name = String(rawName).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) continue;
+    const value = rawValue == null ? "" : String(rawValue);
+    if (!value) continue;
+    lines.push(`${name}="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, "\\n")}"`);
+    names.push(name);
+  }
+  if (names.length === 0) return [];
+  writeFileSync(path, lines.join("\n") + "\n", { mode: 0o600 });
+  return names;
+}
+
+/**
+ * Booting heartbeat: the runner's status lines (installing, still
+ * starting, ready) become `stage: booting` notes on the Verify card, at
+ * most one every `minIntervalMs` (the latest note wins, posted on a
+ * trailing timer), so a 4-minute install still moves the card every ≤ 60 s
+ * and a chatty boot does not flood the Server. `post(note)` returns a
+ * promise; failures are the caller's. Injected timers for tests.
+ */
+export function createStageHeartbeat(post, { minIntervalMs = 5_000, setTimer = setTimeout, clearTimer = clearTimeout, now = Date.now } = {}) {
+  let lastAt = 0;
+  let pending = null;
+  let timer = null;
+  let stopped = false;
+  const flush = () => {
+    timer = null;
+    if (stopped || pending == null) return;
+    const note = pending;
+    pending = null;
+    lastAt = now();
+    void Promise.resolve(post(note)).catch(() => {});
+  };
+  return {
+    note(message) {
+      if (stopped) return;
+      const text = String(message || "").slice(0, 300);
+      if (!text) return;
+      pending = text;
+      const wait = Math.max(0, minIntervalMs - (now() - lastAt));
+      if (wait === 0) return flush();
+      if (!timer) {
+        timer = setTimer(flush, wait);
+        timer?.unref?.();
+      }
+    },
+    stop() {
+      stopped = true;
+      if (timer) clearTimer(timer);
+      timer = null;
+      pending = null;
+    },
+  };
+}

package/src/workspace.mjs

@@ -16,6 +16,8 @@ import { execFileSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { seedNodeModules } from "./deps.mjs";
+
 function git(cwd, args, opts = {}) {
   return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts }).trim();
 }
@@ -82,6 +84,10 @@ export function materializeBinding({ kaiHome, repo, binding, sessionId, title, b
   mkdirSync(join(kaiHome, "worktrees", repo.name), { recursive: true });
   git(repo.primaryPath, ["fetch", "origin", base, "--quiet"]);
   git(repo.primaryPath, ["worktree", "add", "-b", branch, dir, `origin/${base}`]);
+  // A fresh worktree has no node_modules; clone the primary checkout's
+  // when the lockfiles match so the agent's tests and the preview boot
+  // don't each start with a 2-minute install (see deps.mjs).
+  const deps = seedNodeModules({ primaryPath: repo.primaryPath, cwd: dir });
   if (binding?.carryUncommitted) {
     // Tracked changes as a patch; untracked (non-ignored) files copied.
     const patch = git(repo.primaryPath, ["diff", "HEAD"], { maxBuffer: 64 * 1024 * 1024 });
@@ -104,7 +110,7 @@ export function materializeBinding({ kaiHome, repo, binding, sessionId, title, b
       }
     }
   }
-  return { cwd: dir, mode, branch, base, resumed: false };
+  return { cwd: dir, mode, branch, base, resumed: false, deps };
 }
 
 /** The branch checked out at `cwd` (null when it is not a git checkout). */
@@ -117,6 +123,15 @@ export function currentBranch(cwd) {
 }
 
 /** Diff of what the turn changed (for the dashboard's file-changes panel). */
+/** HEAD sha of a checkout, or null (verify reports stamp what was tested). */
+export function currentHead(cwd) {
+  try {
+    return git(cwd, ["rev-parse", "HEAD"]) || null;
+  } catch {
+    return null;
+  }
+}
+
 export function collectChanges(cwd) {
   // NOT via git(): its trailing .trim() also strips the LEADING space of
   // the first porcelain line, so a first entry that is a tracked
@@ -178,6 +193,50 @@ export function removeWorktree({ kaiHome, repo, sessionId, title }) {
  * A failed push is NOT fatal: the dashboard still shows the diff, and the
  * result carries the reason (no credentials, protected branch, …).
  */
+/**
+ * What a pushed session branch contains, for the pull request description:
+ * the commits since `base` (newest first, ≤ 20) and the diff stat. `base`
+ * is tried as `origin/<base>` first (the worktree may have no local ref).
+ * Never throws — an empty description beats a lost turn result.
+ */
+export function describeBranchChanges(cwd, base) {
+  const out = { commits: [], stat: null };
+  const candidates = [base && `origin/${base}`, base].filter(Boolean);
+  let range = null;
+  for (const ref of candidates) {
+    try {
+      git(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+      range = `${ref}...HEAD`;
+      break;
+    } catch {
+      /* try the next ref */
+    }
+  }
+  if (!range) return out;
+  try {
+    const log = git(cwd, ["log", "--no-merges", "--format=%h%x1f%s", "-n", "20", `${range.replace("...", "..")}`]);
+    out.commits = log
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const [sha, subject] = line.split("\x1f");
+        return { sha, subject: (subject || "").trim().slice(0, 200) };
+      });
+  } catch {
+    /* no commits */
+  }
+  try {
+    const short = git(cwd, ["diff", "--shortstat", range]);
+    const files = Number(/(\d+) files? changed/.exec(short)?.[1] ?? 0);
+    const insertions = Number(/(\d+) insertions?/.exec(short)?.[1] ?? 0);
+    const deletions = Number(/(\d+) deletions?/.exec(short)?.[1] ?? 0);
+    if (files) out.stat = { files, insertions, deletions };
+  } catch {
+    /* no stat */
+  }
+  return out;
+}
+
 /**
  * Git-level guard rails for what a turn may publish. Agent state dirs
  * never enter commits; the preview config (.gleap/dev.yaml) stays out