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

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.64` — 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
 
@@ -44,6 +44,7 @@ Five top-level commands — `/goal`, `/list`, `/loop`, `/glla`, `/review`:
 /goal "audit the repo"             # no contract clause → agent grills you first (propose is gated on it)
 /goal "Step 1. Step 2. Done when: tests pass."   # has contract → starts now
 /goal start "fix the flaky login test"          # explicit skip-draft: starts now, no interview (auditor infers the contract)
+/goal plan "build a greenfield crawler"         # extended draft for greenfield/megaplan work: research-first, multi-round interview, structured expanded objective — still Confirm-gated (v0.35.33)
 /goal status                       # show state
 /goal pause                        # pause
 /goal resume                       # resume
@@ -53,7 +54,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
@@ -74,7 +75,9 @@ matches `/list show`.
 /list remove <n>                   # drop item n from the list
 /list clear                        # empty the list
 /list cancel                       # stop the whole list: abort the active item + drop all waiting
+/list plan "a greenfield blog engine"   # extended draft: deep research + multi-round interview, then ONE Confirm proposes the whole items[] batch (v0.35.33)
 /loop                              # draft the loop (agent grills; measure is test-run before you confirm)
+/loop plan                         # extended loop draft: deep research + multi-round metric design (v0.35.33)
 /loop start "keep polishing the UI"                          # infinite metricless loop (v0.23.6): no plateau, no cap — ends at time=/tokens= or /loop stop
 /loop respec                                                  # infinite metricless loop reconciling the codebase against the root SPEC.md / spec.md (v0.24.3) — 2 specs = you pick, 0 specs = drafting, 1 spec = auto-start (v0.24.4)
 /loop audit                                                    # project-audit loop (v0.29.0): each iteration audits fresh, appends findings to .pi-glla/audit-loop/findings.md, fixes the top ones — the orchestrator counts open findings and the plateau stop ends it when the well is dry (one-shot version: /goal audit)
@@ -87,6 +90,22 @@ matches `/list show`.
 /review <goal-id> [off|on|auto|aggressive]   # re-review an archived goal (bypasses the trigger gates)
 ```
 
+### What the verbs mean
+
+The same verb can mean different things on each surface — and `audit` is
+deliberately three different machines:
+
+| | **draft** (bare / text arg) | **start** | **plan** | **audit** |
+|---|---|---|---|
+| `/goal` | agent interviews you, one Confirm | skip the interview, start now | **extended draft**: research-first, multi-round interview, structured expanded objective — still ONE Confirm (v0.35.33) | **one-shot project audit**: a single collect-then-fix pass as an ordinary audited goal; findings are fixed in that pass, DECIDE findings come to you untouched |
+| `/list` | batch-drafts your items into ONE confirmed queue | *(use drafting or direct adds)* | **extended draft for greenfield queues**: deep research + interview proposes the whole items[] batch (v0.35.33). Prose only — a file path stays bulk import (`/list plan.md` imports as-is); inside `/list plan`, files you mention become research input, never auto-imported | **collect, then drain**: queues an item that CHANGES NO CODE — it only appends findings to `.pi-glla/audit-loop/findings.md`; on completion each open finding becomes its own list item, drained fix-by-fix with its own audit (v0.31.0) |
+| `/loop` | drafts the loop; your measure is test-run before Confirm | start a loop directly from args | **extended loop draft**: deep research + multi-round metric design before anything runs (v0.35.33) | **forever audit cadence** (v0.29.0): each iteration audits fresh and fixes the top findings; the plateau stop ends it when the well is dry |
+
+Related but distinct: **`/goal verify`** audits the CURRENT goal's work right
+now (detached auditor, no agent turn) — it does not survey the project.
+One audit initiative per session: starting a second kind warns about
+superseding the first.
+
 **Metricless loops** (`measure=none`): for genuinely endless work — an
 ever-improving spec, continuous hardening — where no number means "better".
 There is **no plateau stop** (nothing to stall on): the loop ends only at
