pi-goal-list-loop-audit 0.35.70 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 0.36.0 — event-driven long-running supervision (2026-08-28)
+
+### Added
+  Bare `/goal start`, `/loop start`, and `/list start` now use a bounded active
+  branch context window only when it contains one clear actionable user
+  request. Ambiguous, generic, truncated, or multi-task context returns to the
+  existing drafting/confirmation flow; list queue activation and loop metric
+  settings remain explicit.
+
+  GLLA now records a six-label user-facing recap for every archived terminal
+  objective and loop stop. Valid recaps are preserved; missing or incomplete
+  claims receive a recorded-facts-only fallback with explicit `not recorded`
+  values instead of invented evidence.
+
+  The shared heartbeat is now an event-first continuous supervisor across
+  goals, list items, loops, auditors, subagents, provider recovery, and queue
+  state. It reacts to lifecycle/durable signals immediately and uses adaptive
+  fallback polling rather than guessed task-duration waits.
+
+### Fixed
+  Detached completion-auditor failures now coordinate RPC stdout EOF with the
+  child process close, preserving bounded exit code, signal, stderr, and
+  malformed-stream diagnostics while remaining fail-closed until
+  `agent_settled`.
+
+### Changed
+  The detached auditor now has the same ordered, deselectable, bounded fallback
+  chain as the main agent (`auditorModelFallbacks`, up to 10 refs), with the
+  former singular fallback setting migrated compatibly. An unset auditor
+  thinking level inherits the parent session's live dial, including `max`,
+  while explicit auditor levels remain overrides.
+
+  Aggressive recovery retries recoverable provider/host/auditor failures across
+  arbitrary durations with bounded per-attempt backoff. Ordinary auditor
+  objections become durable TODOs; repeated identical objections with no new
+  progress stop on a state-based decision boundary. Conservative mode retains
+  its bounded recovery horizon.
+
+  Full auditor `IMPOSSIBLE` results and list auto-drops now pass through the
+  terminal archive fence with durable recaps; partial impossible results keep
+  their explicit narrowing behavior. Every loop-stop notification includes a
+  compact projection of the generated six-label recap. Version-bearing
+  already-shipped claims, explicit goal/list cancellation, and `/glla wipe`
+  now include the same compact projection in their terminal notifications.
+
+  Detached-auditor first-event watchdogs start at worker spawn rather than
+  charging dispatch setup time, with a runtime-compatible return-time fallback;
+  cancellation waits for worker teardown before classifying the attempt. The
+  former unconditional auditor wall is compatibility metadata only; active
+  output, tool, durable, and child progress can continue until a result,
+  confirmed-silence watchdog, per-tool timeout, or explicit lifecycle stop.
+
+  Carryover replacement, `/list next` skips, and complete-without-audit now
+  check the archive fence before reporting success and include the same recap
+  projection as other terminal paths. Continuous-supervision tests now drive
+  durable state transitions and lifecycle signals across every declared plane.
+
+  Validation warnings are metadata rather than recap fields: an incomplete
+  claim whose NOTE mentions label names is still replaced by the recorded-
+  facts-only archive fallback. Approved terminal notifications use the same
+  six-label compact projection, including for long valid recaps, instead of a
+  raw flattened slice.
+
+  Durable-vs-defer decisions now have an explicit `record_goal_judgment` tool:
+  inline and deferred choices are persisted as bounded ledger events, with a
+  required durable follow-up for intentional deferrals. The policy keeps the
+  durable action ahead of defer and pins the plaque-ordering regression.
+  The recommendation now comes from a typed semantic decision path, including
+  the three-defer case, and the active goal card has a deterministic ordered
+  plaque fixture so UI ordering is tested rather than inferred from prose.
+  `record_goal_judgment` now persists bounded recommendation facts on the goal
+  and immediately routes them through production `refreshUI()`; the production
+  integration test captures the resulting durable-first card.
+
+  See `docs/DESIGN-long-running-supervision.md` for the durable policy and
+  future decision checklist.
+
+## 0.35.72 — remove duplicate terminal outcome widget (2026-08-28)
+
+### Fixed
+  Approved or aborted goals now clear the live outcome slot after the single
+  completion notification. The archived goal record and ledger remain the
+  durable history, while legacy `lastOutcome` state is read safely but no
+  longer paints a second `✓ done` row after archival.
+
+### Tests
+  Updated terminal-outcome regressions to verify that completed/aborted goals
+  leave no retained widget row, while live goals still outrank legacy state.
+
+## 0.35.71 — bounded Pi-core retry containment (2026-08-26)
+
+### Changed
+  GLLA now exposes a configurable zero-stream retry budget (default 3,
+  allowed range 0–10). When Pi remains BUSY without stream activity, GLLA
+  still aborts and durably parks the owner, then re-dispatches repeatedly
+  within that finite budget before requiring explicit resume. A real stream
+  starts a fresh budget; supervisor pause, generation fences, and durable
+  recovery semantics remain intact. This contains the Pi-core retry-sleeper
+  failure at GLLA's public boundary without modifying Pi or any other plugin.
+
+### Tests
+  Added repeated-silence exhaustion, budget persistence/validation, settings
+  menu/editor coverage, and existing lifecycle/park/no-storm regressions.
+
 ## 0.35.70 — optional-provider boundary and recovery alignment (2026-08-26)
 
 ### Changed

