pi-goal-list-loop-audit 0.34.50 → 0.34.79

package/README.md

@@ -248,33 +248,49 @@ Activity is otherwise intentionally honest:
 | `QUEUED` | A continuation is waiting to start; no work is fabricated. |
 | `IDLE` | The durable item remains active, but no recent work is observed. |
 | `auditor …` | A detached, extension-less verifier is queued, running, quiet, or waiting for its verdict. |
-| `QUOTA WALL` | The provider rejected the request for a quota/plan window; saved work is waiting for a durable probe. |
-
-Quota walls deliberately do **not** get more blind request retries. A bare
-429/rate-limit response is treated as a transient throttle; explicit plan,
-usage, billing, reset, and provider-code language is classified more strongly.
-For example, MiniMax's `Token Plan rate limit reached … (2062)` asks for an
-upgrade or pay-as-you-go billing and is not the same thing as a per-minute
-throttle. Output/context-token stops are handled separately and never become a
-quota wall. pi's request-local retry counter is bounded; glla owns the longer
-recovery window: generic throttles use `15m → 30m → 1h → 2h → 4h → 5h`; a
-plan wall with no reset hint starts at `1h → 2h → 4h → 5h`. Automatic probes
-stop after 24h.
-A provider hint is honored when it is within the five-hour probe budget; a
-week-long hint is shown and held for manual action instead of scheduling a
-hidden week-long timer. With global `autoResume=on`, pending probes survive a
-session reload. After the safety horizon, `/list resume`, `/goal resume`, or
-`/loop resume` explicitly starts a fresh bounded window. For continuous work,
-configure ordered **Main model backups** in `/glla` using a model from a
-different provider or billing/quota pool — another model on the same exhausted
-plan is not a real fallback.
-
-Classification is conservative: explicit 429/rate-limit/plan-limit/token-plan
-signals are quota walls; ordinary `503 temporarily unavailable`, `403
-forbidden`, auth failures, and ambiguous provider prose are not relabeled as
-quota. Credit/billing exhaustion gets a manual-action hold. The raw provider
-message remains in the ledger/durable state for diagnosis, while the card
-shows the classified reason and recovery action.
+| `QUOTA WALL` | The provider rejected the request for a quota/plan window (by its own wording); saved work is waiting for a durable probe. |
+
+## Provider failures: one retry envelope, bounded (v0.34.51)
+
+Error text is **not trusted** to pick a retry policy: we only know that an
+error came, and provider messages vary. Every main-model failure — quota,
+rate limit, billing/credits, auth, transient, or unclassifiable — rides the
+same durable recovery envelope `15m → 30m → 1h → 2h → 4h → 5h` (probe cap
+5h, automatic window 24h, then an explicit `/goal resume`/`/list resume`/
+`/loop resume` starts a fresh window). The only failures that do not auto-retry
+are the ones identified by *positive evidence* as futile: context/output-token
+limits and user aborts (`non-recoverable`), plus auditor watchdog timeouts
+(a hanging verification command will hang again — the stored claim waits for
+an explicit resume).
+A provider hint (`retry_after`/`reset_at`) is honored when it fits the
+five-hour probe budget; an over-budget hint (e.g. a week-long reset) never
+parks the goal — the bounded cadence owns the wait, and only the 24h horizon
+ends automatic probes (a `/goal resume`/`/list resume`/`/loop resume` then
+starts a fresh window). With global `autoResume=on`, pending
+probes survive a session reload. For continuous work, configure ordered
+**Main model backups** in `/glla` using a model from a different provider or
+billing/quota pool — another model on the same exhausted plan is not a real
+fallback.
+
+**Quota walls engage fast** (v0.34.57): a surfaced long-lived failure
+(quota / billing / auth) records a 30-minute knowledge window; a send-rearm
+storm inside that window escalates into the recovery envelope after **3
+minutes** of failed sends instead of the generic 15 — a wedge right after a
+quota wall is almost always the same wall. Transient (5xx/stream/network)
+failures never record the signal and keep the fast error ladder. The
+envelope is armed by configuration: an empty `mainModelFallbacks` list means
+"park and probe the same model" rather than switching pools — the
+never-switch posture is a first-class policy, not an accident.
+
+Classification still exists, but it only *labels*: the card and badge show
+what the provider said (quota wall, billing, rate limit) so the reason is
+diagnosable, and `QUOTA WALL` is only shown when the provider's own words say
+quota — ambiguous prose is never relabeled. The raw provider message stays in
+the ledger/durable state; the card shows the classified reason and recovery
+action. Detached-auditor failures get the same treatment: any infrastructure
+error on a stored completion claim pauses the goal with a durable bounded
+one-shot retry (`auditor retry: …`), and only the plan's 24h horizon stops
+automatic probes.
 
 The quota-specific card hides raw provider JSON while preserving it in durable
 state and the ledger:
@@ -337,6 +353,16 @@ warning says no replacement arrived, restart pi normally and let the saved
 mux dependency. The legacy `autoReloadOnStale` and `autoRecovery` fields remain
 only as deprecated settings-file compatibility fields; they are ignored.
 
+**A stale handle never mutates** (v0.34.51–v0.34.54): every `/list` mutation
+(add/remove/next/clear/cancel) and the bare `/glla` settings surface probe at
+entry and refuse with the standard recovery message on a stale extension
+context — a session that cannot announce or run its writes must not make them.
+Mutating `/glla` actions (wipe/cancel/reviewer/postaudit/tooloverride) leave a
+`settings_mutation_refused_stale` ledger trail; read-only surfaces (`/list
+show`, `/goal status`) stay usable with the warning. Once the replacement
+`session_start` arrives, both surfaces render cleanly with no stale residue
+(the lifecycle-recovery harness proves the two-phase contract).
+
 **User aborts mean STOP** (v0.29.4): Esc-aborting a turn stands the chain
 down with a named notify (`/goal resume` to continue) — it does NOT count
 toward stall warnings, does NOT auto re-fire, and the stand-down survives

package/docs/DESIGN.md

@@ -197,6 +197,63 @@ architectural decisions that changed the SHAPE of the system:
   cycle. Manual model selection cancels it; goal/list/loop cancellation clears
   its timer and durable state.
 
