pi-goal-list-loop-audit 0.35.13 → 0.35.32

package/docs/DESIGN.md

@@ -255,9 +255,9 @@ replacement without delivering a successor `session_start`:
   flattens extensions in load order and suffixes EVERY registration of a duplicated
   command name (`name:1`, `name:2`, …) — the bare name becomes owned by nobody and
   dispatch stops routing it while a collision exists. The model is read from the
-  installed pi core (hermetic, never modified) and auto-records the routing table to
-  `audit/command-registration-routing.md`, making collisions reproducible and
-  diagnosable without touching pi.
+  installed pi core (hermetic, never modified) and records a process-scoped
+  routing diagnostic, making collisions reproducible without rewriting tracked
+  repository files or touching pi.
 - **Unmatched telemetry stays unmatched** (v0.34.56): tool starts/ends without a
   counterpart are represented as explicitly unmatched facts, never falsely paired —
   the report surface stays truthful (the AuditProgress/AuditorProgress dual-interface
@@ -429,15 +429,20 @@ v0.1.0 ships the same auditor behaviour as pi-goal-x. The author of pi-goal-x do
 
 We accept this caveat for v0.1.0. v0.2.0 will add **regression_shield**: an explicit requirement that the auditor's report must include raw output (a `cat`, a `grep -A 5 <file>`, a `bash <user-script>`) for every item in `verificationContract`. Without that evidence, the auditor's `<approved/>` is rejected by the orchestrator.
 
-### Decision 3: Hard 5-minute backoff cap
+### Decision 3: Hard 5-minute backoff cap (SUPERSEDED v0.35.4)
 
 The #1 complaint about pi-goal-x in our audit (user-stated) was "1-hour waits". The cause is exponential backoff with no ceiling.
 
-v0.1.0 ships a hard 5-minute cap. After 5 minutes of consecutive backoff:
+v0.1.0 shipped a hard 5-minute cap. After 5 minutes of consecutive backoff:
 1. TUI badge turns red with "Last activity: 5m+".
 2. User can press `r` to force-continue or `s` to skip to next pending task.
 3. Optional: configure Telegram/web push notification.
 
+> **Superseded (v0.35.4):** the cap had zero production call sites and was
+> removed (`extensions/goal-loop-backoff.ts` header). The live envelope is
+> the eager 5s first retry + hourly-aligned ladder with stall-ladder/heartbeat
+> coverage — see README's retry section.
+
 ### Decision 4: No drafting phase in v0.1.0 (deferred to v0.2.0)
 
 The user identified vague-correction as a key strength of pi-goal-x. But shipping it in v0.1.0 doubles the scope and we won't get the auditor right if we split focus.
@@ -494,8 +499,11 @@ This is a **clean break** by decision of the user. We do not interop with `pi-go
 ### Decision 8: Status machine
 
 ```ts
+// Historical sketch from v0.2.0 planning. The SHIPPED Status union is
+// "active" | "auditing" | "complete" | "paused" | "aborted" (drafting is a
+// UI phase, not a persisted status).
 type Status =
-  | "drafting"        // v0.2.0
+  | "drafting"        // v0.2.0 (planned; not a persisted Status value)
   | "active"
   | "auditing"
   | "complete"
@@ -565,10 +573,53 @@ This protects against model-generated summaries losing fidelity.
   - *Current*: Parallel subagent exploration fan-out (spawning multiple `Explore` agents in one turn) and parallel disjoint-worktree implementation (`general-purpose` workers with `isolation: "worktree"`). Detached auditor runs concurrently in background OS process.
   - *Opportunities*: Concurrent `/list` dispatch across non-conflicting tasks using isolated worktrees to eliminate head-of-line blocking for large queues, plus background contract rehearsals.
 
+## Addendum v0.35.7–v0.35.31 (consolidated behavior addenda)
+
+Per the doc convention, these releases appended the following architectural
+shapes (details in CHANGELOG.md; each is pinned by tests):
+
+- **Supervisor freeze — `/glla pause` (v0.35.15/17)**: freezes ALL automatic
+  machinery (re-arms, recovery probes, auto-resume, continuation dispatch,
+  proactive notifies) without touching active work or a running detached
+  auditor. Distinct from goal pause; only `/glla resume` clears it.
+- **Load hold (v0.35.23)**: a cold session load that restores pending state
+  WITHOUT explicit consent holds automation (`loadHoldAt`) until an explicit
+  work command releases it. Refines the restore-gate consent story above.
+- **Auditor picker parity (v0.35.24)**: `promptModelRef` accepts
+  `excludeRefs`; forbiddenModels policy refs are filtered from lists AND
+  refused on typed input (`forbidden_model_switch`).
+- **Zero-stream zombie park + RESUMABLE_STOP (v0.35.25/26)**: a run with no
+  provider activity parks as `stopped: automatic zero-stream abort…` and
+  `/loop resume` retries it; the zombie watchdog stands down while tracked
+  subagent waits are in flight via ONE shared `SUBAGENT_WAIT_TOOL_NAMES`
+  predicate (no per-site name lists).
+- **Windows auditor launch, gate-before-quote (v0.35.27)**: unsafe-arg
+  rejection runs on EVERY argument before the quoting decision; bare tokens
+  reach cmd.exe untouched so pnpm .CMD shims resolve.
+- **Heartbeat due-wait backstop + recovery notice (v0.35.28)**: wall-clock
+  comparison against persisted `pauseResumeAt` in the tick resumes lapsed
+  wait/error-brake parks after a 90s grace (consent-gated); successful
+  recoveries stamp `autoResumedAt`/`autoResumedEvent` and the continuation
+  prompt renders a RECOVERY NOTICE instead of waiting on a fired signal.
+- **Tracked-subagent visibility (v0.35.29)**: `getSubagentAgentsSnapshot()`
+  (read-only probe views with hung classification) feeds `/glla agents`,
+  `/glla agents --tail <id>` (read-only child transcript tail), and a widget
+  segment — pure rendering in `extensions/goal-agents-panel.ts`.
+- **Durable last-outcome retention (v0.35.30)**: archiving writes
+  `state.lastOutcome`; the widget keeps one dim ✓/▪ line for 24h after the
+  slot empties so a finished audit stays visible after the turn ends.
+- **Loop plateau vs never-moved baselines (v0.35.31)**: flat metric readings
+  count toward plateau only once the metric has demonstrably moved; a metric
+  that NEVER moves gets its own loud bounded stop. Audit loops keep their
+  purpose-built deferred-baseline + reprieve semantics verbatim.
+
 ## Files
 
 - `docs/DESIGN.md` — **this file**
 - `README.md` — quickstart
-- `audit/pi-name-v3-registry-based.md` — naming rationale
-- `audit/pi-goal-loop-design.md` — earlier design (now superseded)
+- `docs/INDEX.md` — shipped documentation and architecture entry points
+- `README.md` — user-facing installation and operating guidance
+
+Historical audit notes are repository-only and are intentionally not part of
+the published package.
 

package/docs/GLLA-POSITIONING-AND-DECOMPOSITION-2026-08-08.md

@@ -78,7 +78,12 @@ detached-auditor loop, but it is also a deliberate trade:
 
 ## 4. The refactor: decompose goal.ts (the plan skeleton)
 
-Current state: `extensions/loops/goal.ts` ≈ 10.5K lines, 189 top-level
+> **STATUS (2026-08-22): IMPLEMENTED.** This plan shipped in decomposition
+> steps 1–6 (v0.34.109–v0.34.114). `extensions/loops/goal.ts` is now a thin
+> activation/wiring installer (~413 lines); every module below exists under
+> `extensions/` and `extensions/loops/`. Kept for rationale/history.
+
+Current state at planning time: `extensions/loops/goal.ts` ≈ 10.5K lines, 189 top-level
 functions, covering at least these domains (grep counts):
 
 ```

package/docs/INDEX.md

@@ -18,6 +18,10 @@ For shipped docs, the relevant entry points are:
   failback; v0.35.9 hardened cross-version npm tarball checks; v0.35.10
   handles multi-entry npm dry-run reports; v0.35.11 accepts both npm report
   shapes; v0.35.12 supports npm 12's keyed pack reports; v0.35.13 fixes stale-API recovery loops.
+  v0.35.14–v0.35.31 continue through the supervisor freeze (`/glla pause`),
+  load hold, auditor picker parity, Windows launch fix, zombie-watchdog
+  subagent carve-out, due-wait backstop, the `/glla agents` visibility panel,
+  and durable last-outcome retention — see CHANGELOG.md for the full trail.
 - `../README.md` — what the plugin is, install, quickstart, and the
   architectural guarantee (drafting + confirm + detached auditor).
 - `../INSTALL.md` — manual install / symlink setup; the recommended

package/docs/VISION-ASSIST.md

@@ -66,8 +66,8 @@ Edit: `/glla` → **Keep-going** → **Vision assist**, then choose **off**.
 | Command builder | `visionDescribeCommand(imagePath, question?)` |
 | Routing rule (pure) | `routeVisionCheck(request)` — mmx by default; forbidden target → mmx + `blockedSwitch`; preapproved target → `model-switch` allowed |
 | Ledger payload builder | `visionAssistLedger(route, request)` |
-| Continuation injection | `extensions/loops/goal.ts` `continuationPrompt()` (gated on `visionAssist !== false`) |
-| Forbidden-switch hook | `observeModelChange()` forbidden branch → `vision_assist` entry |
+| Continuation injection | `extensions/goal-continuation.ts` pushes `VISION_ASSIST_GUIDANCE` into the continuation directives (gated on `visionAssist !== false`) |
+| Forbidden-switch hook | forbidden-model gate in the settings editors/model pickers (`extensions/loops/goal-settings-ui.ts`, `extensions/loops/goal-activation.ts`) → `forbidden_model_switch` + `vision_assist` ledger entries |
 | Setting | `extensions/goal-settings.ts` (default true), menu row in `extensions/settings-menu.ts`, editor + `/glla` row in `extensions/loops/goal.ts` |
 | Tests | `tests/vision-assist.test.ts` |
 

package/extensions/auditor-extensions.ts

@@ -0,0 +1,289 @@
+// pi-goal-list-loop-audit — v0.36.0
+// extensions/auditor-extensions.ts
+//
+// Discovery + normalization for the auditor extension allowlist
+// (`auditorAllowedExtensions`, GitHub issue: "Allow extension-based model
+// providers in detached auditor sessions").
+//
+// The detached auditor worker spawns `pi --mode rpc --no-extensions …`. Pi's
+// `--extension <spec>` flag still loads explicitly given specs even under
+// `--no-extensions`, BUT a raw `npm:<pkg>` spec makes pi perform a fresh
+// *temporary* npm install into `~/.pi/agent/tmp/extensions/npm/<hash>` on
+// every spawn — network-bound, hundreds of MB, and completely dead offline
+// (field-verified by the 2026-08-22 audit: `-e npm:pi-cursor-sdk` with
+// PI_OFFLINE=1 registered 0 models; the resolved install path registered
+// 209). Relative `extensions[]` entries are likewise resolved by pi against
+// the *auditor's cwd*, not the settings base dir, so a verbatim
+// `../../ghq/...` spec silently loads nothing.
+//
+// We therefore resolve every allowlist entry to a concrete, existing
+// absolute path BEFORE it reaches the worker:
+//   • `npm:<name>[@version]` → `~/.pi/agent/npm/node_modules/<name>` (or the
+//     project `.pi/npm/node_modules/<name>` equivalent) — existing install
+//     only, never triggering a new one.
+//   • `git:<url>` → `~/.pi/agent/git/<host>/<user>/<project>` (or project
+//     `.pi/git/...` equivalent).
+//   • paths → `~` expanded; relative paths resolved against the settings
+//     base dir (user scope: `~/.pi/agent`, project scope: `<cwd>/.pi`),
+//     matching pi's own `getBaseDirForScope` resolution.
+// Entries that do not resolve to an existing path are dropped (fail-closed)
+// rather than emitted as unloadable specs.
+//
+// Discovery is read-only and best-effort: unreadable files simply contribute
+// no entries. The picker menu (Auditor tab) is the only consumer besides the
+// dispatch path, which re-reads the normalized settings at request time.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** One extension the user could allow-list for the auditor. */
+export interface DiscoveredPiExtension {
+  /** The spec to pass to `pi --extension` / store in settings.
+   * Settings-sourced entries are RESOLVED to concrete install paths (see
+   * module header); directory-discovered entries are already absolute. */
+  spec: string;
+  /** Short human label (package name or file/dir basename). */
+  label: string;
+  /** Where the entry came from — for the picker's descriptive text. */
+  source: "package" | "extensions-setting" | "user-dir" | "project-dir";
+  /** The raw settings entry this was resolved from (specs resolved from
+   * packages[]/extensions[] keep the original string for display). */
+  raw?: string;
+}
+
+/** Parse an npm package spec into its install directory name.
+ * Mirrors pi's PackageManager.parseNpmSpec: `@scope/pkg@1.2.3` →
+ * `@scope/pkg`; `pkg@^2` → `pkg`; `pkg` → `pkg`. */
+function npmSpecName(spec: string): string {
+  const match = spec.match(/^(@?[^@]+(?:\/?[^@]+)?)(?:@(.+))?$/);
+  return (match?.[1] ?? spec).trim() || spec;
+}
+
+/** Parse a git source into `{ host, repoPath }` where repoPath is
+ * `user/project` (`.git` and ref stripped). Mirrors the subset of pi's
+ * parseGitUrl/splitRef that settings `packages[]` entries can contain.
+ * Returns undefined when the string is not a git source. */
+function parseGitSpec(source: string): { host: string; repoPath: string } | undefined {
+  let url = source.trim();
+  if (url.startsWith("git:")) url = url.slice(4).trim();
+  else if (!/^(https?|ssh|git):\/\//i.test(url) && !/^git@[^:]+:/.test(url) && !/^[^.\s]+\.[^.\s]+\//.test(url)) {
+    return undefined; // not a git-shaped source
+  }
+  url = url.split("#")[0] ?? url; // strip #ref
+  let host = "";
+  let rest = "";
+  const scp = url.match(/^git@([^:]+):(.+)$/);
+  if (scp) {
+    host = scp[1] ?? "";
+    rest = scp[2] ?? "";
+  } else if (url.includes("://")) {
+    try {
+      const parsed = new URL(url);
+      host = parsed.hostname;
+      rest = parsed.pathname.replace(/^\/+/, "");
+    } catch {
+      return undefined;
+    }
+  } else {
+    const slash = url.indexOf("/");
+    if (slash < 0) return undefined;
+    host = url.slice(0, slash);
+    rest = url.slice(slash + 1);
+  }
+  const at = rest.indexOf("@"); // strip @ref (pi's splitRef semantics)
+  if (at >= 0) rest = rest.slice(0, at);
+  rest = rest.replace(/\.git$/, "").replace(/^\/+/, "");
+  const parts = rest.split("/").filter(Boolean);
+  if (!host || parts.length < 2 || parts.some((p) => p === "..")) return undefined;
+  return { host, repoPath: parts.join("/") };
+}
+
+function firstExisting(candidates: string[]): string | undefined {
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* unreadable — treat as missing */
+    }
+  }
+  return undefined;
+}
+
+/** Expand `~` and resolve a path against a base dir (pi's
+ * resolvePathFromBase semantics for settings entries). */
+function resolveSettingsPath(input: string, baseDir: string, home: string): string {
+  if (input.startsWith("~")) return path.join(home, input.slice(1).replace(/^\/+/, ""));
+  return path.resolve(baseDir, input);
+}
+
+/** Resolve one allowlist spec to a concrete existing absolute path the
+ * worker can pass as `pi --extension <path>` without triggering installs.
+ * `base` is the settings base dir for relative paths (user scope:
+ * `~/.pi/agent`; project scope: `<cwd>/.pi`). Returns undefined when the
+ * entry does not resolve to something loadable — callers drop it
+ * (fail-closed) rather than emit an unloadable spec. */
+export function resolveAuditorExtensionSpec(
+  spec: string,
+  opts: { home: string; cwd?: string; base?: string },
+): string | undefined {
+  const agentDir = path.join(opts.home, ".pi", "agent");
+  const projectDir = opts.cwd ? path.join(opts.cwd, ".pi") : undefined;
+  const trimmed = spec.trim();
+  if (trimmed.startsWith("npm:")) {
+    const name = npmSpecName(trimmed.slice(4));
+    if (!name) return undefined;
+    return firstExisting([
+      path.join(agentDir, "npm", "node_modules", name),
+      ...(projectDir ? [path.join(projectDir, "npm", "node_modules", name)] : []),
+    ]);
+  }
+  const git = parseGitSpec(trimmed);
+  if (git) {
+    return firstExisting([
+      path.join(agentDir, "git", git.host, ...git.repoPath.split("/")),
+      ...(projectDir ? [path.join(projectDir, "git", git.host, ...git.repoPath.split("/"))] : []),
+    ]);
+  }
+  // Local path: `~`/absolute as-is, relative against the settings base dir
+  // (NOT the auditor's future cwd — pi resolves -e against cwd, so emitting
+  // a relative spec would silently load nothing).
+  if (/^[a-z]+:/.test(trimmed)) return undefined; // unknown scheme — no safe resolution
+  const resolved = resolveSettingsPath(trimmed, opts.base ?? agentDir, opts.home);
+  return firstExisting([resolved]);
+}
+
+/** Resolve an allowlist to worker-ready install paths: every entry maps to
+ * a concrete existing path; unresolvable entries are dropped fail-closed. */
+export function resolveAuditorAllowedExtensions(
+  specs: string[] | undefined,
+  home: string,
+  cwd?: string,
+): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const spec of normalizeAuditorAllowedExtensions(specs)) {
+    const resolved = resolveAuditorExtensionSpec(spec, { home, cwd, base: path.join(home, ".pi", "agent") });
+    if (!resolved || seen.has(resolved)) continue; // not installed here — skip, don't emit a dead spec
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+/** Bounded, deterministic normalization of the allowlist value. */
+export function normalizeAuditorAllowedExtensions(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const spec = entry.trim();
+    if (!spec || seen.has(spec)) continue;
+    if (out.length >= 32) break; // bounded: the request hash stays sane
+    seen.add(spec);
+    out.push(spec);
+  }
+  return out;
+}
+
+function readJsonArray(file: string): string[] {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const out: string[] = [];
+    for (const key of ["packages", "extensions"]) {
+      const value = (parsed as Record<string, unknown>)[key];
+      if (!Array.isArray(value)) continue;
+      for (const entry of value) {
+        if (typeof entry === "string" && entry.trim()) out.push(entry.trim());
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** Auto-discovered extension entries in a directory: *.ts / *.js files and
+ * subdirectories (loaded by pi as <dir>/index.ts). */
+function discoverDir(dir: string, source: DiscoveredPiExtension["source"]): DiscoveredPiExtension[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: DiscoveredPiExtension[] = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".js"))) {
+      out.push({ spec: full, label: entry.name, source });
+    } else if (entry.isDirectory()) {
+      out.push({ spec: full, label: `${entry.name}/`, source });
+    }
+  }
+  return out;
+}
+
+function labelForSpec(spec: string): string {
+  // "npm:@scope/pkg@version" → "@scope/pkg"; "git:url" → url tail; paths → basename.
+  const colon = spec.indexOf(":");
+  if (colon > 0) {
+    const scheme = spec.slice(0, colon);
+    const rest = spec.slice(colon + 1);
+    if (scheme === "npm" || scheme === "git") {
+      const withoutVersion = rest.replace(/@[^/@]*$/, "");
+      return withoutVersion || rest;
+    }
+  }
+  return path.basename(spec) || spec;
+}
+
+/**
+ * Discover every extension a normal pi session would load in this
+ * environment: user settings packages/extensions, the user extensions dir,
+ * project settings packages/extensions, and the project extensions dir.
+ * Deduplicated by spec, stable order: settings packages first, then
+ * settings extension paths, then directory discovery (user before project).
+ */
+export function discoverAuditorExtensions(home: string, cwd?: string): DiscoveredPiExtension[] {
+  const agentDir = path.join(home, ".pi", "agent");
+  const out: DiscoveredPiExtension[] = [];
+  const seen = new Set<string>();
+  const push = (spec: string, source: DiscoveredPiExtension["source"]) => {
+    if (!spec || seen.has(spec)) return;
+    seen.add(spec);
+    out.push({ spec, label: labelForSpec(spec), source });
+  };
+  // Settings entries: packages[] specs and extensions[] paths are resolved
+  // to concrete install paths (npm: → managed node_modules, git: → managed
+  // git root, relative paths → settings base dir) so the stored allowlist
+  // entry is directly loadable by `pi --extension <path>` without a fresh
+  // temporary install. Unresolvable entries are skipped, not emitted.
+  const pushResolved = (raw: string, source: DiscoveredPiExtension["source"], base: string) => {
+    const spec = resolveAuditorExtensionSpec(raw, { home, cwd, base });
+    if (!spec || seen.has(spec)) return;
+    seen.add(spec);
+    out.push({ spec, label: labelForSpec(raw), source, raw });
+  };
+  const userSettings = readJsonArray(path.join(agentDir, "settings.json"));
+  for (const raw of userSettings) pushResolved(raw, /^[a-z]+:/.test(raw) ? "package" : "extensions-setting", agentDir);
+  for (const entry of discoverDir(path.join(agentDir, "extensions"), "user-dir")) push(entry.spec, entry.source);
+  if (cwd) {
+    const projectSettings = readJsonArray(path.join(cwd, ".pi", "settings.json"));
+    const projectBase = path.join(cwd, ".pi");
+    for (const raw of projectSettings) pushResolved(raw, /^[a-z]+:/.test(raw) ? "package" : "extensions-setting", projectBase);
+    for (const entry of discoverDir(path.join(cwd, ".pi", "extensions"), "project-dir")) push(entry.spec, entry.source);
+  }
+  return out;
+}
+
+/** Expand the allowlist into `pi` CLI args: ["--extension", spec, …].
+ * Empty/absent list → [] (the worker keeps plain --no-extensions). */
+export function auditorExtensionArgs(allowed: string[] | undefined): string[] {
+  const args: string[] = [];
+  for (const spec of normalizeAuditorAllowedExtensions(allowed)) {
+    args.push("--extension", spec);
+  }
+  return args;
+}

package/extensions/goal-agents-panel.ts

@@ -0,0 +1,185 @@
+// pi-goal-list-loop-audit — v0.35.29
+// goal-agents-panel.ts — issue #15 subagent visibility (design:
+// docs/DESIGN-subagent-visibility.md, scope agreed 2026-08-22).
+//
+// Pure rendering + data assembly for:
+//   1. /glla agents            — tracked-subagent snapshot table
+//   2. /glla agents --tail <id> — read-only child transcript tail
+//   3. the widget agents segment (line built here, appended by the widget)
+//
+// Everything here is deterministic given its inputs; fs access happens only
+// in tailChildTranscript through an injected reader so tests stay hermetic.
+
+import * as path from "node:path";
+
+export interface AgentsPanelRow {
+  recordId: string;
+  agentType?: string;
+  summary?: string;
+  status: "running" | "hung" | "ended";
+  spawnedAt: number;
+  lastProgressAt: number;
+  toolUses: number;
+  outputTokens: number;
+  silentMs: number;
+  evidence: "record-frozen" | "event-only" | "live";
+  endedOk?: boolean;
+  endedAt?: number;
+}
+
+/** Human label: agentType + short summary. */
+function rowLabel(row: AgentsPanelRow): string {
+  const summary = (row.summary ?? "").replace(/\s+/g, " ").trim();
+  return [row.agentType ?? "subagent", summary ? truncate(summary, 28) : ""].filter(Boolean).join(" · ");
+}
+
+export function truncate(text: string, max: number): string {
+  return text.length <= max ? text : text.slice(0, Math.max(1, max - 1)) + "…";
+}
+
+function fmtDuration(ms: number): string {
+  const totalSec = Math.max(0, Math.round(ms / 1000));
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min >= 60) return `${Math.floor(min / 60)}h${String(min % 60).padStart(2, "0")}m`;
+  if (min > 0) return `${min}m${String(sec).padStart(2, "0")}s`;
+  return `${sec}s`;
+}
+
+const PANEL_ROW_CAP = 20;
+
+/** Render the /glla agents table. Running/hung first (hung topmost), then
+ * ended; capped at PANEL_ROW_CAP rows with an explicit truncation notice. */
+export function renderAgentsPanel(rows: AgentsPanelRow[], now: number, managerAvailable: boolean): string[] {
+  if (rows.length === 0) {
+    return ["No subagents tracked yet — spawn one via the Agent tool and it appears here.", "(evidence: glla's event probes" + (managerAvailable ? " + pi-subagents manager records" : "") + ")"];
+  }
+  const rank = (r: AgentsPanelRow): number => (r.status === "hung" ? 0 : r.status === "running" ? 1 : 2);
+  const ordered = [...rows].sort((a, b) => rank(a) - rank(b) || a.silentMs - b.silentMs);
+  const shown = ordered.slice(0, PANEL_ROW_CAP);
+  const lines: string[] = [];
+  for (const row of shown) {
+    const glyph = row.status === "ended" ? "✓" : row.status === "hung" ? "⚠" : "●";
+    const stateWord = row.status === "ended"
+      ? `ENDED ${row.endedOk === false ? "✗" : "ok"} ${fmtDuration((row.endedAt ?? now) - row.spawnedAt)}`
+      : `${row.status === "hung" ? "HUNG?" : "RUNNING"} ${fmtDuration(now - row.spawnedAt)}`;
+    lines.push(`${glyph} ${rowLabel(row)}  ${stateWord}`);
+    lines.push(`  tools ${row.toolUses} · out ${row.outputTokens >= 1000 ? `${(row.outputTokens / 1000).toFixed(1)}k` : row.outputTokens} · silent ${fmtDuration(row.silentMs)}${row.evidence !== "live" ? ` (${row.evidence})` : ""}`);
+    if (row.status === "hung") {
+      lines.push("  └ check the Agents panel: a child whose counters stopped moving is hung, not thinking");
+    }
+  }
+  if (ordered.length > shown.length) {
+    lines.push(`… ${ordered.length - shown.length} more (oldest ended trimmed — cap ${PANEL_ROW_CAP})`);
+  }
+  return lines;
+}
+
+/** The ambient widget segment: hidden at zero tracked children by the caller. */
+export function renderAgentsWidgetLine(rows: AgentsPanelRow[]): string | undefined {
+  const active = rows.filter((r) => r.status !== "ended");
+  if (active.length === 0) return undefined;
+  const busiest = [...active].sort((a, b) => b.silentMs - a.silentMs)[0]!;
+  const hung = busiest.status === "hung" ? " ⚠" : "";
+  return `● ${active.length} agent${active.length === 1 ? "" : "s"} · ${(busiest.agentType ?? "subagent")} silent ${fmtDuration(busiest.silentMs)}${hung}`;
+}
+
+export interface TranscriptTailResult {
+  ok: boolean;
+  lines: string[];
+  /** What was searched / read — surfaced to the user on failure. */
+  detail: string;
+}
+
+/** Read-only tail of a child's session transcript. Candidate selection: all
+ * .jsonl files in sessionsDir whose content mentions the child's summary or
+ * agent type; most recently modified wins. NEVER resumes or attaches.
+ * readFile is injected for tests; production passes fs.readFileSync-wrapped. */
+export function tailChildTranscript(
+  sessionsDir: string,
+  row: { recordId: string; agentType?: string; summary?: string },
+  opts: {
+    lines?: number;
+    readFile?: (file: string) => Buffer;
+    listDir?: (dir: string) => string[];
+    statMtime?: (file: string) => number;
+    now?: number;
+  } = {},
+): TranscriptTailResult {
+  const wantLines = Math.max(1, Math.min(200, opts.lines ?? 20));
+  const readFile = opts.readFile ?? (() => { throw new Error("no reader"); });
+  const listDir = opts.listDir ?? (() => []);
+  const statMtime = opts.statMtime ?? (() => 0);
+  let entries: string[];
+  try {
+    entries = listDir(sessionsDir);
+  } catch (error) {
+    return { ok: false, lines: [], detail: `cannot list ${sessionsDir}: ${error instanceof Error ? error.message.slice(0, 120) : String(error)}` };
+  }
+  const needles = [row.summary?.slice(0, 48), row.agentType, row.recordId]
+    .filter((n): n is string => typeof n === "string" && n.trim().length >= 6)
+    .map((n) => n.toLowerCase());
+  const candidates = entries
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => path.join(sessionsDir, f))
+    .map((f) => ({ f, mtime: statMtime(f) }))
+    .sort((a, b) => b.mtime - a.mtime);
+  let matched: string | undefined;
+  for (const candidate of candidates.slice(0, 25)) {
+    try {
+      const content = readFile(candidate.f).toString("utf8").toLowerCase();
+      if (needles.some((needle) => content.includes(needle))) { matched = candidate.f; break; }
+    } catch { /* unreadable file — skip */ }
+  }
+  if (!matched) {
+    return {
+      ok: false,
+      lines: [],
+      detail: `no session file in ${sessionsDir} matches this child (searched ${candidates.length} transcripts for: ${needles.map((n) => `"${truncate(n, 24)}"`).join(", ") || "any needle"}) — the child may not persist a session, or it lives under another working directory`,
+    };
+  }
+  try {
+    const raw = readFile(matched).toString("utf8").split("\n").filter(Boolean);
+    const formatted = raw.map(formatTranscriptEntry).filter(Boolean) as string[];
+    return { ok: true, lines: formatted.slice(-wantLines), detail: `${matched} (last ${Math.min(wantLines, formatted.length)} of ${formatted.length})` };
+  } catch (error) {
+    return { ok: false, lines: [], detail: `cannot read ${matched}: ${error instanceof Error ? error.message.slice(0, 120) : String(error)}` };
+  }
+}
+
+/** Tolerant pi-session JSONL → `[role] text` line. Unparseable lines are
+ * truncated raw so forensic value survives shape drift. */
+export function formatTranscriptEntry(line: string): string | undefined {
+  const trimmed = line.trim();
+  if (!trimmed) return undefined;
+  try {
+    const entry = JSON.parse(trimmed) as {
+      type?: string;
+      role?: string;
+      message?: { role?: string; content?: unknown };
+      content?: unknown;
+    };
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return `[raw] ${truncate(trimmed, 120)}`;
+    const role = entry.message?.role ?? entry.role ?? entry.type ?? "?";
+    const content = entry.message?.content ?? entry.content;
+    const text = extractText(content);
+    if (!text) return undefined;
+    return `[${role}] ${truncate(text.replace(/\s+/g, " ").trim(), 160)}`;
+  } catch {
+    return `[raw] ${truncate(trimmed, 120)}`;
+  }
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => typeof block === "string"
+        ? block
+        : typeof block === "object" && block !== null && typeof (block as { text?: unknown }).text === "string"
+          ? (block as { text: string }).text
+          : "")
+      .join(" ");
+  }
+  return "";
+}