package/INSTALL.md

@@ -72,7 +72,9 @@ Done when:
 A complete `Done when:` clause starts directly. For a new or ambiguous
 objective, use bare `/goal` instead: GLLA interviews you, helps shape the
 contract, and waits for Confirm. `/goal start "..."` skips that interview only
-when you explicitly want it skipped.
+when you explicitly want it skipped. Bare `/goal start` uses one clear recent
+user request when possible and otherwise returns to the normal drafting flow;
+it never guesses across ambiguous requests.
 
 The first run proceeds like this:
 
@@ -93,17 +95,22 @@ waiting for a decision.
 /list "refactor the cache. Done when: tests pass"
 /list plan.md
 /list
+/list start
 /list next
 /list resume
 
 /loop
+/loop start                                  # one clear recent target, metricless
 /loop start "reduce flaky tests" measure="..." direction=min
 /loop start "keep improving the spec" measure=none max=20 cadence=900
 /loop audit
 ```
 
 Use `/goal` for one outcome, `/list` for several independently auditable
-outcomes, and `/loop` for an improvement process without one final item. For
+outcomes, and `/loop` for an improvement process without one final item. Bare
+`/list start` activates the queued head, or seeds the normal Confirm-gated list
+draft when the queue is empty. Bare `/loop start` infers only the target; it
+does not invent metric, direction, bounds, cadence, or branch settings. For
 metricless loops that intentionally mature between checks, add optional
 `cadence=<seconds>`; the interval is visible in `/loop status`, while explicit
 starts/resumes remain urgent. See the README for the full command semantics.
@@ -147,7 +154,10 @@ Useful controls:
 ```
 
 `/glla pause` freezes supervisor automation without killing active work.
-`/glla resume` releases it. A user abort means stop; recovery is not silently
+`/glla resume` releases it. A BUSY/no-stream Pi turn is aborted and parked by
+GLLA, then automatically re-dispatched within the **Zero-stream retries**
+budget (default 3, configurable from 0–10); exhaustion requires an explicit
+mode-correct resume. A user abort means stop; recovery is not silently
 re-fired behind your back.
 
 ## Auditor model requirement

package/README.md

@@ -1,5 +1,9 @@
 # pi-goal-list-loop-audit
 
+<p align="center">
+  <img src="media/glla2.png" alt="GLLA mission control" width="960">
+</p>
+
 > **Long-running, high-leverage autonomy for pi.**
 >
 > Give pi a meaningful outcome. GLLA helps it research, plan, execute,
@@ -18,13 +22,18 @@ finished without evidence**:
 
 - You state the outcome and what “done” means.
 - The agent researches, decomposes, and executes across many turns.