@@ -117,7 +136,11 @@ grilled by the agent (proposing is mechanically blocked until you have
 replied at least once — typed chat or an answered `ask_user_question` dialog
 both count), args-with-a-clause start instantly, `/goal start` skips the
 interview by explicit command, a file path is
-bulk direct.** A
+bulk direct.** The `plan`
+verb is the fourth depth on every surface: same Confirm gate, but the agent
+researches BEFORE asking and interviews across multiple rounds — for
+greenfield or megaplan work where the normal 5–7-question draft would be
+too shallow. A
 sisyphus-style plan file (checklists, bullets, numbered, plain lines) imports
 as-is — headings become nothing, items become goals. And the drafter itself
 batches: asking for "these 50 tasks" in a `/list` drafting session produces
@@ -203,6 +226,9 @@ product). The other three are optional; glla works without them:
 
 ## Which loop? (the decision rule)
 
+(Verb semantics — what `start`, `plan`, and `audit` mean on each surface —
+are tabulated above, "What the verbs mean".)
+
 **`/goal`** — one thing, judged *semantically*. Research, features, docs,
 anything where "done" needs a reader. The isolated auditor verifies against
 your `Done when:` contract with quoted evidence.
@@ -240,7 +266,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 +312,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 +348,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 +422,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 +485,47 @@ 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.
+
+### Auditor context without autostart (v0.35.63)
+
+A restored objective remains visible in the status/widget UI even when the
+load hold is active, but GLLA does not add a new continuation or re-inject the
+previous auditor report until continuation consent exists. `/goal resume`,
+`/list resume`, `/list next`, `/glla resume`, admitted loop resumes, validated
+session continuity, and global **Auto-resume = on** are consent paths. The
+previous Pi transcript is historical and remains untouched; this gate controls
+only newly projected auditor feedback and model context.
+
+**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 +545,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 +566,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`,
@@ -525,15 +642,21 @@ are workers** (v0.23.8):
 - A subagent session never clobbers the loop's session handle, never runs
   the restore gate, and never drives continuation — so the heartbeat,
   wedge alert, and auto-resume machinery always act on the main session.
-  (pi hands a fresh ctx wrapper per event; `ctx.sessionManager` identity
-  is the discriminator.)
+  Headless `print`/`json` child contexts are rejected before root
+  registration, restore, owner claims, or command/tool mutation; this also
+  covers persistent children, not only the usual in-memory workers.
 - Subagent tool activity counts as activity for the wedge clock — a long
-  subagent run is work, not a hang.
+  productive child run is work, not a hang. If a tracked top-level child stops
+  changing its tool-use/output counters, glla warns at the short detection
+  threshold and can request one child-specific abort after
+  `subagentHangEscalationMinutes` (default 30; `0` = warning-only). The main
+  host still records lifecycle, action state, and partial output for
+  `/glla agents` through the event bus.
 - With `@tintinweb/pi-subagents` specifically (the one we test against):
   read-only agents (Explore, Plan) get no glla tools; general-purpose
   agents see them but state-mutating calls (`complete_goal`, `propose_*`,
-  `list_add`, `pause_goal`, …) are refused with "report back to the main
-  agent".
+  `list_add`, `pause_goal`, …) and foreign slash commands are refused with
+  "report back to the main agent".
 
 ## Token guard
 
@@ -598,23 +721,75 @@ 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-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
+extensions/  (34 files — all of them, grouped by concern)
+  # command + UI surface
+  goal-commands.ts             # /goal + /list command surface, drafting, wipe/stats
+  settings-menu.ts             # /glla settings menu sections + rows
+  goal-agents-panel.ts         # tracked-subagent panel (/glla agents) + widget line
+  confirm-draft.ts             # Confirm-card markdown builder
+  vision-assist.ts             # mmx vision routing + model-switch gate
+  glla-version.ts              # version info for /glla version (source + npm)
+  # state, types, pure helpers
+  goal-loop-core.ts            # types, JSONL state reader, pure helpers
+  goal-state.ts                # disk writer (persistStateLine serialization)
+  goal-settings.ts             # settings load/save + global/project paths
+  faulty-objective-recovery.ts # suspicious-objective classification + repair derivation
+  goal-objective-conflict.ts   # live-objective conflict resolution on start/tweak
   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)
+  # continuation + recovery
+  goal-continuation.ts         # continuation scheduling/dispatch + prompt templates
+  goal-loop-dispatch.ts        # generation-bound dispatch records
+  length-continue.ts           # stop_reason=length auto-continue policy
+  goal-heartbeat.ts            # heartbeat self-watchdog, subagent probes, due-wait backstop
+  goal-recovery.ts             # main-model recovery + completion-audit recovery
+  main-model-recovery.ts       # pure model-fallback/probe scheduling helpers
+  quota-retry.ts               # provider diagnostics + bounded retry windows
+  # loop machinery (Loop 3)
+  goal-loop.ts                 # /loop tick engine, git finish
   goal-loop-forever.ts         # /loop measure/parse/plateau helpers
-  goal-loop-backoff.ts         # 5-min hard cap
-prompts/
-  goal-loop-continuation.md    # loop driver prompt
-  goal-loop-draft.md           # drafting prompt
+  goal-loop-backoff.ts         # scheduling constants + stall/wedge/pending-latch decisions
+  goal-loop-repetition.ts      # anti-repetition detectors (stuck ladder, v0.24.0)
+  goal-loop-stats.ts           # ledger rollups + premature-success detection
+  goal-loop-subagents.ts       # subagent markers + pinned-agent knowledge
+  reviewer.ts                  # archived-goal re-review config + classification
+  # auditor machinery
+  goal-loop-auditor.ts         # auditor prompt + legacy in-process helper
+  goal-loop-auditor-process.ts # detached worker protocol + shield revalidation
+  auditor-extensions.ts        # auditor-session extension discovery + allowlist
+  # model pickers
+  drafter-model.ts             # drafting-only model resolution + fallbacks
+  model-picker.ts              # single-model picker items
+  multi-model-picker.ts        # multi-model picker UI
+  model-selector.ts            # scope-aware fallback selector composition
+loops/
+  goal.ts                      # public activation/wiring installer (thin)
+  goal-activation.ts           # event wiring, command registration, session lifecycle
+  goal-tools.ts                # agent tools (complete_goal, pause_goal, list_*, loop drafts)
+  goal-orchestrator.ts         # goal lifecycle: create/archive/advance, reviewer
+  goal-list-queue.ts           # /list queue: enqueue/advance/drain, list drafting
+  goal-auditor-hooks.ts        # completion-audit claim/recovery machinery
+  goal-session.ts              # session-scoped runtime globals + lifecycle state
+  goal-runtime-globals.ts      # ambient declarations for those globals
+  goal-settings-ui.ts          # settings editors + model pickers
+  goal-ui.ts                   # shared UI helpers (drafting state reset, notify wrappers)
+prompts/  (7 — one per prompt surface; edited as .md, read at runtime)
+  goal-loop-continuation.md    # continuation prompt template
+  goal-loop-draft.md           # /goal + /list drafting interview
+  goal-loop-plan.md            # extended plan draft — goal/list (v0.35.33)
+  goal-loop-plan-loop.md       # extended plan draft — loop (v0.35.33)
   goal-loop-forever.md         # /loop driver prompt
-  goal-loop-forever-draft.md   # /loop drafting prompt
+  goal-loop-forever-draft.md   # /loop drafting interview
+  goal-loop-forever-metricless.md  # metricless-/loop drafting variant
 scripts/
   goal-auditor-worker.mjs      # extension-less RPC auditor child process
+  goal-auditor-launch.mjs      # Windows-safe spawn spec builder (gate-before-quote)
+  auditor-extension-fixture.mjs       # hermetic provider fixture for the auditor gate
+  verify-auditor-extensions-offline.mjs  # mandatory gate: resolved allowlist loads offline
   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.

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` |