+## Addendum v0.34.48–v0.34.56 (lifecycle/recovery hardening — the stale-handle era)
+
+Between the v0.34.31 recovery envelope and the v0.34.57 quota fast-engagement, the
+recovery story hardened around the **stale extension handle** — the field-observed
+shape (hegemon/polis 2026-07-26+) where pi invalidates the extension API on session
+replacement without delivering a successor `session_start`:
+
+- **Honest stale entry everywhere** (v0.34.51/52): `warnIfStaleAtEntry` probes at
+  entry (since v0.28.1), but the probe's return value used to be discarded by the
+  mutation paths. Now every `/list` mutation (add/remove/next/clear/cancel) and the
+  bare `/glla` settings surface refuse on a stale handle with the standard recovery
+  message — a session that cannot announce or run its writes must not make them.
+  Mutating `/glla` actions (wipe/cancel/reviewer/postaudit/tooloverride) refuse with
+  a `settings_mutation_refused_stale` ledger trail; read-only surfaces stay usable
+  with the warning. This is the plugin side of the missing-replacement contract: fail
+  closed, never guess, never pretend success.
+- **Settings routing clarity** (v0.34.53): `/list settings` is a verb, handled
+  explicitly BEFORE the natural-language dump fallthrough — a ledgered redirect to
+  `/glla`, never a drafting seed. `/list add settings …` remains the only way an item
+  literally named "settings" enters the queue.
+- **Lifecycle-recovery harness** (v0.34.54): a behavioral suite proves the two-phase
+  contract — stale handle: `/list show` warns and does not pretend, settings refuse
+  wholesale; fresh `session_start`: both render cleanly with no stale residue.
+- **Command-registration collision model** (v0.34.55): pi's `resolveRegisteredCommands`
+  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.
+- **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
+  rule: display evidence-gates on `unmatchedStarts + unmatchedEnds > 0`).
+- **Uniform retry envelope, no text-trust** (v0.34.51): error text is not trusted to
+  pick a retry policy. Quota, billing, auth, transient, and unknown failures all ride
+  ONE bounded durable envelope `15m → 30m → 1h → 2h → 4h → 5h` (cap 5h, automatic
+  window 24h); classification only labels the display. The billing-hold special case
+  is removed (`main_model_billing_hold` is legacy). Positive-evidence futile classes
+  (context/output-token limits, user aborts) plus auditor watchdog timeouts never
+  auto-retry; provider hints are honored only within the 5h probe budget.
+
+## Addendum v0.34.57 (quota walls engage recovery fast)
+
+- **Knowledge-window escalation**: a surfaced long-lived failure (quota /
+  billing / auth) records a 30-minute knowledge window. A send-rearm storm
+  inside that window escalates into the recovery envelope after 3 minutes of
+  failed sends (plus the unchanged 5-minute activity silence gate) instead of
+  the generic 15 minutes — a wedge right after a quota wall is almost always
+  the same wall, and blind re-sends into it are pure waste.
+- **Transient failures stay fast**: 5xx/stream/network failures are
+  short-lived by definition and never record the knowledge signal; they keep
+  the 5s→3m error ladder and the pi-core retry budget.
+- **Armed by configuration**: the envelope is inert without
+  `mainModelFallbacks` (rotation) — an empty list means "park and probe the
+  same model" instead of switching pools.
+
 ## Addendum v0.4.0 (completion)
 
 - **Auditor compaction enabled** (flaw #3 — the last open one). Safety:

package/docs/RELEASING.md

@@ -17,6 +17,12 @@ the repository.
 
 ## Release checklist
 
+Accumulated changes since the last release live under an `## Unreleased`
+section at the top of `CHANGELOG.md` (with the in-repo milestone labels such
+as `### 0.34.51`); the release commit renames that section to the released
+version. Do not invent version headers for work that was never tagged —
+untagged work stays under `Unreleased` until the release commit.
+
 ```bash
 npm version <major.minor.patch> --no-git-tag-version
 npm run release:check

package/docs/VISION-ASSIST.md

@@ -0,0 +1,73 @@
+# Vision Assist — see with mmx, not a model switch
+
+**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."*
+
+## 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):
+
+```bash
+mmx vision describe --image <path-or-url> --prompt "<question>" --quiet --non-interactive
+```
+
+- 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`.)
+
+## The preapproval gate (model switches)
+
+A model switch is sanctioned **only when the target is preapproved** — i.e.
+NOT in the `forbiddenModels` policy:
+
+- Default forbidden list: `gpt-5.5`, `sonnet`, `opus` (matched
+  case-insensitively as a substring against the `provider/id` ref).
+- `/glla forbiddenModels=...` edits the list; `blockForbiddenModelSwitches`
+  (default on) reverts a 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" }`.
+
+Even a preapproved vision-capable model is a second choice: mmx vision is the
+default for every vision check.
+
+## 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).
+
+Edit: `/glla` → Keep-going → Vision assist, or `/glla visionAssist=off`.
+
+## Implementation map
+
+| 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 |
+| 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 |
+| 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` |
+
+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.

package/extensions/confirm-draft.ts

@@ -0,0 +1,130 @@
+// pi-goal-list-loop-audit — v0.2.0
+// extensions/confirm-draft.ts
+//
+// v0.34.78 (GitHub #4): the draft-class confirm dialog as a real TUI
+// component. ctx.ui.select renders plain text with no wrapping; this
+// component renders the SAME title/body as Markdown (objective + contract
+// readable at full width) with a SelectList for the Yes / Yes-and-always /
+// No choices. Kept in its own file so tests can construct and render it
+// without dragging in the whole goal loop.
+
+import {
+  type Component,
+  Container,
+  Markdown,
+  type MarkdownTheme,
+  type SelectItem,
+  SelectList,
+  type SelectListTheme,
+  Spacer,
+  Text,
+} from "@earendil-works/pi-tui";
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+
+export interface ConfirmDraftFactoryDeps {
+  title: string;
+  body: string;
+  options: string[];
+}
+
+/** Structural type for the KeybindingsManager — mirrors settings-menu.ts. */
+export interface KeybindingsManagerLike {
+  matches(data: string, key: string): boolean;
+}
+
+/** Pure: the markdown rendered in the dialog. The title is the H1, the
+ * body (objective + verification contract) is the content. */
+export function buildConfirmDraftMarkdown(title: string, body: string): string {
+  return `# ${title}\n\n${body}`;
+}
+
+/** Build a MarkdownTheme from the runtime Theme's fg()/bold() primitives.
+ * Uses the theme's own md* colors so the dialog follows the active theme. */
+function markdownTheme(theme: Theme): MarkdownTheme {
+  const fg = (color: Parameters<Theme["fg"]>[0]) => (t: string) => theme.fg(color, t);
+  return {
+    heading: (t) => theme.bold(fg("mdHeading")(t)),
+    link: (t) => fg("mdLink")(t),
+    linkUrl: (t) => fg("mdLinkUrl")(t),
+    code: (t) => fg("mdCode")(t),
+    codeBlock: (t) => fg("mdCodeBlock")(t),
+    codeBlockBorder: (t) => fg("mdCodeBlockBorder")(t),
+    quote: (t) => fg("mdQuote")(t),
+    quoteBorder: (t) => fg("mdQuoteBorder")(t),
+    hr: (t) => fg("mdHr")(t),
+    listBullet: (t) => fg("mdListBullet")(t),
+    bold: (t) => theme.bold(t),
+    italic: (t) => t,
+    strikethrough: (t) => t,
+    underline: (t) => t,
+    codeBlockIndent: "  ",
+  };
+}
+
+function selectListTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: (t) => theme.fg("accent", t),
+    selectedText: (t) => theme.fg("accent", t),
+    description: (t) => theme.fg("muted", t),
+    scrollInfo: (t) => theme.fg("dim", t),
+    noMatch: (t) => theme.fg("warning", t),
+  };
+}
+
+/**
+ * The confirm dialog: DynamicBorder frame, markdown title+body, spacer, the
+ * three-choice SelectList, and a help line. Exported so tests can construct
+ * it with a fake theme and assert the rendered lines.
+ */
+export class ConfirmDraftComponent implements Component {
+  private readonly md: Markdown;
+  private readonly selectList: SelectList;
+  private readonly requestRender: () => void;
+  private readonly theme: Theme;
+  private readonly keybindings: KeybindingsManagerLike;
+
+  constructor(
+    deps: ConfirmDraftFactoryDeps,
+    requestRender: () => void,
+    theme: Theme,
+    keybindings: KeybindingsManagerLike,
+    done: (value: string | undefined) => void,
+  ) {
+    this.requestRender = requestRender;
+    this.theme = theme;
+    this.keybindings = keybindings;
+    this.md = new Markdown(buildConfirmDraftMarkdown(deps.title, deps.body), 1, 1, markdownTheme(theme));
+    const items: SelectItem[] = deps.options.map((o) => ({ value: o, label: o }));
+    this.selectList = new SelectList(items, Math.min(items.length, 10), selectListTheme(theme));
+    this.selectList.onSelect = (item) => done(item.value);
+    this.selectList.onCancel = () => done(undefined);
+  }
+
+  render(width: number): string[] {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => this.theme.fg("borderAccent", s)));
+    container.addChild(this.md);
+    container.addChild(new Spacer(1));
+    container.addChild(this.selectList);
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(this.theme.fg("dim", "↑↓ navigate • enter select • esc cancel"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => this.theme.fg("borderAccent", s)));
+    return container.render(width);
+  }
+
+  invalidate(): void {
+    this.md.invalidate();
+    this.selectList.invalidate();
+    this.requestRender();
+  }
+
+  handleInput(data: string): void {
+    this.selectList.handleInput(data);
+    this.requestRender();
+  }
+
+  /** Exposed for tests. */
+  getSelectedItem(): string | null {
+    return this.selectList.getSelectedItem()?.value ?? null;
+  }
+}