-- GLLA keeps durable state, supervises progress, and recovers bounded failures.
+- GLLA keeps durable state, checks lifecycle/progress signals continuously, and
+  recovers failures with bounded per-attempt backoff plus policy-driven stop rules.
+- Every terminal objective leaves a useful six-label recap; missing evidence is
+  shown as `not recorded`, never guessed.
 - Optional subagents can do parallel research and focused implementation work.
 - A separate detached auditor checks the saved completion claim before GLLA
   accepts it.
 
 The aim is not “run forever.” The aim is **more useful work per unit of
-attention, with better evidence at the end**.
+attention, with event-driven progress instead of guessed-duration waiting, and
+better evidence at the end**. See `docs/DESIGN-long-running-supervision.md` for
+the long-running policy.
 
 Use `/glla version` to inspect the installed version and compare it with the
 registry. This checkout may contain unreleased changes; npm is authoritative
@@ -127,6 +136,7 @@ forcing every problem into a loop.
 /goal                                      # interview + Confirm
 /goal "... Done when: ..."                 # direct contract start
 /goal start "..."                          # explicit no-interview start
+/goal start                                  # use one clear recent request, or draft safely
 /goal plan "..."                           # research-first extended plan
 /goal status                               # inspect the current goal
 /goal pause                                # pause automatic continuation
@@ -146,6 +156,7 @@ quietly inventing an unbounded backlog.
 /list "fix the cache. Done when: tests pass"
 /list plan.md                              # import a checklist or plan file
 /list                                     # show active and waiting items
+/list start                                # activate the queued head, or draft one clear recent request
 /list next                                 # intentionally activate the next item
 /list next <n>                             # choose a specific item
 /list resume                               # explicitly retry/resume the list
@@ -162,12 +173,16 @@ If a saved item is malformed or needs a repair, the repair card preserves the
 full original target, explains the concrete recovery action, and permits one
 bounded bootstrap turn containing `propose_task_list`. Confirm the redraft;
 automatic repeats are fenced. Use `/list resume` for an intentional retry and
-`/list next` when you intentionally want another queued item.
+`/list next` when you intentionally want another queued item. `/list start` is
+also explicit: it activates the queued head, or—when the queue is empty—uses
+one clear recent user request as a seed for the normal Confirm-gated list
+drafting flow. Ambiguous context is never queued automatically.
 
 ### `/loop` — an improvement process
 
 ```text
 /loop                                     # interview + Confirm
+/loop start                                # use one clear recent target as an explicit metricless start
 /loop plan                                # research-first loop design
 /loop start "reduce flaky tests" measure="..." direction=min
 /loop start "keep improving the spec" measure=none max=20 cadence=900
@@ -176,6 +191,12 @@ automatic repeats are fenced. Use `/list resume` for an intentional retry and
 /loop stop
 ```
 
+Bare `/loop start` infers only one clear recent target. It does not invent a
+measure, direction, bound, cadence, or branch setting; the command uses the
+existing explicit metricless-start path. If the context is ambiguous, GLLA
+returns to loop drafting so the target and any numeric metric/consent gates
+remain visible.
+
 There are three loop styles:
 
 - **Metric:** a bounded command prints one number that honestly represents
@@ -329,7 +350,9 @@ that silence means success. Error text is **not trusted** to pick a retry policy
 failure wording is retained as bounded diagnostics, not interpreted as
 proof of a quota or billing state.
 
-- automatic retries are bounded and visible;
+- automatic retries are bounded and visible; a BUSY/no-stream turn is parked
+  and re-dispatched within the configurable **Zero-stream retries** budget
+  (default 3, range 0–10), then requires explicit resume;
 - `/goal resume`, `/list resume`, and `/loop resume` are explicit recovery
   paths;
 - a user abort means stop, not “try again behind my back”;
@@ -341,16 +364,18 @@ proof of a quota or billing state.
 - interrupted completion claims remain available for retry and inspection.
 
 Use `/glla pause` to freeze supervisor automation without killing active work,
-`/glla resume` to release it, and `/glla status` or `/goal status` to inspect
+`/glla resume` to release it, `/glla bug [message]` to capture failure context to `bugs/` without touching durable goal state, and `/glla status` or `/goal status` to inspect
 what happened.
 
 ### Settings worth knowing
 
 Open `/glla` for the settings table. The most important choices are:
 
