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

package/PLAN.md

@@ -0,0 +1,316 @@
+# PLAN — pi-goal-list-loop-audit
+
+Living plan for the project. Update this file as decisions land or milestones close.
+New here? Start with README.md and INSTALL.md — this file is the historical
+plan, not the onboarding path.
+Last updated: v0.29.6 (header refresh). The milestones
+below cover the v0.1.0–v0.7.0 scaffold era; later decisions live in CHANGELOG.md
+(current through v0.29.6) and the current-state addendum in docs/DESIGN.md.
+
+---
+
+## 0. Product definition (frozen)
+
+- **What it is**: a pi-coding-agent extension that supervises long-running work to *verified* completion.
+- **Core mechanism**: a shared goal state machine + an `agent_end`-driven continuation loop + an **isolated auditor** (fresh pi session, no extensions, no skills, power-mode audit tools: read/grep/find/ls/bash) that must approve before a goal is marked complete.
+- **Three loops on one machine**:
+  - **goal** — one ordered goal, audited (`/goal`)
+  - **list** — a queue of goals, each audited in turn (`/list`)
+  - **loop** — a forever-polish loop around a measurable target (`/loop`)
+- **Naming is frozen**: commands are `/goal*`, `/list*`, `/loop*`. No `pi-gla-` prefix, no `oracle/sisyphus/squad/forge` metaphors anywhere (code, files, docs, keywords).
+
+### Non-goals (v0.x)
+
+- No interop with `pi-goal-x` state (`.pi/goals/`). Clean break, `.pi-gla/` only.
+- No web dashboard, no remote control, no multi-machine coordination.
+- No planner/decomposer that invents the goal for the user (drafting *clarifies*; it does not originate).
+
+---
+
+## 1. Milestones & acceptance criteria
+
+### M0 — v0.1.0-alpha.1 scaffold ✅ (done)
+
+- [x] Package layout, LICENSE, README, CHANGELOG, DESIGN, tsconfig
+- [x] `extensions/loops/goal.ts` — commands + agent tools + agent_end loop
+- [x] `extensions/goal-loop-core.ts` — types, JSONL ledger, markdown renderer
+- [x] `extensions/goal-loop-auditor.ts` — isolated auditor session
+- [x] `extensions/goal-loop-backoff.ts` — 5-min hard cap
+- [x] `prompts/goal-loop-continuation.md`, `schemas/goal.schema.json`
+- [x] 24 unit tests green (`npm test`)
+- **Exit evidence**: `npm test` → 24/24 pass (verified 2026-07-20).
+
+### M1 — v0.1.0 (first real release)
+
+Scope: make the goal loop actually work end-to-end in a live pi session. No new features.
+
+- [ ] **Type-check clean**: `npm run check` (tsc --noEmit) → 0 errors.
+  - Known risk: `ExtensionContext`, `defineTool` import path, `pi.registerCommand` arg shapes were written against memory of pi-goal-x, not verified against the installed pi 0.74 API.
+- [x] **Live smoke test** ✅ 2026-07-20 — full loop verified end-to-end in tmux: `/goal` → agent works → `complete_goal` → isolated auditor (opencode/deepseek-v4-flash-free, extension-less) approves → archived with clean 1-entry history + real auditor report.
+- [x] **Fix whatever the smoke test breaks** ✅ — 6 real fixes: (1) API imports from public entrypoint + pi-ai/pi-agent-core types; (2) `sendMessage` on `pi` API not `ctx`; (3) stale-ctx crash → `lastCtx`/`rememberCtx` pattern; (4) `details:{}` in tool results, async handlers, `tool_call` event name; (5) auditor model default → `ctx.model` + string-ref resolver; (6) audit-history pollution — record only non-empty reports, cap at 20, include `error` field.
+- [x] **Escape hatch verified** ✅ (with caveat) — Esc during audit aborts the pi turn; the auditor session may complete detached. Loop recovers cleanly via `agent_end` (verified live: 3 empty audits then approval). pi-goal-x's fancy Escape dialog is v0.2.0 scope. Abort signal is threaded into the auditor for when pi wires tool-level abort properly.
+- [x] **Backoff cap verified** ✅ (incidentally, live) — openrouter 403 storm triggered exactly "Goal paused: 5 consecutive errors" auto-pause.
+- [ ] Update CHANGELOG, tag `v0.1.0`, `npm publish`.
+
+**Live smoke script** (target: < 5 min):
+```
+pi -e /home/dracon/Dev/pi-goal-list-loop-audit
+> /goal "Create file hello.txt containing the word world. Done when: grep -q world hello.txt"
+# expect: agent writes file, calls complete_goal, auditor approves, goal archived
+> /goal status        # expect: complete, audit history shows 1 approved
+cat .pi-gla/active.jsonl | tail -3
+ls .pi-gla/archive/   # expect: one .md file
+```
+
+### M2 — v0.2.0 (list + drafting + regression_shield) ✅ (2026-07-20)
+
+- [x] **Loop 2: `/list`** — `add|show|next|remove <n>|clear`; each item is a full goal; completing/aborting one auto-activates the next; session restart resumes a non-empty queue. Live-verified: two items auto-advanced through audit to archive.
+- [x] **Drafting**: `/goal` no-args → agent grills one question at a time → `propose_goal_draft` → real Confirm dialog. Live-verified end-to-end (drafted goal completed with shield).
+- [x] **regression_shield**: auditor must quote raw output per contract item in an `<evidence>` block; orchestrator converts evidence-free `<approved/>` into disapproval. Pure logic in `goal-loop-shield.ts`; 14 unit tests + live verification (verbatim `<evidence>` in history).
+- [x] **Escape dialog**: abort → complete-without-audit / continue choice.
+- [x] **Provider warning**: one-time `session_start` notice when the session provider isn't a confirmed built-in and no auditorModel is set. Live-verified on kilocode.
+- [x] **Inline contract extraction**: one-liner `Done when:` now extracts (was silently skipped before — the shield never engaged on one-liners).
+- [x] **Live integration harness**: `scripts/smoke.sh [goal|list|draft]` — goal scenario 5/5 assertions green.
+- [x] CHANGELOG, version 0.2.0, publish.
+- [ ] `max_subtasks_per_task` cap → moved to M3 (no task-list creation tool exists yet; capping nothing is premature).
+
+### M3 — v0.3.0 (loop) ✅ (2026-07-20) — design
+
+**Loop 3 is metric-driven, not vibes-driven.** This is the anti-doorknob design:
+pi-loop-mode's failure mode was endless "improvement" churn (the DOORKNOB problem).
+Our loop only believes a number.
+
+**Model**:
+- User supplies: `target` (what to improve), `measure` (shell command that prints
+  a number), `direction` (min|max). Optional: `window` (plateau window, default 5),
+  `max` (iteration cap, default 50).
+- On `/loop start`: orchestrator runs `measure` → baseline.
+- On every `agent_end` while active: orchestrator runs `measure` → compare to best:
+  - improved (min: value < best; max: value > best) → new best, stall=0
+  - not improved / measure failed → stall++
+  - The **orchestrator** runs the measure (via `pi.exec`), never the agent —
+    the agent cannot fake the number.
+- Stop conditions: `stall >= window` (plateau), `iteration >= max`, or `/loop stop`.
+- No git-based auto-revert in v0.3.0 (too dangerous with uncommitted user work);
+  on regression the agent is instructed to undo its own last change, and the next
+  measure verifies.
+- **No auditor in loop 3**: the metric IS the verdict. Documented.
+- Mutual exclusion: a `/loop` cannot start while a goal/list is active and vice versa.
+
+**Command shape**: `/loop start "<target>" measure="<cmd>" direction=min [window=5] [max=50]`
+`/loop` (status) · `/loop stop`
+
+**Collision note**: `/loop` collides with pi-loop-mode — the M1 collision detector
+handles UX; smoke tests run under a bare `PI_CODING_AGENT_DIR` to isolate.
+
+**Also in M3**:
+- `propose_task_list` tool + `max_subtasks_per_task: 5` cap (M2 carry-over — makes
+  the existing complete_task/update_task_status tools actually usable).
+- `notify=<cmd>` setting: shell out on goal complete / goal pause / loop stop
+  (message passed as `$1`; config-gated, no deps).
+- Unit tests (metric parse, plateau logic, task cap) + `/loop` smoke scenario.
+
+**M3 verification evidence** (all live, 2026-07-20):
+- `/loop` smoke: metric 5→0 over 5 improving iterations (stall reset each time),
+  3 stall iterations at 0, plateau stop at window=3, `loop_stopped` + per-iteration
+  `loop_measured` in ledger, notify fired on stop. `scripts/smoke.sh loop` 5/5.
+- Regression check: `goal` 5/5, `list` 4/4, `draft` 3/3 — all scenarios hermetic
+  (bare agent dir + readiness wait) after two collision/REPL-race flakes.
+- 73 unit tests green; `tsc --noEmit` clean.
+- Found + fixed during M3: `/gla` whitespace split mangled quoted
+  notify commands; smoke `wait_for "plateau"` matched agent prose instead of
+  the orchestrator's stop text (assertions raced the loop).
+
+### M7 — v0.7.0 (global config tier) ✅ (2026-07-21)
+
+User directive: settings are not per-goal/loop/list — there should be ONE
+global config you set once and rarely open. Shipped: project > global >
+defaults resolution, `/gla` writes global by default (`project`
+prefix for local overrides), provenance display, 4 mergeSettings unit tests,
+live-verified both tiers + no-leak smoke. Docs updated.
+
+### M6 — v0.6.0 (draft everything) ✅ (2026-07-20)
+
+User directive: for a long-running thing, a draft up front is better. Drafting
+exists only for `/goal`; `/list add` takes raw strings, and `/loop start`
+demands a correct target+measure+direction in one blind shot — the most
+expensive place to be wrong (up to 50 iterations before plateau stops a bad
+metric). Draft all three loops; for `/loop`, validate the metric BEFORE
+confirming.
+
+1. **Unified drafting modes**: drafting target becomes `"goal" | "list" |
+   "loop"`. `/goal` (existing), `/list add` with no args (draft → confirmed
+   contract goes into the QUEUE instead of activating), `/loop` with no args
+   (draft → confirmed loop config starts the loop).
+2. **`/loop` drafting with measure test-run** (centerpiece): the agent grills
+   about target + what number represents progress, then calls
+   `propose_loop_draft(target, measureCmd, direction, window?, max?)`. The
+   **orchestrator runs the measure command once** and shows target + measure +
+   real output + parsed number + direction in the Confirm dialog:
+   "`grep -c TODO src.txt` → `42` (min). Start?" A broken measure (no number)
+   is shown as such and the agent is told to fix the proposal. User validates
+   the metric before a single iteration burns tokens.
+3. **`/goals` archive browser**: list archived goals (id, status, stop reason,
+   objective head) from `.pi-gla/archive/`. Long-running tool needs history.
+4. Gates: unit tests (draft-mode routing, loop-draft measure parsing), smoke
+   scenarios for loop-drafting and list-drafting, publish v0.6.0.
+
+**M6 evidence** (2026-07-20):
+- Loop drafting live: agent located num.txt itself, proposed `cat num.txt`;
+  Confirm dialog showed the real test-run ("Parsed number: 10, lower is
+  better"); confirmed loop ran improving iterations immediately.
+- List drafting live: confirmed contract → list_added → auto-activate →
+  audited → archived.
+- `/goals` parsing verified against real archive entries.
+- 89 unit tests, tsc clean.
+
+**Still deferred**: live footer/TUI widget (now the ONLY remaining scoreboard
+gap vs pi-loop-mode/pi-goal-x).
+
+### M5 — v0.5.0 (self-sufficiency) ✅ (2026-07-20)
+
+User directive: a goal loop that dies silently after compaction and needs an
+EXTERNAL plugin (`@badliveware/pi-compaction-continue`) to restart it is a hole
+in OUR plugin. Liveness is the loop's own job. Bake it in; cut the watchdog.
+
+1. **Heartbeat self-watchdog** (replaces pi-compaction-continue for our loops):
+   a 15s interval checks: active goal-or-loop AND session idle AND no pending
+   continuation/loop timer AND no activity for 60s → re-fire the continuation.
+   One check covers every stall cause (compaction-eaten turn, dropped message,
+   stale ctx). Stall accounting: a heartbeat-nudged turn with ZERO tool calls
+   counts as a nudge; 3 consecutive → pause (mirrors the watchdog's 3-nudge cap,
+   but scoped to real goal progress). Pure decision function unit-tested.
+   Scope note: this covers stalls while a goal/loop is active. Non-goal sessions
+   are the user's own business — they are at the keyboard.
+2. **`/goal tweak "<text>"`** — edit the active goal's objective in place
+   (Confirm dialog shows old vs new; contract re-extracted from the new text).
+   Closes the last pi-goal-x feature gap we use.
+3. **Structured drafting forms**: drafting prompt prefers `ask_user_question`
+   (rpiv-ask-user-question) when the tool is available in the session — closes
+   the structured-forms gap vs pi-goal-x without a hard dependency.
+4. **Rig cuts** (after publish): `pi-codex-goal`, `pi-loop-mode`,
+   `@badliveware/pi-compaction-continue`. AGENTS.md stack table rewritten:
+   goal plane = pi-goal-list-loop-audit.
+
+**M5 evidence** (2026-07-20):
+- Heartbeat: 8 unit tests for the stall predicate + nudge accounting; `goal`
+  smoke 5/5 with the heartbeat interval live through the full cycle.
+- `/goal tweak`: implemented with Confirm dialog + contract re-extraction.
+- Drafting prompt prefers `ask_user_question` when available.
+- 89 unit tests, tsc clean.
+
+**Deferred**: live footer/TUI widget (pi-loop-mode's dashboard is the one thing
+we genuinely lose by cutting it; v0.6.0 candidate if missed).
+
+### M4 — v0.4.0 (completion release) ✅ (2026-07-20)
+
+Everything left, in one release. Completes the 6-flaw list and makes the docs honest.
+
+1. **Auditor compaction (flaw #3 — the LAST open flaw)**. Enable pi's built-in
+   compaction in the auditor session (currently `compaction: { enabled: false }`).
+   Safety argument: regression_shield is orchestrator-side — a compaction-degraded
+   auditor produces weaker evidence → disapproval, never false approval. The risky
+   direction (silent false approval) is structurally impossible.
+2. **Schema + examples + docs sync**. `schemas/goal.schema.json` still says "oracle"
+   and "v0.1.0 loop 1 only"; `examples/example-objective.md` used `/pi-gla-set`;
+   `tests/README.md` has stale counts; `docs/DESIGN.md` needs the v0.2/v0.3 addendum.
+3. **tokensUsed wiring + limit enforcement**. `AgentEndEvent.messages` carries
+   `usage.totalTokens` per assistant message — accumulate per goal. `tokensLimit`
+   becomes a real cost guard: crossing it pauses the goal with a clear reason
+   (configurable via `/glla tokenlimit=`).
+4. **Resumption notice** on `session_start`: if a goal is active or a loop is
+   running, say so. (The "plugin vanished" self-check from D4 is impossible from
+   inside the plugin — absent code cannot run. Recorded as rejected.)
+5. **Loop 3 git-branch mode** (`branch=1` flag): at `/loop start`, create scratch
+   branch `pi-glla-loop/<id>`; commit after each improving iteration; on regression
+   `git reset --hard` to the last improving commit ON THE SCRATCH BRANCH ONLY.
+   The user's branch and uncommitted work are never touched. Requires: git repo,
+   and we refuse `branch=1` with a dirty tree (refuse to mix user work into the
+   scratch branch).
+6. **Draft reject path** in the smoke harness (Confirm → No → agent refines).
+
+After M4 the 6-flaw list is closed and the roadmap table is all-shipped.
+
+**M4 verification evidence** (all live, 2026-07-20):
+- Auditor compaction enabled; `goal` smoke 5/5 green after the change.
+- Token guard: 3 unit tests for dedup accumulation; limit-pause path wired in
+  agent_end with settings-configurable budget.
+- branch=1 live: 5 improvement commits on scratch branch, 0 for stalls, main
+  untouched, returned to main on plateau with merge instructions.
+- `draft-reject` smoke 6/6: Confirm → reject → refine → Confirm → approval.
+- Resumption notice on session_start for active goal/loop.
+- 81 unit tests, tsc clean, all 5 smoke scenarios green.
+- **6/6 pi-goal-x flaws now closed.** The D4 "plugin vanished" self-check is
+  recorded as REJECTED (absent code cannot run); replaced by the resumption
+  notice.
+
+**Deferred to v0.4.0 (with justification)**: (superseded — this release)
+
+---
+
+## 2. Open decisions (must resolve before M1 publish)
+
+### D1 — Command collision strategy ✅ RESOLVED
+
+**Verified in installed pi source** (`dist/core/extensions/runner.js:resolveRegisteredCommands`):
+- Duplicate command names **never throw** and **never clobber** — both survive.
+- First registrant keeps the bare name (`/goal`); later ones get `/goal:2`, `/goal:3`, …
+- So the failure mode is degraded UX (our command reachable as `/goal:2`), never breakage.
+
+**Decision: option 1 — plain names + detect-and-warn.** Implemented in `extensions/loops/goal.ts:warnOnCommandCollision`: at `session_start` we count registered command names via `pi.getCommands()`, and if any of ours (`goal`, `list`, `loop`, `goal-*`) appears more than once we notify the user with the degraded invocation name. Collision check is fail-silent (non-fatal by design).
+
+### D2 — Auditor model default ✅ RESOLVED (with a hard discovered constraint)
+
+**Discovered during M1 smoke (2026-07-20): the auditor session has no extensions, so it can only use BUILT-IN providers.** On this rig the main session ran kilocode (`tencent/hy3:free`) — an extension-registered provider — and every auditor spawn failed with `No API key found for kilocode`. Verified bare-session matrix: `opencode/deepseek-v4-flash-free` works extension-less; kilocode/zenmux/kimi-coding do not.
+
+**Decision**: default = session model (works when the session model is built-in); `/gla model=provider/id` overrides for rigs running extension-provided session models. The `/gla` save message now warns about the built-in-provider constraint. `resolveAuditorModel` documents it in code. v0.2.0 should add a startup check: if session model's provider is extension-registered and no auditorModel is set, warn once.
+
+### D3 — State dir name ✅ RESOLVED
+
+**Keep `.pi-gla/`.** Internal-only path; renaming costs a migration for zero user-visible gain. If we ever regret it, the rename is a one-line constant (`piGlaDir` in `goal-loop-core.ts`) plus a migrate-on-read.
+
+### D4 — Persistence across pi updates ✅ RESOLVED
+
+Known rig behavior (from earlier audits): `pi update` overwrites `~/.pi/agent/npm/node_modules/`, which can wipe npm-installed plugins. **Decision: document both install paths in INSTALL.md** — `pi install npm:pi-goal-list-loop-audit` (convenient, re-install after `pi update`) and project-local `.pi/extensions/` (permanent, survives updates). The `-e <path>` dev flow is unaffected. v0.2.0 should add a `session_start` self-check that notifies if the plugin vanished from the loaded set while `.pi-gla/active.jsonl` shows an active goal.
+
+---
+
+## 3. Verification gates (apply to every milestone)
+
+A milestone is not done until:
+
+1. `npm test` green (unit).
+2. `npm run check` clean (types).
+3. Live smoke passes (M1+).
+4. CHANGELOG entry written.
+5. No `oracle|sisyphus|squad|forge|pi-gla-` string outside `.pi-gla/` dir name (run the grep).
+
+```bash
+grep -rn "oracle\|sisyphus\|squad\|forge" \
+  tests/ extensions/ prompts/ docs/ examples/ README.md INSTALL.md CHANGELOG.md package.json \
+  | grep -v node_modules
+# expect: no output
+```
+
+---
+
+## 4. Risks
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| pi extension API drift (0.74 → next) | medium | pin peerDeps `*`; smoke test after every pi update |
+| Command collision (D1) | high | resolve D1 before publish |
+| Auditor cost (every complete_goal = extra session) | medium | D2 settings; document cost expectation in README |
+| User installs alongside pi-goal-x and gets two loops fighting | medium | README "conflicts" section; loud notify if `.pi/goals/` detected |
+| v0.1.0's auditor is rubber-stampable (`bash true`) until v0.2.0 regression_shield | known/accepted | documented in DESIGN + README; ship v0.2.0 fast |
+
+---
+
+## 5. Publish checklist (M1)
+
+- [ ] D1–D4 resolved and recorded in this file
+- [ ] `npm test` + `npm run check` + live smoke all green
+- [ ] Version bump `0.1.0-alpha.1` → `0.1.0`
+- [ ] git init + initial commit + GitHub repo `dracon/pi-goal-list-loop-audit`
+- [ ] `npm publish --access public`
+- [ ] Verify: `pi install npm:pi-goal-list-loop-audit` on a clean rig

package/README.md

@@ -8,9 +8,9 @@ The auditor runs in a fresh extension-less pi RPC process with no extensions, sk
 
 This is a detached process, not a nested session in the main pi process. `complete_goal` returns after writing the claim and job request; the status surface shows `auditor queued`, `auditor running`, or `audit recovery pending` while the worker runs or awaits a fresh lifecycle.
 
-On Windows, npm installs the `pi.cmd` shim rather than a directly executable `pi` binary. The auditor launches it through an explicitly quoted `cmd.exe` boundary; POSIX keeps direct shell-less execution. Protocol snapshots also tolerate transient Windows file-locks without deleting the last valid snapshot first.
+On Windows, npm installs the `pi.cmd` shim rather than a directly executable `pi` binary. The auditor launches it through an explicit `cmd.exe` boundary; arguments are quoted only when tokenization requires it (v0.35.27 — quoting a bare executable name breaks `.CMD` shim resolution on pnpm installs), and every argument passes the unsafe-character gate (`%`, CR, LF) before that decision. POSIX keeps direct shell-less execution. Protocol snapshots also tolerate transient Windows file-locks without deleting the last valid snapshot first.
 
-**Current package version:** `v0.35.13` — use `/glla version` to see the installed version and the command for comparing it with the registry latest. This checkout may contain unreleased changes; the npm registry is authoritative for published versions.
+**Current package version:** `v0.35.32` — use `/glla version` to see the installed version and the command for comparing it with the registry latest. This checkout may contain unreleased changes; the npm registry is authoritative for published versions.
 
 ## Why this exists
 
@@ -53,7 +53,7 @@ Five top-level commands — `/goal`, `/list`, `/loop`, `/glla`, `/review`:
 /goal verify                       # queue a detached auditor for the current goal — no agent turn (v0.28.27, renamed from /goal audit in v0.29.8)
 /goal tweak "<new objective>"      # edit in place (Confirm dialog)
 /goal archive                      # archived goals, newest first
-/glla                               # settings UI table · actions include /glla version · /glla status · /glla stats · /glla audits [N|full] · /glla cancel (cancel the active objective) · /glla postaudit · /glla wipe (idempotent all-live-state reset, Confirm-gated)
+/glla                               # settings UI table · actions include /glla version · /glla status · /glla stats · /glla audits [N|full] · /glla agents (tracked-subagent panel; --tail <id> reads a child transcript read-only) · /glla pause (freeze ALL supervisor automation — active work keeps running) · /glla cancel (cancel the active objective) · /glla postaudit · /glla wipe (idempotent all-live-state reset, Confirm-gated)
 /list fix the login bug, add dark mode, write docs   # dump it — the agent shapes it into items, one Confirm
 /list plan.md                      # file detected → bulk import, one Confirm (sisyphus/Ralph style)
 /list <paste a checklist>          # multi-line paste → same batch flow
@@ -240,7 +240,7 @@ Each loop is a different policy class on the same status machine.
 | Flaw in pi-goal-x | Fix in pi-goal-list-loop-audit |
 |---|---|
 | `detailedSummary` is hand-concat strings | Structured JSON state + native markdown renderer |
-| Stuck-counter has no ceiling — 1-hour waits happen | Hard 5-minute backoff cap, fall through to user notification |
+| Stuck-counter has no ceiling — 1-hour waits happen | Bounded retry envelope: eager 5s first retry, then the hourly-aligned ladder (v0.35.0); stall ladder + heartbeat nudges cap silent waits |
 | Auditor can rubber-stamp after `bash true` | **regression_shield** (shipped v0.2.0): auditor must quote raw tool output per verification-contract item; orchestrator rejects evidence-free approvals |
 | `pause_goal` is fire-and-forget | Clear `pauseReason` surfaced in status + agent feedback |
 | Vague objective + weak auditor = rubber-stamp | Drafting phase with Confirm dialog + isolated auditor + shield |
@@ -286,6 +286,29 @@ tool call or hidden reasoning interval therefore remains visibly timed; after
 three minutes without worker activity the UI changes to `auditor quiet` and
 names the cancellation/recovery path instead of presenting a frozen live card.
 
+**Per-phase glyphs + activity meter (v0.35.15).** Every auditor phase carries a
+distinct glyph — `⋯` queued, `▶` running, `◌` quiet, `⛔` blocked, `✓`
+awaiting-verdict — beside a draining `▰▱` activity meter, with the dense text
+kept as secondary detail. When a quiet stretch ends, the footer summarizes it
+(`silent 8m then resumed`) so silence is reported, not just survived. A single
+proactive warning fires when the detached auditor crosses the quiet threshold;
+it never repeats per tick.
+
+**Supervisor freeze (v0.35.15).** `/glla pause` silences every automatic
+side-effect — heartbeat re-arms, recovery probes, auto-resume, auto-continuation
+dispatch, the proactive quiet notify, and (v0.35.17) the zero-stream auto-retry
+below — without touching active work or a running detached audit. The flag is
+persisted and survives restarts; `/glla resume` clears it. Bare `/glla` shows
+the frozen state.
+
+**Zombie watchdog vs subagent waits (v0.35.26, issue #13).** A parent
+blocked on a foreground subagent call is stream-silent by design, so the
+zero-stream watchdog stands down while one is in flight. The recognized
+names cover both the built-ins (`Agent`, `get_subagent_result`,
+`steer_subagent`) and the pi-subagents extension's registrations
+(`subagent`, `subagent_wait`), shared by the watchdog and the wedge-alert
+hint so they cannot drift apart again.
+
 ## Provider failures: aggressive retry envelope, bounded (v0.35.0)
 
 Error text is **not trusted** to pick a retry policy. The runtime does not
@@ -299,6 +322,9 @@ adds a blind `:00:30` retry after each hour starts, so work can be picked up
 quickly after a possible provider-side change. The automatic window is 24h;
 explicit `/goal resume`, `/list resume`, or `/loop resume` starts a fresh
 window. With global `autoResume=on`, pending retries survive a session reload.
+A loop parked by the zero-stream abort (v0.35.25, issue #14) is explicitly
+resumable: `/loop resume` re-arms it with the preserved iteration count,
+best value, and history — exactly as the abort message promises.
 
 Only failures identified by positive evidence as futile avoid automatic retry:
 context/output-token limits and user aborts (`non-recoverable`). Auditor
@@ -370,6 +396,16 @@ brake streak, so a broken provider can't spin forever. A confirmed queued
 continuation with no turn is reported by the queue-stuck probe; it does not
 inject terminal input.
 
+**Zero-stream zombie abort + one bounded auto-retry (v0.35.17).** When pi stays
+BUSY with zero provider stream activity for 20 minutes, glla warns; after a
+10-minute grace it aborts the zombie turn and parks the work safely. Since
+v0.35.17 the FIRST such silence arms exactly ONE automatic retry ~90 seconds
+later (the park becomes a waystation, not a dead end — field: turns dispatched
+by accepting Confirm dialogs hung this way repeatedly). If the retry also hangs,
+the second consecutive silence parks permanently for manual `/goal resume` /
+`/list resume`. `/glla pause` freezes the retry like every other automatic
+side-effect.
+
 ## Session replacement and stale handles
 
 Recovery crosses pi's lifecycle boundary. On `session_shutdown`, glla records
@@ -423,6 +459,37 @@ loser is archived (recoverable under `.pi-glla/archive/`), never silently
 wiped. Legacy `complete`/`aborted` terminal slots are also cleared once their
 archive exists, while the final summary remains available in history.
 
+### Load without autostart (v0.35.23)
+
+On startup glla RESTORES and DISPLAYS all durable state — active/paused
+goal, waiting queue, loop — but holds every automatic dispatch until you
+decide. The load hold freezes the same machinery as `/glla pause`
+(continuation dispatch, loop ticks, heartbeat refires, recovery timers)
+through one shared gate; unlike a manual pause it keeps host-loss
+supervision probing, and it is released by any explicit work command:
+`/goal resume`, `/list resume`, `/list next`, `/loop resume`, `/loop start`,
+or starting a new goal. Every release is ledgered (`load_hold_engaged` /
+`load_hold_released`). Set global **Auto-resume = on** to restore
+load-time automation for unattended rigs — the consent is the raw setting,
+not the aggressive-mode default. Narrow continuity exceptions keep working
+without consent: validated handoffs/rebinds, same-process session
+successors, re-arming of work already in flight when a host silently died,
+and the single retry a parked completion claim earns when main-model
+recovery heals the provider that parked it.
+
+**Due-wait backstop (v0.35.28, issue #16).** A time-gated wait pause
+(`pauseKind: "wait"` with a `pauseResumeAt`) is no longer trusted to
+in-memory timers alone — agent-authored waits armed none, error-brake
+cooldowns were not re-armed on reload, and every scheduled resume died with
+its session. The heartbeat now compares wall time against `pauseResumeAt`
+every tick and re-fires the route once the deadline lapses by more than
+~90s (main-model waits probe the provider; other waits clear the park and
+dispatch one fresh continuation). `/glla pause` and the load hold still
+freeze it; every fire is ledgered (`wait_pause_overdue_resume`). Auto-resumed
+goals carry a RECOVERY NOTICE in their next continuation prompt — "welcome
+back, YOU were recovered" — so the agent continues its own work instead of
+waiting for an external recovery signal that already fired.
+
 ## Completion and destructive commands
 
 An approved objective writes its final completion summary to the archive and
@@ -442,6 +509,17 @@ Open `/glla` to edit these settings in the table (the rows show effective values
 
 - Auditor model and thinking level
 - Auditor fallback agent
+
+**Auditor selection (v0.35.24):** the **Auditor model** row opens the same
+`/model`-style fuzzy picker the main agent flows use — configured-auth models
+only, with a session-model row and a typed escape hatch. It is at full parity
+with the main selector on policy too: your forbidden-models patterns filter
+the picker list AND a typed match is refused with a named warning, so a pin
+saved here is one `resolveAuditorModel` will actually honor. The pick lands
+in global `auditorModel` and is followed immediately by the auditor thinking
+dialog for that model. The **Auditor fallback agent** row applies the same
+filtering to the failure-over pin.
+
 - Notify command, token limit, and wedge-alert minutes
 - Auto-resume, auto-accept drafts, decision popup, and carryover policy
 - Main-agent current model/thinking, fallback models, recovery cadence, and preferred-primary failback policy in the Main agent tab
@@ -452,11 +530,14 @@ Open `/glla` to edit these settings in the table (the rows show effective values
   stall brakes
 
 The argument namespace is reserved for actions such as `/glla status`, `/glla
-resume`, `/glla cancel`, `/glla stats`, `/glla audits`, `/glla tooloverride`,
-`/glla fallbacks clear`, and `/glla wipe`. `fallbacks clear` atomically removes
-the global main-agent fallback chain and cancels any pending fallback switch. Cancel stops the
-active objective; wipe clears all live state while preserving history.
-There is no top-level `/glla key=value` setting syntax.
+pause`, `/glla resume`, `/glla cancel`, `/glla stats`, `/glla audits`,
+`/glla tooloverride`, `/glla fallbacks clear`, and `/glla wipe`. `fallbacks clear`
+atomically removes the global main-agent fallback chain and cancels any pending
+fallback switch. Pause freezes every automatic supervisor side-effect (heartbeat
+re-arms, recovery probes, auto-resume, continuation dispatch, loop ticks, quiet
+notifications) without touching active work, and survives session restarts;
+resume unfreezes. Cancel stops the active objective; wipe clears all live state
+while preserving history. There is no top-level `/glla key=value` setting syntax.
 
 Resolution per key: **project > global > defaults** — EXCEPT `autoResume` and
 agent recovery settings (`mainModelFallbacks`, `mainModelRetryMinutes`,
@@ -598,23 +679,37 @@ customizes.
 
 ## Files
 
+Post-decomposition layout (the v0.34.x monolith is gone — `loops/goal.ts` is
+a thin activation/wiring installer):
+
 ```
 extensions/
-  loops/goal.ts                # /goal + /list commands, agent tools, loop driver
+  goal-commands.ts             # /goal + /list command surface, drafting, wipe/stats
+  loops/goal.ts                # public activation/wiring installer (thin)
+  loops/goal-tools.ts          # agent tools (complete_goal, pause_goal, list_*, loop drafts)
+  loops/goal-orchestrator.ts   # goal lifecycle: create/archive/advance, reviewer
+  loops/goal-auditor-hooks.ts  # completion-audit claim/recovery machinery
+  loops/goal-activation.ts     # event wiring, command registration, session lifecycle
+  loops/goal-settings-ui.ts    # settings editors + model pickers
   goal-loop-core.ts            # types, JSONL state, pure helpers
   goal-loop-auditor.ts         # auditor prompt + legacy in-process helper
   goal-loop-auditor-process.ts # detached worker protocol + shield revalidation
   goal-loop-shield.ts          # regression_shield (pure, dependency-free)
-  goal-loop-display.ts         # status line + /goal status rendering
+  goal-loop-display.ts         # widget/status rendering (incl. last-outcome retention)
+  goal-heartbeat.ts            # heartbeat self-watchdog, subagent probes, due-wait backstop
+  goal-continuation.ts         # continuation scheduling/dispatch + prompts
+  goal-recovery.ts             # main-model recovery + completion-audit recovery
+  goal-loop.ts                 # Loop 3 machinery: /loop tick engine, git finish
   goal-loop-forever.ts         # /loop measure/parse/plateau helpers
-  goal-loop-backoff.ts         # 5-min hard cap
+  goal-loop-backoff.ts         # scheduling constants + stall/wedge/pending-latch decisions
 prompts/
-  goal-loop-continuation.md    # loop driver prompt
+  goal-loop-continuation.md    # continuation prompt
   goal-loop-draft.md           # drafting prompt
   goal-loop-forever.md         # /loop driver prompt
   goal-loop-forever-draft.md   # /loop drafting prompt
 scripts/
   goal-auditor-worker.mjs      # extension-less RPC auditor child process
+  goal-auditor-launch.mjs      # Windows-safe spawn spec builder (gate-before-quote)
   smoke.sh                     # live integration harness (tmux + real models)
 tests/                         # current test count is reported by `bun test`; no live pi required for the suite
 docs/DESIGN.md                 # architectural decisions

package/docs/DESIGN-subagent-visibility.md

@@ -0,0 +1,76 @@
+# Design — subagent visibility (`/glla agents`, issue #15)
+
+Status: SCOPE AGREED with the user 2026-08-22 (panel + transcript tail +
+widget line; live activity stream explicitly rejected as too noisy).
+This document is the implementation contract for the follow-up work.
+
+## Problem (issue #15)
+
+During long fan-outs the only child visibility is the widget's 3-slot
+"recent actions" ring. A child that "almost completed its final report,
+went back to check some more, then crashed" is invisible: the parent sees
+a silent wait, the user sees nothing actionable, and post-mortem evidence
+lives in files nobody knows how to find.
+
+## Agreed scope
+
+### 1. `/glla agents` — snapshot panel
+
+One-shot table of every tracked subagent, sourced from what glla already
+holds (no new instrumentation):
+
+- `subagentHangProbes` (goal-heartbeat.ts): agentType, summary, spawnedAt,
+  lastProgressAt, toolUses, outputTokens, endedAt, hangAlertedAt.
+- `subagentManagerPoller()` when pi-subagents publishes its registry
+  (absent on some installed versions — always degrade gracefully to
+  event-derived evidence).
+- `flags.inFlightToolCalls` for which parent wait (foreground Agent /
+  subagent call) each running child blocks.
+- Ledger history of `subagent_hang_detected` for the "Recent hangs" footer
+  of the panel.
+
+Row shape:
+
+```
+● explore   map-model-picker   RUNNING 4m12s   tools 18 · out 2.1k · silent 0m
+● plan      audit-contract     HUNG? 31m       tools 6 → frozen · out 890 · silent 26m
+  └ blocks: foreground subagent call (zombie stand-down active)
+✓ explore   schema-check       ENDED ok 3m44s
+```
+
+Hung classification reuses `classifyHungSubagents` semantics (record-frozen
+vs event-only evidence). Cap display at ~20 rows; prune ended probes per
+the existing SUBAGENT_HANG_PRUNE_MS rule.
+
+### 2. `/glla agents --tail <id>` — child transcript tail (post-mortem)
+
+Locate the child's session file on disk (pi sessions are JSONL under the
+session store; pi-subagents records expose/allow correlation by id — probe
+both the manager record and the probe registry) and print the LAST N lines
+(N default 20, `--lines` override) rendered as `[tool] …/[asst] …/[user] …`
+with truncation. If the file cannot be located, say so LOUDLY and name the
+searched paths — never silently print an empty tail. Read-only: the tail
+NEVER resumes or attaches to the child session.
+
+### 3. Widget line — ambient awareness
+
+One footer segment while children are tracked: `● N agents · <busiest>
+silent Xm ⚠` (⚠ only past the hang threshold). Reuses the existing widget
+render path in goal-loop-display/goal-ui; hidden when zero tracked
+children so idle rigs see no change.
+
+## Non-goals (explicitly rejected with the user)
+
+- Live streaming of child tool calls into the main transcript (noise).
+- Any attach/resume capability from the panel (read-only by design).
+- New cross-extension contracts beyond the existing defensive manager poll.
+
+## Implementation notes
+
+- New module `extensions/goal-agents-panel.ts` (pure render functions +
+  data assembly), wired into the `/glla` argument namespace next to
+  `/glla audits`; widget segment in goal-ui.
+- All rendering pure/testable: feed fixtures of probes + manager records;
+  pin hung classification, cap behavior, loud-missing-file behavior for
+  --tail, and widget hide-at-zero.
+- Version + CHANGELOG + README at ship time; full release gate.