@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/compaction-savings.ts

@@ -0,0 +1,127 @@
+/**
+ * What each compaction in a transcript cost and saved.
+ *
+ * Compaction is the largest single thing that happens to a chat and the only one the
+ * transcript records without the UI ever saying so: a session silently loses most of
+ * its history, the next turn's prefix collapses, and the only visible trace is a long
+ * summary message. This reads the figures back out so the divider above that summary
+ * can state them.
+ *
+ * The link between a boundary and the message it introduces is `parentUuid`. Claude
+ * Code writes the `compact_boundary` record with `parentUuid: null` — it is the root
+ * of the post-compaction segment — and the summary immediately after it carries the
+ * boundary's uuid as its parent. Keying the result by that summary's uuid is what
+ * lets both message readers stamp it on without either of them knowing the layout,
+ * since `parseSessionMessage` already uses the record uuid as `ChatMessage.id`.
+ */
+
+import { existsSync } from "node:fs";
+import type { CompactionInfo } from "../types/chat.ts";
+import { readLines } from "./read-lines.ts";
+
+/**
+ * Cheap test for the only two lines per compaction worth parsing.
+ *
+ * A transcript reaches tens of megabytes and `JSON.parse` on every line of one is the
+ * dominant cost of reading it at all — but a compaction leaves two records in a file
+ * that holds thousands, so a substring check keeps this a scan rather than a parse.
+ */
+const BOUNDARY_MARKER = '"compact_boundary"';
+
+/**
+ * Map of compact-summary message uuid → that compaction's figures.
+ *
+ * Answers an empty map for a missing or unreadable file: a transcript that cannot be
+ * read still has messages worth showing, and a divider is not worth failing a history
+ * load over.
+ */
+export async function readCompactions(jsonlPath: string): Promise<Map<string, CompactionInfo>> {
+  const byMessageId = new Map<string, CompactionInfo>();
+  if (!existsSync(jsonlPath)) return byMessageId;
+
+  // The boundary is read one line before the summary that claims it, so it waits here
+  // until a record names it as parent. Held rather than assumed adjacent: the pairing
+  // is by uuid, so a record written between the two cannot mis-attach the figures.
+  let pending: { uuid: string; info: CompactionInfo } | null = null;
+
+  try {
+    for await (const line of readLines(jsonlPath)) {
+      if (line.includes(BOUNDARY_MARKER)) {
+        const info = parseBoundary(line);
+        pending = info ? { uuid: info.uuid, info: info.compaction } : null;
+        continue;
+      }
+      if (!pending) continue;
+      // Only lines that could be the child are parsed — the uuid of the boundary is a
+      // full uuid, so this substring test has no realistic false positive.
+      if (!line.includes(pending.uuid)) continue;
+      const child = parseChild(line);
+      if (child?.parentUuid === pending.uuid) {
+        byMessageId.set(child.uuid, pending.info);
+        pending = null;
+      }
+    }
+  } catch {
+    // Truncated or mid-write — keep whatever pairs were already complete.
+  }
+  return byMessageId;
+}
+
+/** The boundary's own uuid and figures, or null when the record is not one we can use. */
+function parseBoundary(line: string): { uuid: string; compaction: CompactionInfo } | null {
+  let entry: any;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (entry?.type !== "system" || entry.subtype !== "compact_boundary") return null;
+  const meta = entry.compactMetadata;
+  if (typeof entry.uuid !== "string" || !meta) return null;
+
+  const preTokens = numberOr(meta.preTokens, 0);
+  const postTokens = numberOr(meta.postTokens, 0);
+  // A boundary with no `preTokens` is a record shape this cannot describe — a zero
+  // saving would render as a confident "saved 0", which is worse than no divider.
+  if (preTokens <= 0) return null;
+
+  return {
+    uuid: entry.uuid,
+    compaction: {
+      trigger: meta.trigger === "manual" ? "manual" : "auto",
+      preTokens,
+      postTokens,
+      // Clamped: `postTokens` is absent on older records, and a summary that somehow
+      // measured larger than its input must not report a negative saving.
+      savedTokens: Math.max(0, preTokens - postTokens),
+      ...(typeof meta.durationMs === "number" ? { durationMs: meta.durationMs } : {}),
+    },
+  };
+}
+
+/** The uuid/parentUuid pair of a candidate child record. */
+function parseChild(line: string): { uuid: string; parentUuid: string } | null {
+  try {
+    const entry = JSON.parse(line);
+    if (typeof entry?.uuid !== "string" || typeof entry.parentUuid !== "string") return null;
+    return { uuid: entry.uuid, parentUuid: entry.parentUuid };
+  } catch {
+    return null;
+  }
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/** Stamp each compaction onto the message that opens its segment. */
+export function applyCompactions(
+  messages: { id: string; compaction?: CompactionInfo }[],
+  byMessageId: Map<string, CompactionInfo>,
+): void {
+  if (byMessageId.size === 0) return;
+  for (const msg of messages) {
+    const info = byMessageId.get(msg.id);
+    if (info) msg.compaction = info;
+  }
+}

package/src/services/db.service.ts

@@ -8,7 +8,7 @@ import { backupDbSync } from "./db-backup/db-backup-sync.ts";
 import { CODEX_DEFAULT_MODEL } from "../types/config.ts";
 // Must equal the last `PRAGMA user_version` below: the pre-migration snapshot is skipped for
 // any database already at this version, so a stale value silently drops that backup.
-export const CURRENT_SCHEMA_VERSION = 51;
+export const CURRENT_SCHEMA_VERSION = 54;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -36,8 +36,7 @@ export function getDb(): Database {
   const ppmDir = getPpmDir();
   if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
   db = new Database(getDbPath());
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA foreign_keys = ON");
+  applyDbPragmas(db);
   backupBeforeMigrations(db);
   runMigrations(db);
   return db;
@@ -68,6 +67,26 @@ function backupBeforeMigrations(database: Database): void {
   }
 }
 
+/**
+ * The pragmas every PPM connection to this database needs.
+ *
+ * `busy_timeout` is the one with a story. SQLite's default is to fail a
+ * contended lock INSTANTLY — measured, 0ms to `SQLiteError: database is
+ * locked` — and PPM routinely has two processes on this file for a moment: a
+ * `systemctl restart` starts the new supervisor while the outgoing server is
+ * still committing and checkpointing, which for a 300MB database is over a
+ * second. That single throw arrived as an unhandled rejection inside
+ * supervisor startup, which then stopped before spawning the edge forwarder —
+ * so PPM ran with nothing listening on its public port. 5s rather than the
+ * query audit's 2s: one snapshot of this database measures ~1.2s, so the wait
+ * has to cover a checkpoint plus whatever writes queued behind it.
+ */
+export function applyDbPragmas(database: Database): void {
+  database.exec("PRAGMA journal_mode = WAL");
+  database.exec("PRAGMA busy_timeout = 5000");
+  database.exec("PRAGMA foreign_keys = ON");
+}
+
 /** Close the DB (for graceful shutdown or tests) */
 export function closeDb(): void {
   if (db) { db.close(); db = null; }
@@ -76,8 +95,7 @@ export function closeDb(): void {
 /** For tests: open an isolated in-memory DB with schema applied */
 export function openTestDb(): Database {
   const testDb = new Database(":memory:");
-  testDb.exec("PRAGMA journal_mode = WAL");
-  testDb.exec("PRAGMA foreign_keys = ON");
+  applyDbPragmas(testDb);
   runMigrations(testDb);
   return testDb;
 }
@@ -1131,10 +1149,33 @@ export function runMigrations(database: Database): void {
     database.exec(`PRAGMA user_version = 48;`);
   }
 
+  // This checkout's prompt-cache work first shipped as migrations 46-48 on turn_usage, before
+  // main used those numbers for accounts (it is 50-52 below now). A database that ran the local
+  // ones sits past 45 without main's columns, so the version gates above skip them for good and
+  // 49 then updates a column that does not exist. Added by schema rather than by version here;
+  // on a database that followed main every statement is a no-op.
+  if (current >= 46 && current < 49) {
+    for (const col of [
+      "granted_at INTEGER",
+      "refresh_expires_at INTEGER",
+      "reauth_required INTEGER NOT NULL DEFAULT 0",
+      "last_refresh_attempt_at INTEGER",
+    ]) {
+      try { database.exec(`ALTER TABLE accounts ADD COLUMN ${col}`); } catch { /* exists */ }
+    }
+    try { database.exec(`ALTER TABLE codex_accounts ADD COLUMN status TEXT NOT NULL DEFAULT 'active'`); } catch { /* exists */ }
+    try { database.exec(`ALTER TABLE codex_accounts ADD COLUMN daily_guard_enabled INTEGER NOT NULL DEFAULT 0`); } catch { /* exists */ }
+  }
+
   if (current < 49) {
     // Daily guard was introduced as an opt-in during development. Ship it enabled so every
     // weekly-only account starts paced; Plus accounts simply do not surface or use it.
-    database.exec(`UPDATE codex_accounts SET daily_guard_enabled = 1`);
+    //
+    // Guarded like every statement around it, and for the same reason: the ladder runs against
+    // databases that do not have this table yet. Unguarded, the throw escapes `runMigrations`
+    // and leaves the database half-migrated at whatever version the previous step wrote —
+    // there is no transaction around the ladder to undo it.
+    try { database.exec(`UPDATE codex_accounts SET daily_guard_enabled = 1`); } catch { /* no accounts table yet */ }
     database.exec(`PRAGMA user_version = 49;`);
   }
 
@@ -1155,6 +1196,33 @@ export function runMigrations(database: Database): void {
     try { database.exec("ALTER TABLE claude_limit_snapshots ADD COLUMN extra_json TEXT"); } catch { /* exists */ }
     database.exec(`PRAGMA user_version = 51;`);
   }
+
+  if (current < 52) {
+    // The idle-cache notice had to live entirely in server memory, because nothing on disk
+    // said when a session last cached or how much. `recorded_at` answers the first; this
+    // column answers the second with a figure the summed token columns cannot give —
+    // see `TurnUsage.contextTokens`. Null on every existing row: unmeasured, not zero.
+    try { database.exec("ALTER TABLE turn_usage ADD COLUMN context_tokens INTEGER"); } catch { /* column exists */ }
+    database.exec(`PRAGMA user_version = 52;`);
+  }
+
+  if (current < 53) {
+    // The cache window was inferred from the credential's shape — an `sk-ant-oat` prefix
+    // meaning a subscription and therefore an hour. The API states it outright in
+    // `usage.cache_creation`, and that answer has to outlive the process the way the rest of
+    // the last turn's facts now do. Null on existing rows: unreported, so the guess stands.
+    try { database.exec("ALTER TABLE turn_usage ADD COLUMN cache_ttl_ms INTEGER"); } catch { /* column exists */ }
+    database.exec(`PRAGMA user_version = 53;`);
+  }
+
+  if (current < 54) {
+    // A compaction makes the cached prefix inapplicable rather than stale, and the window in
+    // which that matters is between the compaction and the user's next message — a window a
+    // restart lands inside often enough to be worth surviving. Null on existing rows: no
+    // compaction is known, which is what every turn before this recorded anyway.
+    try { database.exec("ALTER TABLE turn_usage ADD COLUMN compacted_at INTEGER"); } catch { /* column exists */ }
+    database.exec(`PRAGMA user_version = 54;`);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1729,6 +1797,9 @@ export interface TurnUsageRow {
   cold_reason: string | null;
   account_id: string | null;
   account_label: string | null;
+  context_tokens: number | null;
+  cache_ttl_ms: number | null;
+  compacted_at: number | null;
   recorded_at: string;
 }
 
@@ -1745,13 +1816,16 @@ export function insertTurnUsage(record: {
   coldReason?: string;
   accountId?: string;
   accountLabel?: string;
+  contextTokens?: number;
+  cacheTtlMs?: number;
+  compactedAt?: number;
 }): void {
   getDb().query(
     `INSERT INTO turn_usage
        (session_id, model, input_tokens, output_tokens, cache_read_tokens,
         cache_write_tokens, context_window, cost_usd, cold_start, cold_reason,
-        account_id, account_label)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        account_id, account_label, context_tokens, cache_ttl_ms, compacted_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     record.sessionId, record.model ?? null,
     record.inputTokens, record.outputTokens,
@@ -1759,9 +1833,50 @@ export function insertTurnUsage(record: {
     record.contextWindow ?? null, record.costUsd ?? null,
     record.coldStart ? 1 : 0, record.coldReason ?? null,
     record.accountId ?? null, record.accountLabel ?? null,
+    record.contextTokens ?? null, record.cacheTtlMs ?? null, record.compactedAt ?? null,
   );
 }
 
+/**
+ * When this session last wrote its prompt cache, and what it would cost to write again.
+ *
+ * The idle notice used to be answerable only from the live `SessionEntry`, which is dropped
+ * five minutes after the last tab disconnects — while the cache it describes lives for an
+ * hour. So the notice appeared only for a session left connected and went silent for exactly
+ * the session reopened the next morning, which is the one it exists for. These three columns
+ * are already written on every turn; reading them back is the whole fix.
+ */
+export function getLastTurnCacheState(sessionId: string): {
+  endedAtMs: number;
+  prefixTokens: number;
+  contextTokens?: number;
+  cacheTtlMs?: number;
+  compactedAt?: number;
+} | null {
+  const row = getDb().query(
+    `SELECT input_tokens, cache_read_tokens, cache_write_tokens, context_tokens, cache_ttl_ms, compacted_at, recorded_at
+       FROM turn_usage WHERE session_id = ? ORDER BY id DESC LIMIT 1`,
+  ).get(sessionId) as Pick<
+    TurnUsageRow,
+    "input_tokens" | "cache_read_tokens" | "cache_write_tokens" | "context_tokens" | "cache_ttl_ms" | "compacted_at" | "recorded_at"
+  > | null;
+  if (!row?.recorded_at) return null;
+
+  // `datetime('now')` is UTC and writes no zone suffix, which `Date` then reads as LOCAL
+  // time — seven hours adrift in Asia/Saigon, enough to make the idle window come out
+  // negative and silence the notice on precisely the machines it was rebuilt for.
+  const endedAtMs = Date.parse(`${row.recorded_at.replace(" ", "T")}Z`);
+  if (!Number.isFinite(endedAtMs)) return null;
+
+  return {
+    endedAtMs,
+    prefixTokens: row.input_tokens + row.cache_read_tokens + row.cache_write_tokens,
+    ...(row.context_tokens != null && { contextTokens: row.context_tokens }),
+    ...(row.cache_ttl_ms != null && { cacheTtlMs: row.cache_ttl_ms }),
+    ...(row.compacted_at != null && { compactedAt: row.compacted_at }),
+  };
+}
+
 /** Most recent turns first — the debug dialog shows the tail of a session. */
 export function listTurnUsage(sessionId: string, limit = 30): TurnUsageRow[] {
   return getDb().query(

package/src/services/fs-ops/fs-ops-trash.service.ts

@@ -47,28 +47,40 @@ function osaLiteral(value: string): string {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-function windowsCommand(path: string, isDirectory: boolean): string[] {
+/**
+ * How a backend binary is found, replaceable for the same reason `TrashRunner` is.
+ *
+ * Which tool is present is as much a property of the host as what running it does, and
+ * leaving the lookup outside the seam meant a test could fake the run and still be refused
+ * before reaching it — on any machine without `gio` or `trash-put`, which includes the
+ * container the suite runs in.
+ */
+export type TrashLookup = (name: string) => string | null;
+
+const defaultLookup: TrashLookup = (name) => Bun.which(name);
+
+function windowsCommand(path: string, isDirectory: boolean, which: TrashLookup): string[] {
   const method = isDirectory ? "DeleteDirectory" : "DeleteFile";
   const script =
     "Add-Type -AssemblyName Microsoft.VisualBasic; " +
     `[Microsoft.VisualBasic.FileIO.FileSystem]::${method}(${psLiteral(path)},'OnlyErrorDialogs','SendToRecycleBin')`;
-  const shell = Bun.which("powershell") ?? Bun.which("pwsh");
+  const shell = which("powershell") ?? which("pwsh");
   if (!shell) throw noTrash("powershell not found on PATH");
   return [shell, "-NoProfile", "-NonInteractive", "-Command", script];
 }
 
 /** Paths are always absolute here, so no leading-dash option confusion. */
-function posixCommand(path: string): string[] {
+function posixCommand(path: string, which: TrashLookup): string[] {
   if (process.platform === "darwin") {
-    const trash = Bun.which("trash");
+    const trash = which("trash");
     if (trash) return [trash, path];
-    const osascript = Bun.which("osascript");
+    const osascript = which("osascript");
     if (!osascript) throw noTrash("neither trash nor osascript found on PATH");
     return [osascript, "-e", `tell application "Finder" to delete POSIX file ${osaLiteral(path)}`];
   }
-  const gio = Bun.which("gio");
+  const gio = which("gio");
   if (gio) return [gio, "trash", path];
-  const trashPut = Bun.which("trash-put");
+  const trashPut = which("trash-put");
   if (trashPut) return [trashPut, path];
   throw noTrash("neither gio nor trash-put found on PATH");
 }
@@ -85,7 +97,7 @@ async function isDirectoryTarget(path: string): Promise<boolean> {
 
 export async function trashPath(
   path: string,
-  options?: { run?: TrashRunner },
+  options?: { run?: TrashRunner; which?: TrashLookup },
 ): Promise<{ trashed: true; path: string }> {
   const target = resolvePath(path);
   assertAllowed(target);
@@ -94,8 +106,9 @@ export async function trashPath(
   await assertNotProtected(target);
   const isDir = await isDirectoryTarget(target);
 
+  const which = options?.which ?? defaultLookup;
   const cmd =
-    process.platform === "win32" ? windowsCommand(target, isDir) : posixCommand(target);
+    process.platform === "win32" ? windowsCommand(target, isDir, which) : posixCommand(target, which);
 
   const run = options?.run ?? spawnRunner;
   let result: { exitCode: number; stderr: string };

package/src/services/git-refs/for-each-ref.ts

@@ -0,0 +1,118 @@
+/**
+ * Every checkout target — local branches, remote-tracking branches and tags —
+ * out of a single `git for-each-ref`, with the commit each one points at.
+ *
+ * The format string is built from the field list rather than written out,
+ * because the parser reads fields *positionally*: a field added to one and not
+ * the other shifts everything after it, and git answers just as happily either
+ * way — the picker would simply show a date where the author belongs, with
+ * nothing failing.
+ *
+ * Six of the twelve fields are the `*`-dereferenced twins of six others, and
+ * they are what makes an **annotated** tag readable. `refs/tags/v1` resolves to
+ * the tag *object*, not to a commit: its `objectname` is the tag's own hash,
+ * it has a tagger rather than an author (so `%(authorname)` and
+ * `%(committerdate)` come back empty) and its `contents:subject` is the tag
+ * message. A lightweight tag has no such object and leaves every `*` field
+ * empty — which is why each pair is resolved as "dereferenced when non-empty,
+ * else plain" rather than by asking what kind of ref it is.
+ */
+import type { GitRef } from "../../types/git.ts";
+
+const FIELDS = [
+  "refname",
+  "objectname",
+  "*objectname",
+  "HEAD",
+  "upstream:short",
+  "upstream:track",
+  "authorname",
+  "*authorname",
+  "committerdate:iso-strict",
+  "*committerdate:iso-strict",
+  "contents:subject",
+  "*contents:subject",
+] as const;
+
+/** NUL between fields, newline between records: no ref name or subject may contain either. */
+export const FOR_EACH_REF_FORMAT = FIELDS.map((f) => `%(${f})`).join("%00");
+
+export const FOR_EACH_REF_ARGS = [
+  "for-each-ref",
+  `--format=${FOR_EACH_REF_FORMAT}`,
+  "refs/heads",
+  "refs/remotes",
+  "refs/tags",
+];
+
+const PREFIX: Record<GitRef["type"], string> = {
+  branch: "refs/heads/",
+  remote: "refs/remotes/",
+  tag: "refs/tags/",
+};
+
+/**
+ * `%(upstream:track)` as git writes it: `[ahead 1, behind 26]`, either half on
+ * its own, `[gone]` when the remote branch was deleted, or empty when the
+ * branch has no upstream at all.
+ */
+export function parseUpstreamTrack(track: string): Pick<GitRef, "ahead" | "behind" | "gone"> {
+  if (track.includes("gone")) return { ahead: 0, behind: 0, gone: true };
+  const ahead = /ahead (\d+)/.exec(track);
+  const behind = /behind (\d+)/.exec(track);
+  return {
+    ahead: ahead ? Number(ahead[1]) : 0,
+    behind: behind ? Number(behind[1]) : 0,
+    gone: false,
+  };
+}
+
+function refType(refName: string): GitRef["type"] | null {
+  for (const [type, prefix] of Object.entries(PREFIX)) {
+    if (refName.startsWith(prefix)) return type as GitRef["type"];
+  }
+  return null;
+}
+
+/** Newest commit first. Compared as instants, never as strings: `iso-strict` carries the author's own offset. */
+function newestFirst(a: GitRef, b: GitRef): number {
+  const at = Date.parse(a.date);
+  const bt = Date.parse(b.date);
+  if (Number.isNaN(at) || Number.isNaN(bt)) return a.name.localeCompare(b.name);
+  return bt - at;
+}
+
+export function parseForEachRef(stdout: string): GitRef[] {
+  const refs: GitRef[] = [];
+
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const f = line.split("\0");
+    // A short record means a field carried a newline after all. Skipping it
+    // loses one row; reading it would silently shift every field of that row.
+    if (f.length < FIELDS.length) continue;
+
+    const refName = f[0]!;
+    const type = refType(refName);
+    if (!type) continue;
+    // `origin/HEAD` is a symbolic pointer at another row of this same list.
+    if (type === "remote" && refName.endsWith("/HEAD")) continue;
+
+    const hash = f[2] || f[1]!;
+    refs.push({
+      refName,
+      name: refName.slice(PREFIX[type].length),
+      type,
+      current: f[3] === "*",
+      hash,
+      shortHash: hash.slice(0, 7),
+      subject: f[11] || f[10]!,
+      author: f[7] || f[6]!,
+      date: f[9] || f[8]!,
+      upstream: f[4] || null,
+      ...parseUpstreamTrack(f[5]!),
+    });
+  }
+
+  return refs.sort(newestFirst);
+}

package/src/services/git.service.ts

@@ -1,13 +1,16 @@
 import path from "node:path";
 import simpleGit, { type SimpleGit } from "simple-git";
 import { isBinaryContent } from "./binary-content.ts";
+import { FOR_EACH_REF_ARGS, parseForEachRef } from "./git-refs/for-each-ref.ts";
 import type {
+  CheckoutMode,
   FileFullDiff,
   GitStatus,
   GitFileChange,
   GitCommit,
   GitBranch,
   GitGraphData,
+  GitRef,
   GitWorktree,
 } from "../types/git.ts";
 
@@ -319,8 +322,28 @@ class GitService {
     await this.git(projectPath).checkoutBranch(name, from ?? "HEAD");
   }
 
-  async checkout(projectPath: string, ref: string): Promise<void> {
-    await this.git(projectPath).checkout(ref);
+  /**
+   * `track` is not a nicety: `git checkout origin/foo` lands on a **detached
+   * HEAD**, because the remote-tracking ref is not a branch anyone can commit
+   * to. `-t` is what creates the local `foo` that follows it. The picker
+   * chooses between the three modes; the service only has to keep them apart.
+   */
+  async checkout(
+    projectPath: string,
+    ref: string,
+    mode: CheckoutMode = "checkout",
+  ): Promise<void> {
+    const flags = mode === "detach" ? ["--detach"] : mode === "track" ? ["-t"] : [];
+    // `--` or the ref is read as a pathspec when no such ref exists: `git checkout src`
+    // in a repository with no branch named `src` restores every unstaged change under
+    // that directory, silently and with exit 0. `assertSafeRev` refuses a leading dash
+    // and a range, but a plain directory name is a legitimate ref shape.
+    await this.git(projectPath).checkout([...flags, ref, "--"]);
+  }
+
+  /** Every local branch, remote-tracking branch and tag, newest commit first. */
+  async refs(projectPath: string): Promise<GitRef[]> {
+    return parseForEachRef(await this.git(projectPath).raw(FOR_EACH_REF_ARGS));
   }
 
   async deleteBranch(

package/src/services/host-info/spawn-runner.ts

@@ -13,10 +13,37 @@ export type Runner = (argv: string[], timeoutMs?: number) => Promise<RunResult>;
 
 const DEFAULT_TIMEOUT_MS = 5000;
 
-/** Real implementation: argv array only (never string-interpolated into a shell), bounded by timeoutMs. */
+/** Real implementation: argv array only (never string-interpolated into a shell), bounded by timeoutMs.
+ *
+ *  `Bun.spawn` **throws synchronously** when the binary is not on `PATH`
+ *  ("Executable not found in $PATH"), and for these providers that is a normal
+ *  condition rather than an error: every one of them shells out to a per-OS tool
+ *  (`systemctl`, `plutil`, `powershell.exe`, `findmnt`, `xdg-user-dir`,
+ *  `nvidia-smi`), so on any other OS the binary is simply absent. Left to throw,
+ *  it escapes the `Promise<RunResult>` this signature promises: the Services page
+ *  on macOS and Windows answered 500 and showed the exception, instead of the
+ *  "this host has no service manager" the collector is written to report.
+ *
+ *  So a missing binary is returned as a run that failed — `code: null` with the
+ *  message on stderr, which is the shape every caller already handles for a
+ *  non-zero exit. */
+const spawnPiped = (argv: string[]) =>
+  Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+
 export const defaultRunner: Runner = async (argv, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-  const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+  // Named via `spawnPiped` rather than `ReturnType<typeof Bun.spawn>`: the bare
+  // form loses the option narrowing, and `proc.stdout` widens back to a union
+  // with `number` (a raw fd) that `new Response()` will not take.
+  let proc: ReturnType<typeof spawnPiped>;
+  try {
+    proc = spawnPiped(argv);
+  } catch (e: any) {
+    return { stdout: "", stderr: e?.message ?? String(e), code: null, timedOut: false };
+  }
   let timedOut = false;
+  /** Resolves when the timeout fires, so the readers below stop waiting with the process. */
+  let giveUp!: () => void;
+  const abandoned = new Promise<void>((resolve) => { giveUp = resolve; });
   const killTimer = setTimeout(() => {
     timedOut = true;
     try {
@@ -24,12 +51,29 @@ export const defaultRunner: Runner = async (argv, timeoutMs = DEFAULT_TIMEOUT_MS
     } catch {
       // Process already exited between the timer firing and the kill call.
     }
+    giveUp();
   }, timeoutMs);
 
+  /**
+   * The output, or nothing once the run has been given up on.
+   *
+   * Killing the process does **not** close its pipes. A shell that forks rather than execs
+   * leaves a grandchild holding the write end, so draining stdout goes on until *that* exits —
+   * measured, `proc.exited` came back at the 150ms timeout while the drain ran the full five
+   * seconds, which means `timeoutMs` bounded nothing at all. The pending read is left to settle
+   * on its own and discarded rather than cancelled: cancelling a subprocess stream has crashed
+   * Bun on Windows before, and there is nothing here worth that risk.
+   */
+  const readOrAbandon = (stream: ReadableStream<Uint8Array>): Promise<string> =>
+    Promise.race([
+      new Response(stream).text().catch(() => ""),
+      abandoned.then(() => ""),
+    ]);
+
   try {
     const [stdout, stderr, code] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
+      readOrAbandon(proc.stdout),
+      readOrAbandon(proc.stderr),
       proc.exited,
     ]);
     return { stdout, stderr, code, timedOut };