-- **Auditor model / thinking level:** the verifier's model and depth;
-- **Main-agent fallback models:** an ordered recovery chain for provider
-  failures;
+- **Auditor model / thinking level:** the verifier's model and depth; when
+  unset, auditor thinking inherits the parent session dial (including `max`);
+- **Main-agent and auditor fallback models:** both roles use the same ordered,
+  deselectable, bounded fallback-chain picker for provider failures; the
+  auditor's session model remains the final last resort;
 - **Auto-resume:** whether persisted work may restart automatically after a
   session loads; explicit resume commands are always available;
 - **State root:** `workingDir` by default, opt-in `sessionDir`;
@@ -358,6 +383,8 @@ Open `/glla` for the settings table. The most important choices are:
   choices win;
 - **Subagent hang escalation:** warning-only at `0`, or one child-specific
   action after a confirmed frozen interval;
+- **Zero-stream retries:** automatic GLLA recovery attempts after a busy,
+  stream-silent Pi turn; `0` keeps recovery manual and `1–10` bounds repeats;
 - **Audit cap and retry cadence:** bounds for repeated objections and
   infrastructure recovery.
 
@@ -435,8 +462,10 @@ when tracing behavior:
 
 The package contains the extension entry point
 `extensions/loops/goal.ts`, prompt templates, schemas, scripts, docs, examples,
-and the full test suite. `audit/` and `.research/` are repository material, not
-first-use package content.
+and the user-facing README/install/changelog files. The full test suite remains
+repository material for maintainers and is exercised by `npm run test:all`; it is
+not included in the published tarball. `audit/` and `.research/` are also
+repository material, not first-use package content.
 
 ## License
 

package/docs/DESIGN-long-running-supervision.md

@@ -0,0 +1,116 @@
+# Long-running supervision policy
+
+**Decision record: v0.36.0 — 2026-08-28**
+
+This document records the GLLA policy for work that can outlive one agent
+turn, one provider session, or one day. It is a project decision record, not a
+change to Pi core, `pi-subagents`, or `pi-memory`.
+
+## Decision
+
+GLLA automation is **event-driven and progress-aware**, not duration-guessed.
+
+- A lifecycle event, durable state transition, child-progress signal, or
+  process completion marker is the primary reason to inspect or advance work.
+- If no public event signal exists, GLLA uses a short adaptive fallback poll
+  (`250ms` backoff to the normal safety cadence) rather than sleeping for an
+  estimated task duration. A five-second task must not inherit a ten-minute
+  wait merely because the system guessed wrong.
+- A live process remains eligible while real output, tool activity, durable
+  markers, or child progress proves liveness. A silent or unreachable process
+  may be classified as wedged only by the existing bounded safety watchdog.
+  Detached auditors have no unconditional wall-clock expiry: legacy wall
+  metadata is ignored, while confirmed silence and an individual tool timeout
+  remain the bounded safety mechanisms.
+- Timers remain useful for per-attempt backoff, watchdogs, and host safety. A
+  timer is never evidence that work completed and is not the definition of a
+  long-running process's lifetime. Detached-auditor first-event silence starts
+  at the successful worker spawn boundary (with a return-time fallback for
+  runtimes that deliver the spawn event too early), so dispatch setup cannot
+  consume the worker's startup budget. Cancellation awaits the worker's
+  TERM-to-KILL settlement before the attempt is classified or cleaned up.
+
+The shared checker covers all GLLA-owned work planes: ordinary goals, list
+items and their queue, metric/spec/audit loops, detached completion auditors,
+tracked subagents, provider recovery, and lifecycle/session transitions.
+
+## Aggressive automation
+
+Aggressive mode is the default effective keep-going policy unless the user
+explicitly opts out. Its purpose is unattended long-running work:
+
+- Recoverable provider, host, and auditor-infrastructure failures retry with
+  bounded per-attempt backoff and durable owner/generation fences.
+- In aggressive mode, a recovery episode has no wall-clock expiry. Legacy
+  `autoRetryUntil` fields remain readable for compatibility, but new aggressive
+  scheduling must not stop solely because that old horizon elapsed.
+- A semantic auditor disapproval is actionable work: its extracted objections
+  become a bounded durable TODO projection and the next continuation works them.
+  Repeated identical objections with no new progress are a state-based stop,
+  not an invitation to burn more turns.
+- Automation stops on success, explicit user pause/cancel, a non-retriable or
+  contradictory semantic result, ownership loss, persistence-integrity failure,
+  or repeated no-progress. A cold-start consent/load hold still wins; aggressive
+  mode does not silently turn an unattended fresh launch into user consent.
+- A retry must be idempotent with respect to durable state. It must not create
+  duplicate workers, overwrite a newer generation, duplicate TODOs, or erase a
+  recoverable claim.
+
+Conservative mode keeps the pre-v0.36 bounded recovery horizons and explicit
+manual holds. This opt-out is retained for users who prefer a finite
+unattended recovery envelope.
+
+## User-facing completion summaries
+
+Every archived terminal objective gets one full six-label recap:
+
+```text
+Outcome: ...
+Changed: ...
+Evidence: ...
+Tests: ...
+Unresolved: ...
+Next: ...
+```
+
+This applies to complete, aborted/cancelled, auto-dropped, full-auditor-IMPOSSIBLE,
+and already-shipped archive paths. A valid executor recap is preserved. A
+partial IMPOSSIBLE verdict remains a decision pause in conservative mode (or
+continues narrowing in aggressive mode); only a full impossible objective is
+terminalized. A missing, generic, or incomplete recap is replaced at the
+central archive boundary by a
+fallback assembled only from recorded GLLA facts: the objective, terminal
+status/reason, durable telemetry, captured audit verdicts, and known archive
+path. It says `not recorded` when a changed-file manifest or test result is not
+available. It never infers a passing test or invents a commit.
+
+The full recap lives in the archive and status/history surfaces. Every
+terminal goal notification—including version-bearing already-shipped claims,
+explicit goal/list cancellation, and `/glla wipe`—includes a compact
+projection of all six labels; loop notifications do the same. The terminal
+notification may use a compact excerpt. The executor recap and independent
+auditor verdict stay separate: an approval is not manufactured from the
+presence of a summary.
+
+Metric-loop stops use the same six-label contract in their durable loop state
+and `/loop status`, and every terminal loop notification carries a compact
+projection of that recap. Lifecycle/recovery holds are not falsely presented
+as terminal completion.
+
+## Future decision checklist
+
+Before adding a new long-running GLLA path, record answers to these questions:
+
+1. What durable or lifecycle signal proves start, progress, recovery, and
+   completion?
+2. If the host has no signal, what is the adaptive fallback, and what bounded
+   watchdog identifies confirmed silence without guessing task duration?
+3. Which failures are recoverable, and which state-based conditions stop
+   automation? Is the retry idempotent across reload and owner changes?
+4. What exact six-label user recap is available after every terminal path? Which
+   values are recorded facts, and which must explicitly say `not recorded`?
+5. Does the change stay at GLLA's public boundary and preserve persistence,
+   ownership, lifecycle, auditor, and user-stop semantics?
+
+Do not solve an external Pi/core defect by widening GLLA's scope. Keep the
+external-only issue as a documented observation or a separate upstream report.

package/docs/DESIGN.md

@@ -117,19 +117,19 @@ architectural decisions that changed the SHAPE of the system:
 - **The durable claim owns recovery state**: `pendingCompletion.phase` is
   `running`, `recovery-pending`, or `quota-waiting`. Missing phase is legacy
   state and is treated as recovery-pending after a fresh lifecycle event.
-  The isolated attempt id and wall deadline prevent an old generation from
-  finalizing a newer attempt.
+  The isolated attempt id prevents an old generation from finalizing a newer
+  attempt; legacy wall-deadline metadata is not a lifetime bound.
 - **Rebind recovery is immediate but consent-aware**: a replacement
   `session_start` converts an old running claim to recovery-pending and
   retries it immediately when the lifecycle handoff or global `autoResume`
   supplies consent. A cold startup with autoResume off paints the pending
   claim and waits for `/goal resume`.
-- **Auditor bounds have two layers**: no-event inactivity aborts after 10m
-  only when no auditor tool is active; a live verification tool may finish,
-  but the complete isolated run has a 30m wall-clock cap. Each auditor tool
-  also has an independent five-minute ceiling. Both outcomes are
-  infrastructure failures, never verdicts, and the stored claim remains
-  retryable.
+- **Auditor liveness has event-derived layers**: no-event inactivity aborts
+  after 10m only when no auditor tool is active; a live verification tool may
+  finish, and the complete isolated run has no unconditional wall-clock cap.
+  Each auditor tool also has an independent five-minute ceiling. These
+  watchdog outcomes are infrastructure failures, never verdicts, and the
+  stored claim remains retryable.
 
 ## Addendum v0.34.22 (detached completion auditor)
 
@@ -140,9 +140,10 @@ architectural decisions that changed the SHAPE of the system:
   never loads glla extensions or project context files. In current power mode,
   bash is not an OS sandbox: it can write repository or goal-state files, so
   the worker's isolation is process/API isolation rather than immutability. The
-  worker has independent per-tool and wall-clock bounds. This removes the
-  previous nested `AgentSession` from the main pi process and prevents a
-  provider stall in the auditor from occupying the executor's turn.
+  worker has independent per-tool and confirmed-silence bounds, with no
+  unconditional wall-clock expiry. This removes the previous nested
+  `AgentSession` from the main pi process and prevents a provider stall in the
+  auditor from occupying the executor's turn.
 - **Durable job protocol**: request, progress, lock, and result files live
   under `.pi-glla/audit-jobs/<attemptId>/`. Requests and results are hashed and
   atomically written. The parent validates attempt/request identity, verdict
@@ -160,10 +161,12 @@ architectural decisions that changed the SHAPE of the system:
   `audit recovery pending` are distinct. The main session can continue
   rendering and accepting input while the worker audits; completion/archive or
   disapproval/continuation happens only after durable result consumption.
-- **Bounded worker liveness**: no session event for 10 minutes while no
-  auditor tool is active aborts the worker; a five-minute per-tool ceiling and
-  30-minute wall-clock bound always win. Both are infrastructure failures,
-  never verdicts, and the claim remains retryable.
+- **Event-derived worker liveness**: no session event for 10 minutes while
+  no auditor tool is active aborts the worker; a five-minute per-tool ceiling
+  remains armed while a tool is open. There is no unconditional wall-clock
+  bound, so active output/tool progress may continue indefinitely. Watchdog
+  outcomes are infrastructure failures, never verdicts, and the claim remains
+  retryable.
 
 ## Addendum v0.34.24 (dispatch proof and display projection safety)
 
@@ -354,6 +357,23 @@ replacement without delivering a successor `session_start`:
   and normalize old files. Canonical persisted state uses `retry-waiting`,
   `retryAttempts`, `retryFirstAt`, and `retryUntil`.
 
+## Addendum v0.35.71 (GLLA-only external-failure containment)
+
+GLLA is a workflow supervisor, not a maintenance fork of its host ecosystem.
+The repository changes only GLLA-owned code. Pi-core, OS, provider, and
+third-party-plugin failures may be observed through public hooks and contained
+by durable GLLA state (for example, a BUSY/no-stream turn can be aborted,
+parked, and retried within a finite configured budget), but GLLA never edits
+those external implementations or claims to repair them. Reports whose only
+code lives outside GLLA are explicitly documented and disposed of as
+out-of-scope.
+
+The zero-stream budget defaults to three automatic re-dispatches and accepts
+0–10. Each uninterrupted silent attempt consumes one slot; a real stream
+starts a fresh episode. Exhaustion leaves the goal/list item/loop parked for
+explicit resume. Generation, supervisor-pause, persistence, and dispatch
+ownership fences remain authoritative throughout.
+
 ## Addendum v0.35.0 (long-running judgment, Designer, and drafting chain)
 
 - **Judgment is a prompt-level contract**: drafting and continuation preserve

package/docs/INDEX.md

@@ -18,11 +18,13 @@ 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.64 continue through the supervisor freeze (`/glla pause`),
+  v0.35.14–v0.36.0 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,
   durable state-root selection, blank-until-resume auditor context, frozen
-  subagent recovery, and bounded repair/replan recovery — see CHANGELOG.md for
+  subagent recovery, bounded repair/replan recovery, production RPC child
+  stopping, mandatory hermetic auditor-extension validation, optional provider
+  extensions, and bounded zero-stream retry containment — see CHANGELOG.md for
   the full trail.
 - `../README.md` — what the plugin is, install, quickstart, and the
   architectural guarantee (drafting + confirm + detached auditor).
@@ -39,6 +41,7 @@ For shipped docs, the relevant entry points are:
 
 ## Architecture
 - `DESIGN.md` — plugin design (types, state, extension lifecycle)
+- `DESIGN-long-running-supervision.md` — v0.36.0 event/progress-driven supervision, aggressive recovery, terminal recaps, and future decision checklist
 - `GLLA-POSITIONING-AND-DECOMPOSITION-2026-08-08.md` — ecosystem
   positioning, competitor review, and the goal.ts decomposition plan
   (the current strategic doc — read this before touching
@@ -51,6 +54,7 @@ For shipped docs, the relevant entry points are:
 - `../schemas/` — goal state JSON schema
 - `../examples/` — example objective files
 - `../CHANGELOG.md` — user-facing changelog (unreleased at top)
+- `/glla bug` — `extensions/goal-commands.ts:cmdGllaBug` captures failure context to `<stateDir>/bugs/<ts>-<id>.md` without touching `active.jsonl`/`goals/*.md` (see `tests/glla-bug-capture.test.ts`)
 
 ## Repository-only material
 The audit history and competitor research live in `audit/` and `.research/`

package/docs/VISION-ASSIST.md

@@ -1,60 +1,52 @@
-# Vision Assist — see with mmx, not a model switch
+# Vision Assist — native vision first; external tools optional
 
-**v0.34.72** · note.md 2026-08-07: *"the agent is too eager when couldnt see it
-tried to use expensive mdoels. we need to special a vision setting where it
-called another model or cli like mmx vision to see if stuck. but not just this
-we need to specify that it cant be too eager to switch only preapproved."*
+**v0.34.72 policy update** · The executor/auditor should use the native image
+capability of the model currently doing the work whenever it is available.
+No external vision CLI, including MMX, is assumed to be installed.
 
 ## Policy
 
-The executor (pi's main agent) has no eyes. When a task needs it to **look**
-at something — a screenshot, a UI state, an error dialog, a rendered mockup —
-it must NOT switch models to get vision. The check routes to the **mmx vision
-CLI** (the `mmx-cli` skill, MiniMax VLM):
+When a task needs the model to **look** at a screenshot, UI state, error dialog,
+or rendered mockup:
 
-```bash
-mmx vision describe --image <path-or-url> --prompt "<question>" --quiet --non-interactive
-```
+1. Use the current model's native image capability first. This means the main
+   model for executor work or the configured auditor model for detached audit
+   work.
+2. Do not switch models merely to obtain vision.
+3. If native image input is unavailable, use an external vision provider only
+   after its availability has been explicitly confirmed. MMX is an optional
+   example, not a default or package requirement:
 
-- The image is usually a screenshot the user already pasted into the
-  conversation (e.g. `/home/dracon/Pictures/Screenshots/...`). Pass its path
-  straight through.
-- Keep the question short and specific: *"What does this screenshot show?"*,
-  *"Is there an error dialog?"*, *"What is the terminal output?"*.
-- Reading the returned description is the agent's job — no model switch
-  needed. (Verified 2026-08-07: `mmx vision describe` returns clean JSON/text
-  with `status_code: 0`.)
+   ```bash
+   mmx vision describe --image <path-or-url> --prompt "<question>" --quiet --non-interactive
+   ```
 
-## The preapproval gate (model switches)
+4. If neither native vision nor a confirmed external provider is available,
+   state that visual evidence is unavailable and request a supported capture or
+   user description. Never invent a visual observation or silently assume MMX.
 
-A model switch is sanctioned **only when the target is preapproved** — i.e.
-NOT in the `forbiddenModels` policy:
+## The preapproval gate (model switches)
 
-- Default forbidden list: empty — no opinionated ban list ships. Users can
-  add patterns such as `gpt-5.5`, `sonnet`, or `opus`; matches are
-  case-insensitive substrings against the `provider/id` ref.
-- `/glla` → **Keep-going** → **Forbidden models** edits the list;
-  `blockForbiddenModelSwitches` (default on) reverts an explicitly forbidden
-  selection to the previous model.
-- Every switch to a forbidden model is ledgered as `forbidden_model_switch`
-  (with `blocked: true|false`).
-- With vision assist on (default), the same event also appends a
-  `vision_assist` ledger entry — the routing alternative: `{ route:
-  "mmx-vision", blockedSwitch: <ref>, reason: "forbidden_model_switch" }`.
+A model switch is not the default solution to a visual check. A preapproved
+model may be selected only when the user explicitly requests it or it is needed
+for the ordinary task—not as an assumed vision workaround.
 
-Even a preapproved vision-capable model is a second choice: mmx vision is the
-default for every vision check.
+- Default `forbiddenModels` is empty; users may add patterns such as `gpt-5.5`,
+  `sonnet`, or `opus`.
+- `/glla` → **Keep-going** → **Forbidden models** edits that list.
+- `blockForbiddenModelSwitches` (default on) blocks explicitly forbidden
+  selections and records `forbidden_model_switch`.
+- Vision routing is recorded as `vision_assist`, including the selected route
+  (`main-model`, confirmed `mmx-vision`, `model-switch`, or `unavailable`).
 
 ## The setting
 
 `visionAssist` (default **on** — opt-out):
 
-- **on** → every continuation prompt carries the `## VISION-ASSIST — SEE WITH
-  MMX, NOT A MODEL SWITCH` directive (`extensions/vision-assist.ts`
-  `VISION_ASSIST_GUIDANCE`), and a forbidden switch also records the
-  `vision_assist` routing entry.
-- **off** → no vision guidance is injected; the `forbiddenModels` gate still
-  stands (forbidden switches remain blocked/ledgered).
+- **on** → continuation prompts carry the native-vision-first guidance and
+  forbidden-switch events can record a `vision_assist` entry.
+- **off** → no vision guidance is injected; the forbidden-model gate still
+  stands.
 
 Edit: `/glla` → **Keep-going** → **Vision assist**, then choose **off**.
 
@@ -63,13 +55,15 @@ Edit: `/glla` → **Keep-going** → **Vision assist**, then choose **off**.
 | Piece | Where |
 |---|---|
 | Guidance block (single source of truth) | `extensions/vision-assist.ts` → `VISION_ASSIST_GUIDANCE` |
-| Command builder | `visionDescribeCommand(imagePath, question?)` |
-| Routing rule (pure) | `routeVisionCheck(request)` — mmx by default; forbidden target → mmx + `blockedSwitch`; preapproved target → `model-switch` allowed |
+| Optional MMX command builder | `visionDescribeCommand(imagePath, question?)` |
+| Routing rule (pure) | `routeVisionCheck(request)` — native main-model route by default; confirmed MMX is optional; forbidden target never forces an unconfirmed tool |
 | Ledger payload builder | `visionAssistLedger(route, request)` |
-| Continuation injection | `extensions/goal-continuation.ts` pushes `VISION_ASSIST_GUIDANCE` into the continuation directives (gated on `visionAssist !== false`) |
+| Continuation injection | `extensions/goal-continuation.ts` pushes `VISION_ASSIST_GUIDANCE` into continuation directives (gated on `visionAssist !== false`) |
+| Visual audit prompt | `extensions/goal-loop-auditor.ts` requires fresh evidence and does not assume an external tool |
 | 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` |
+| Setting | `extensions/goal-settings.ts` (default true), menu row in `extensions/settings-menu.ts` |
 | Tests | `tests/vision-assist.test.ts` |
 
-The `vision_assist` ledger type is the audit trail: every entry says where the
-check routed and (when a switch was blocked) which model was refused.
+The `vision_assist` ledger entry is the audit trail: it says whether the check
+used the current model, a confirmed optional provider, an explicitly allowed
+model switch, or had no safe visual path.