@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/implementation-thinking.d.ts

@@ -2,41 +2,43 @@
  * Hold the host session at the `implementation` group's thinking level for the
  * duration of one implementation turn, then put it back.
  *
- * WHY THIS IS NOT LIKE THE OTHER SIX GROUPS
- * -----------------------------------------
- * Every other group is a child process, so its level is one argv flag and it
- * dies with the child. The implementation turn runs in the USER'S OWN session
- * (orchestrator.ts `sendSpec` → sendUserMessage → superviseImplementation), so
- * the only lever is `pi.setThinkingLevel`, which is session-global and visible.
+ * WHY THIS GROUP IS NOT LIKE THE OTHERS
+ * -------------------------------------
+ * Every other reasoning group runs in a child process, so its level is one argv
+ * flag (`--thinking <level>`, built in reasoning-args.ts) and it dies with the
+ * child. The implementation turn runs in the USER'S OWN session
+ * (orchestrator.ts `sendSpec` -> `sendUserMessage` -> `superviseImplementation`),
+ * so the only lever is `pi.setThinkingLevel`, which is session-global.
  *
- * THREE THINGS pi DOES that this has to survive. All three read from
- * pi-coding-agent's agent-session `setThinkingLevel`:
+ * THREE THINGS pi DOES that this has to survive:
  *
- *  1. IT PERSISTS. On a real change it calls
- *     `settingsManager.setDefaultThinkingLevel(...)`, writing
- *     `~/.pi/agent/settings.json`. This is not a session-local toggle — without
- *     the restore, running one task would silently rewrite the user's global
- *     default. That makes `release()` load-bearing, not tidy-up.
- *  2. IT CLAMPS, to what the model declares it supports. We may ask for `medium`
- *     and be given `off`. So the restore writes back what was READ after
- *     setting, never what was asked for — otherwise a clamp would ratchet the
- *     stored default a little further every run.
- *  3. IT IS OBSERVABLE, and the user can change it mid-turn (shift+tab cycles
- *     the level). Restoring blindly would clobber a choice they just made. We
- *     detect it by comparing the live level at release against what we applied:
- *     if it has moved, somebody else moved it, and we leave it alone.
+ *  1. IT PERSISTS. pi-coding-agent's agent-session `setThinkingLevel` calls
+ *     `settingsManager.setDefaultThinkingLevel(...)` whenever the effective
+ *     level actually changes, and that writes pi's global settings file
+ *     (`~/.pi/agent/settings.json`). Without the restore, running one task would
+ *     silently rewrite the user's global default. That makes `release()`
+ *     load-bearing, not tidy-up.
+ *  2. IT CLAMPS, to the levels the model declares. A model with no reasoning
+ *     support offers only `off`, so asking for `medium` yields `off`. The
+ *     restore therefore writes back what was READ after setting, never what was
+ *     asked for — otherwise a clamp would ratchet the stored default a little
+ *     further every run.
+ *  3. IT IS OBSERVABLE, and the user can change it mid-turn: `shift+tab` is the
+ *     default binding for `app.thinking.cycle`, and a change invalidates the
+ *     footer. Restoring blindly would clobber a choice they just made. We detect
+ *     it by comparing the live level at release against what we applied: if it
+ *     has moved, somebody else moved it, and we leave it alone.
  *
- * We compare rather than subscribe because `pi.on` returns no unsubscribe
- * handle, so a per-turn listener could only ever be added, never removed. The
- * comparison answers the same question with no accumulating state.
+ * We compare rather than subscribe because the extension API's `on(...)` returns
+ * `void` — there is no unsubscribe handle — so a per-turn listener could only
+ * ever be added, never removed. The comparison answers the same question with no
+ * accumulating state.
  */
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import { type GroupSetting } from '../config/reasoning.js';
 /**
- * The slice of the extension API this needs, named so tests can drive it without
- * a live pi session. Every other dependency in `RunSingleTaskOptions` is
- * injectable; this one has to be too, or the restore logic is only exercisable
- * by running a real task.
+ * The slice of the extension API this needs, named so tests can drive the
+ * hold-and-restore with a fake object instead of a live pi session.
  */
 export interface ThinkingControl {
     get(): ThinkingLevel;
@@ -47,8 +49,8 @@ export interface ThinkingControl {
  * that puts it back. Always call the returned function — `finally`, not the
  * happy path.
  *
- * `inherit` makes NO call at all, not even a redundant set-to-current: a set
- * that happens to be a no-op still goes through pi's change detection, and the
- * shipped default must not touch the user's settings file.
+ * `inherit` makes NO call at all, not even a redundant set-to-current. It means
+ * the same thing here as in `thinkingArgs`, which emits no `--thinking` flag for
+ * it: leave the level wherever it already is.
  */
 export declare function holdImplementationThinking(control: ThinkingControl, setting?: GroupSetting): () => void;

package/dist/task/implementation-thinking.js

@@ -5,9 +5,9 @@ import { resolveReasoning } from '../config/reasoning.js';
  * that puts it back. Always call the returned function — `finally`, not the
  * happy path.
  *
- * `inherit` makes NO call at all, not even a redundant set-to-current: a set
- * that happens to be a no-op still goes through pi's change detection, and the
- * shipped default must not touch the user's settings file.
+ * `inherit` makes NO call at all, not even a redundant set-to-current. It means
+ * the same thing here as in `thinkingArgs`, which emits no `--thinking` flag for
+ * it: leave the level wherever it already is.
  */
 export function holdImplementationThinking(control, setting = resolveReasoning('implementation', getConfig())) {
     if (setting === 'inherit')
@@ -21,9 +21,8 @@ export function holdImplementationThinking(control, setting = resolveReasoning('
         return () => { };
     let released = false;
     return () => {
-        // Idempotent: the caller's `finally` may run alongside an outer one on an
-        // abort path, and a second restore would fight a user change made in
-        // between.
+        // Idempotent by contract: only the first call restores. A later call
+        // would write `before` on top of whatever the level is by then.
         if (released)
             return;
         released = true;

package/dist/task/implementation-turn.d.ts

@@ -7,12 +7,13 @@
  *   • `aborted`     — a user ESC (or the command watchdog) cut the turn short;
  *   • `compaction`  — a threshold auto-compaction parked the turn at idle without
  *                     auto-continuing (the runtime expects a manual continue);
- *   • `error`       — the model/provider died mid-turn after pi's own retries;
+ *   • `error`       — the model or provider failed after pi exhausted the retries
+ *                     in its own retry settings;
  *   • `stop`        — genuine completion.
- * `classifyTurnEnd` reads the session entries and names ONE of those, in the
- * precedence the supervision sequence needs; `superviseImplementation` then
- * resumes across compactions, lets the user steer after an interrupt, and reports
- * the terminal outcome. The orchestrator calls it once.
+ * `classifyTurnEnd` reads the session entries and names ONE of those;
+ * `superviseImplementation` then resumes across compactions, lets the user steer
+ * after an interrupt, and reports the terminal outcome. The orchestrator calls it
+ * from one place, inside the `sendSpec` closure.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 /** How the most recent implementation turn ended. See {@link classifyTurnEnd}. */
@@ -34,21 +35,20 @@ export type SessionEntryLike = {
 /**
  * Classify how the most recent turn ended, from the session entries alone.
  *
- * Precedence, when several signals are present at once (this is the order the
- * supervision sequence has always applied, now stated in one place):
+ * Precedence, when several signals are present at once:
  *   1. `aborted`    — the last assistant message has stopReason "aborted". A user
  *                     ESC (or watchdog abort) wins over everything: it is not a
  *                     compaction pause, and the steer loop owns it.
  *   2. `compaction` — a `compaction` entry sits AFTER the last assistant message.
- *                     Position-based, not timestamp-based: the runtime appends the
- *                     boundary to the tail of the branch after the message that
- *                     triggered it (`appendCompaction` → `_appendEntry` push), so a
+ *                     Position-based, not timestamp-based: `appendCompaction`
+ *                     pushes the boundary onto the tail of the entry list, and
+ *                     `getEntries()` returns that list in append order, so a
  *                     trailing compaction means we are parked with no continuation.
- *                     A finished turn ends on an assistant message; an *overflow*
- *                     compaction self-retries and never leaves us idle here.
- *   3. `error`      — the last assistant message has stopReason "error": the
- *                     model/provider died (context-overflow 400, disconnect, 5xx)
- *                     after pi exhausted its own retries.
+ *                     A finished turn ends on an assistant message. An overflow
+ *                     compaction that is going to retry continues the turn itself
+ *                     and never reaches us idle.
+ *   3. `error`      — the last assistant message has stopReason "error": the model
+ *                     or provider failed after pi exhausted its own retries.
  *   4. `stop`       — anything else, including a session with no assistant turn.
  */
 export declare function classifyTurnEnd(entries: ReadonlyArray<SessionEntryLike>): TurnEnd;
@@ -78,10 +78,11 @@ export type SteerCtx = ExtensionCommandContext & {
 };
 /**
  * Timing knobs for the watchdog-abort guard in {@link steerUntilDone}, injectable
- * so tests exercise the grace expiry without a 10-second wait. `graceMs` bounds
- * how long the loop waits for the watchdog's follow-up to be DELIVERED (not to
- * finish — its turn may legitimately run for minutes afterwards); delivery is
- * normally near-instant, so the grace only expires on a stale flag.
+ * so a test can exercise the grace expiry without waiting it out. `graceMs`
+ * bounds how long the loop waits for the watchdog's follow-up to be DELIVERED,
+ * not to finish: once it lands, the wait for its turn is unbounded. `onFire`
+ * sends the follow-up in the same block that raised the flag, so the grace
+ * expires only when the flag was already stale.
  */
 export interface SteerWatchdogDeps {
     consume: () => boolean;
@@ -95,6 +96,8 @@ export interface SteerWatchdogDeps {
 export interface ImplementationTurnDeps {
     /** The live session entries — the only thing the classifier reads. */
     entries: () => ReadonlyArray<SessionEntryLike>;
+    /** Test seam over the module-level one-shot; the real reader is the default. */
+    consumeGuardTermination?: () => boolean;
     /** Queue a follow-up user turn on the (idle) session. */
     send: (text: string) => Promise<void>;
     /** Wait for the session to go idle again. */
@@ -124,20 +127,23 @@ export declare function turnDepsFor(ctx: SteerCtx, opts?: SuperviseOptions): Imp
 /**
  * Nudge that resumes an implementation turn the runtime parked at a compaction
  * boundary. It must let a turn that was genuinely finished (then tipped over the
- * threshold by its own final message) confirm completion without inventing busywork
- * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
- * from the boundary alone, so the wording lets a done turn end in one line.
+ * threshold by its own final message) confirm completion without inventing busywork.
+ * The classifier sees only the boundary's POSITION, so it cannot tell "paused
+ * mid-task by compaction" from "finished, then compacted"; the wording lets a done
+ * turn end in one line.
  */
 export declare const CONTINUE_AFTER_COMPACTION: string;
 /**
  * Safety cap on compaction-driven resumes for a single implementation turn. Each
- * resume follows a real compaction (which only fires after the model produced a
- * turn large enough to cross the threshold), so a legitimately large task may
- * resume a handful of times; the cap exists only to stop a pathological loop from
- * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
- * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
+ * resume follows a real compaction, which pi only runs once `shouldCompact` says
+ * the context crossed its threshold. The cap exists to stop a pathological loop
+ * from auto-sending forever with no user watching. Hitting it stops resuming and
+ * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export declare const MAX_COMPACTION_RESUMES = 20;
+/** How a guard-stopped turn is reported. Named so a caller can tell it from a
+ *  provider error: the fix is a different task, not a retry of this one. */
+export declare const GUARD_TERMINATED = "the runaway guard stopped this turn: one tool call was repeated past every warning";
 /**
  * Resume an implementation turn that went idle at a threshold-compaction boundary.
  * The runtime compacts and parks at idle without auto-continuing; we send a
@@ -154,10 +160,12 @@ export declare function resumeAcrossCompactions(deps: ImplementationTurnDeps): P
  * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
  * the turn → idle). When the last turn was aborted, the host's main input loop is
  * blocked inside our command handler, so a message typed in the editor would only
- * queue, never run (interactive-mode routes idle input through onInputCallback,
- * which is unset while we hold the loop). We therefore solicit the steering text
- * ourselves and feed it back as another turn via sendUserMessage — which runs to
- * completion when the session is idle. Repeat until a turn finishes uninterrupted.
+ * queue, never run: interactive-mode's submit handler calls `onInputCallback` when
+ * the session is idle, and that callback is set only inside `getUserInput()` — the
+ * REPL loop we are holding — so the text lands in `pendingUserInputs` instead. We
+ * therefore solicit the steering text ourselves and feed it back as another turn
+ * via `sendUserMessage`, which forwards to `prompt()` and, on an idle session, runs
+ * the turn rather than queueing it. Repeat until a turn finishes uninterrupted.
  *
  * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
  * from a human ESC by the session entries alone at that instant. The watchdog

package/dist/task/implementation-turn.js

@@ -7,15 +7,17 @@
  *   • `aborted`     — a user ESC (or the command watchdog) cut the turn short;
  *   • `compaction`  — a threshold auto-compaction parked the turn at idle without
  *                     auto-continuing (the runtime expects a manual continue);
- *   • `error`       — the model/provider died mid-turn after pi's own retries;
+ *   • `error`       — the model or provider failed after pi exhausted the retries
+ *                     in its own retry settings;
  *   • `stop`        — genuine completion.
- * `classifyTurnEnd` reads the session entries and names ONE of those, in the
- * precedence the supervision sequence needs; `superviseImplementation` then
- * resumes across compactions, lets the user steer after an interrupt, and reports
- * the terminal outcome. The orchestrator calls it once.
+ * `classifyTurnEnd` reads the session entries and names ONE of those;
+ * `superviseImplementation` then resumes across compactions, lets the user steer
+ * after an interrupt, and reports the terminal outcome. The orchestrator calls it
+ * from one place, inside the `sendSpec` closure.
  */
 import { SessionUI } from '../remote/bridge.js';
 import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
+import { consumeGuardTermination } from './implementation-guards.js';
 const isAssistant = (e) => e.message !== undefined && e.message.role === 'assistant';
 /** Index of the last assistant message and of the last compaction boundary. */
 function tailPositions(entries) {
@@ -33,21 +35,20 @@ function tailPositions(entries) {
 /**
  * Classify how the most recent turn ended, from the session entries alone.
  *
- * Precedence, when several signals are present at once (this is the order the
- * supervision sequence has always applied, now stated in one place):
+ * Precedence, when several signals are present at once:
  *   1. `aborted`    — the last assistant message has stopReason "aborted". A user
  *                     ESC (or watchdog abort) wins over everything: it is not a
  *                     compaction pause, and the steer loop owns it.
  *   2. `compaction` — a `compaction` entry sits AFTER the last assistant message.
- *                     Position-based, not timestamp-based: the runtime appends the
- *                     boundary to the tail of the branch after the message that
- *                     triggered it (`appendCompaction` → `_appendEntry` push), so a
+ *                     Position-based, not timestamp-based: `appendCompaction`
+ *                     pushes the boundary onto the tail of the entry list, and
+ *                     `getEntries()` returns that list in append order, so a
  *                     trailing compaction means we are parked with no continuation.
- *                     A finished turn ends on an assistant message; an *overflow*
- *                     compaction self-retries and never leaves us idle here.
- *   3. `error`      — the last assistant message has stopReason "error": the
- *                     model/provider died (context-overflow 400, disconnect, 5xx)
- *                     after pi exhausted its own retries.
+ *                     A finished turn ends on an assistant message. An overflow
+ *                     compaction that is going to retry continues the turn itself
+ *                     and never reaches us idle.
+ *   3. `error`      — the last assistant message has stopReason "error": the model
+ *                     or provider failed after pi exhausted its own retries.
  *   4. `stop`       — anything else, including a session with no assistant turn.
  */
 export function classifyTurnEnd(entries) {
@@ -143,9 +144,10 @@ export function turnDepsFor(ctx, opts = {}) {
 /**
  * Nudge that resumes an implementation turn the runtime parked at a compaction
  * boundary. It must let a turn that was genuinely finished (then tipped over the
- * threshold by its own final message) confirm completion without inventing busywork
- * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
- * from the boundary alone, so the wording lets a done turn end in one line.
+ * threshold by its own final message) confirm completion without inventing busywork.
+ * The classifier sees only the boundary's POSITION, so it cannot tell "paused
+ * mid-task by compaction" from "finished, then compacted"; the wording lets a done
+ * turn end in one line.
  */
 export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compacted. Continue implementing this task from '
     + 'exactly where you left off, and keep going until it is fully done. If the '
@@ -153,13 +155,15 @@ export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compact
     + 'extra work or restart the task.';
 /**
  * Safety cap on compaction-driven resumes for a single implementation turn. Each
- * resume follows a real compaction (which only fires after the model produced a
- * turn large enough to cross the threshold), so a legitimately large task may
- * resume a handful of times; the cap exists only to stop a pathological loop from
- * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
- * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
+ * resume follows a real compaction, which pi only runs once `shouldCompact` says
+ * the context crossed its threshold. The cap exists to stop a pathological loop
+ * from auto-sending forever with no user watching. Hitting it stops resuming and
+ * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export const MAX_COMPACTION_RESUMES = 20;
+/** How a guard-stopped turn is reported. Named so a caller can tell it from a
+ *  provider error: the fix is a different task, not a retry of this one. */
+export const GUARD_TERMINATED = 'the runaway guard stopped this turn: one tool call was repeated past every warning';
 /**
  * Resume an implementation turn that went idle at a threshold-compaction boundary.
  * The runtime compacts and parks at idle without auto-continuing; we send a
@@ -209,10 +213,12 @@ async function awaitWatchdogFollowUp(deps) {
  * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
  * the turn → idle). When the last turn was aborted, the host's main input loop is
  * blocked inside our command handler, so a message typed in the editor would only
- * queue, never run (interactive-mode routes idle input through onInputCallback,
- * which is unset while we hold the loop). We therefore solicit the steering text
- * ourselves and feed it back as another turn via sendUserMessage — which runs to
- * completion when the session is idle. Repeat until a turn finishes uninterrupted.
+ * queue, never run: interactive-mode's submit handler calls `onInputCallback` when
+ * the session is idle, and that callback is set only inside `getUserInput()` — the
+ * REPL loop we are holding — so the text lands in `pendingUserInputs` instead. We
+ * therefore solicit the steering text ourselves and feed it back as another turn
+ * via `sendUserMessage`, which forwards to `prompt()` and, on an idle session, runs
+ * the turn rather than queueing it. Repeat until a turn finishes uninterrupted.
  *
  * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
  * from a human ESC by the session entries alone at that instant. The watchdog
@@ -258,6 +264,13 @@ export async function superviseWith(deps) {
     const interrupted = await steerUntilDone(deps);
     // A user-declined steer (interrupted) is its own paused path; otherwise
     // inspect how the turn actually ended.
-    const error = interrupted ? undefined : turnErrorMessage(deps.entries());
+    // The runaway guard ends a turn WITHOUT an error stopReason, so classifyTurnEnd
+    // reads `'stop'` and the caller would verify a half-done implementation and
+    // re-deliver to a model that deterministically re-thrashes. Consumed here
+    // because this is the one place that reports how the turn really ended.
+    const guardEnded = deps.consumeGuardTermination?.() ?? consumeGuardTermination();
+    const error = interrupted ? undefined
+        : guardEnded ? GUARD_TERMINATED
+            : turnErrorMessage(deps.entries());
     return { interrupted, error, resumes };
 }

package/dist/task/inline-markdown.d.ts

@@ -1,13 +1,26 @@
 /**
- * Inline-markdown helpers for the clarify/grill question dialogs.
+ * Inline-markdown helpers for the question dialogs (grill, clarify, /task-plan).
  *
- * The model often wraps the core question in **bold** (and code in backticks)
- * because it makes the question easier to read at a glance. ctx.ui.input titles
- * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
- * displayed prompt, and STRIP them to plain text for the editable input default
- * and the persisted task file (which must stay ANSI-free).
+ * The question arrives carrying markdown because our own prompts ask for it:
+ * auto-prompts.ts and plan-prompts.ts both say "Put the core question in
+ * **bold** ... Backticks around code/identifiers are fine."
+ *
+ * One question then needs two forms, and question-dialog.ts `settleQuestion`
+ * builds both:
+ *   • RENDERED — passed as `localTitle`, which reaches `ctx.ui.input`. pi wraps
+ *     that title in `theme.fg("accent", ...)` and hands it to a pi-tui `Text`,
+ *     which passes embedded escape sequences straight through, so the bold and
+ *     code spans survive to the terminal.
+ *   • STRIPPED — passed as the browser card's `question`, as the editable
+ *     `recommended` default, and as the text recorded in QaTranscript, whose
+ *     `forRecord()` is written into the task file's `grill Q&A` section. All
+ *     three are plain text, never ANSI.
+ */
+/**
+ * Minimal theme surface we need. pi's `Theme` satisfies it: it declares
+ * `bold(text)` and `fg(color, text)`, and `mdCode` is one of its `ThemeColor`
+ * values, so `ctx.ui.theme` is passed in directly.
  */
-/** Minimal theme surface we need; ExtensionCommandContext['ui'].theme satisfies it. */
 export interface InlineMarkdownTheme {
     bold(text: string): string;
     fg(color: 'mdCode', text: string): string;

package/dist/task/inline-markdown.js

@@ -1,11 +1,20 @@
 /**
- * Inline-markdown helpers for the clarify/grill question dialogs.
+ * Inline-markdown helpers for the question dialogs (grill, clarify, /task-plan).
  *
- * The model often wraps the core question in **bold** (and code in backticks)
- * because it makes the question easier to read at a glance. ctx.ui.input titles
- * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
- * displayed prompt, and STRIP them to plain text for the editable input default
- * and the persisted task file (which must stay ANSI-free).
+ * The question arrives carrying markdown because our own prompts ask for it:
+ * auto-prompts.ts and plan-prompts.ts both say "Put the core question in
+ * **bold** ... Backticks around code/identifiers are fine."
+ *
+ * One question then needs two forms, and question-dialog.ts `settleQuestion`
+ * builds both:
+ *   • RENDERED — passed as `localTitle`, which reaches `ctx.ui.input`. pi wraps
+ *     that title in `theme.fg("accent", ...)` and hands it to a pi-tui `Text`,
+ *     which passes embedded escape sequences straight through, so the bold and
+ *     code spans survive to the terminal.
+ *   • STRIPPED — passed as the browser card's `question`, as the editable
+ *     `recommended` default, and as the text recorded in QaTranscript, whose
+ *     `forRecord()` is written into the task file's `grill Q&A` section. All
+ *     three are plain text, never ANSI.
  */
 const BOLD_SPAN = /\*\*(.+?)\*\*/g;
 const CODE_SPAN = /`([^`]+)`/g;

package/dist/task/launch-config-gap.js

@@ -1,65 +1,51 @@
 /**
  * launch-config-gap — a launch script that cannot run because a variable the
  * project's own tracked template DECLARES is absent from this box is an
- * ENVIRONMENT GAP, not a code fault (mx5 run 20).
+ * ENVIRONMENT GAP, not a code fault.
  *
- * THE EPISODE. Attempt 3 of the final-gate autofix passed every guard, fixed the
- * failing test, and still lost the run:
- *
- *     autofix attempt 3 failed — did not converge: launch script: `bun run seed`
- *     exited 1 — $ bun run src/server/seed.ts  Missing required environment
- *     variable: ADMIN_PHONE  error: script "seed" exited with code 1
- *
- * Single-failure phrasing (final-gate.ts uses a numbered list for ≥2), so the
- * suite was green and this was the only remaining failure. The run failed on
- * exactly this, and it is self-inflicted at the last moment: pre-gate
- * `package.json` had no `seed` script at all, so `if (!present.has(name)) continue`
- * skipped it. Attempt 3 added the script to clear the launch-contract diff — and
- * thereby armed the check that killed the run.
- *
- * The loop was closed by construction. The gate runs every declared non-boot
- * script with `runnerEnv(runner)` = `process.env` plus a PATH prefix and nothing
- * else; "Missing required environment variable" matches neither ENV_GAP_OUTPUT_RE
- * nor INFRA_GAP_OUTPUT_RE, so it is a hard FAIL; and the only way to supply the
- * value is a gitignored `.env`, whose writes nexttask 4 correctly refuses to
- * credit. The static half of this already shipped and WORKED — `.env.example`
- * declares ADMIN_PHONE/ADMIN_PASSWORD, so `findMissingEnvDeclarations` was
- * correctly silent. This is the execution half.
+ * WHY THE GATE CANNOT SETTLE THIS ON ITS OWN. final-gate.ts runs every declared
+ * non-boot script (`runnableDeclaredScripts`, which filters on `BOOT_CLASS_RE`)
+ * as `bun run <name>`, with `runnerEnv(runner)` — `process.env` plus at most a
+ * PATH prefix, and nothing else. A project's own "missing environment variable"
+ * message matches neither `ENV_GAP_OUTPUT_RE` nor `INFRA_GAP_OUTPUT_RE`, so it
+ * lands as a hard FAIL. The only way to supply the value is a gitignored `.env`,
+ * and final-gate-fix.ts downgrades a converged PASS to UNOBSERVED when the gate
+ * stops passing with the ignored paths moved aside. Without this check the loop
+ * has no exit.
  *
  * FOUR STATIC CONDITIONS, ALL REQUIRED. Deliberately over-constrained: the
  * failure mode of getting this wrong is a gate that excuses real breakage.
  *
- *   1. the script's resolved body names a TRACKED SOURCE FILE
- *      (`bun run src/server/seed.ts` → `src/server/seed.ts`);
+ *   1. the script's resolved body names a TRACKED SOURCE FILE;
  *   2. that file REQUIRES an env var `X` under `scanSource` — i.e. none of its
- *      step-asides (default / compared / assigned / ambient / …) applies;
+ *      step-asides (`default`, `compared`, `assigned`, `ambient`,
+ *      `optional-api`, `probe`) applies;
  *   3. `X` is DECLARED in the tracked template. If it is NOT,
  *      `findMissingEnvDeclarations` has already failed the gate statically and
  *      this path must not fire — otherwise the two checks would cancel out and a
  *      project with no template at all would gain a blanket excuse;
  *   4. `X` is ABSENT from the env the gate spawned the child with.
  *
- * NOTHING IS PARSED FROM THE CHILD'S STDERR. `Missing required environment
- * variable: ADMIN_PHONE` is a string the PROJECT authored; matching on it would
- * be a rule about one project's phrasing, and every other project would phrase it
- * differently or not at all.
+ * NOTHING IS PARSED FROM THE CHILD'S STDERR. A "missing variable" message is a
+ * string the PROJECT authored; matching on it would be a rule about one project's
+ * phrasing, and the next project phrases it differently or not at all.
  *
  * THE FIFTH CONDITION IS DYNAMIC, AND IT IS WHAT MAKES THE RULE HONEST. The four
  * above cannot tell "exited BECAUSE the variable is absent" from "exited for its
  * own reasons, and also happens to read an absent variable". A script that throws
- * a TypeError on line 1 and also reads ADMIN_PHONE on line 3 satisfies all four.
+ * a TypeError on line 1 and also reads the variable on line 3 satisfies all four.
  * So the script is re-run once with the gap variables supplied as OBVIOUSLY
  * SYNTHETIC placeholders, and the exit code decides:
  *
- *     still non-zero → the absence did not cause it → FAIL, as today
- *     now zero       → the absence did cause it     → skip + UNOBSERVED + debt
+ *     still non-zero -> the absence did not cause it -> FAIL, unchanged
+ *     now zero       -> the absence did cause it     -> skip + UNOBSERVED + debt
  *
- * The probe run is a DIAGNOSTIC, never an observation. Its success is not
- * reported, and the verdict it produces is UNOBSERVED with debt — never a PASS
- * (memory/unobserved-gate-verdict-shipped.md). The placeholder is a fixed
- * harness-authored string; `.env.example`'s own values are never injected,
- * because they are placeholders too (`change-me`) and a green seed run against
- * them would be a fabricated observation.
+ * The probe run is a DIAGNOSTIC, never an observation. On a passing probe
+ * final-gate.ts calls `tally.unobserve()` and files the script as skipped, so the
+ * verdict is UNOBSERVED with debt and never a PASS. The placeholder is one fixed
+ * harness-authored string ({@link CONFIG_GAP_PROBE_VALUE}); the template's own
+ * values are never injected, because those are placeholders too and a green run
+ * against them would be a fabricated observation.
  */
 import { readFileSync } from 'node:fs';
 import * as path from 'node:path';

package/dist/task/launch-contract.d.ts

@@ -12,22 +12,20 @@ export declare function parseScriptLines(text: string): string[];
  */
 export declare function keepGroundedScripts(names: string[], sourceDoc: string): string[];
 /**
- * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * DETERMINISTIC RECALL: enumerate every backticked, script-name-shaped
  * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
  *
- * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
- * paragraph, so the grounding guard would have KEPT it — but the extraction child
- * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
- * emitted it. Grounding can only DROP a candidate, never add one, so recall was
- * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
- * enumerates candidates and hands them to the child as an explicit checklist; the
- * model's job flips from recall (weak) to per-candidate classification (strong).
+ * Grounding can only DROP a candidate, never add one, so without this the recall of a
+ * script declared far from the design's summary list is entirely the model's. This
+ * makes recall mechanical: the host enumerates the candidates and hands them to the
+ * child as an explicit checklist, so the model's job flips from recall (weak) to
+ * per-candidate classification (strong).
  *
  * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
  * don't match) is a grounded-context filter, not a tuned knob: a design declares a
- * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
- * of the checklist so a weak model isn't invited to keep junk the grounding guard
- * would then bless (every package name is backticked somewhere). A design with no
+ * script by calling it one. It keeps package-name paragraphs out of the checklist so
+ * a weak model isn't invited to keep junk the grounding guard would then bless —
+ * every package name is backticked somewhere. A design with no
  * such paragraph yields no candidates and the prompt is unchanged.
  */
 export declare function enumerateScriptCandidates(sourceDoc: string): string[];
@@ -38,13 +36,12 @@ export declare function readDeclaredScripts(cwd: string): Promise<string[]>;
 /** Append grounded script names, deduped against what is stored, keeping newest MAX. */
 export declare function appendDeclaredScripts(cwd: string, names: string[]): Promise<void>;
 /**
- * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
- * 11): everything the launch contract declares that is neither boot-class (the
- * boot check exercises those) nor already covered by the gate's integration
- * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
- * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
- * TypeError on first call) while the gate checked only that the scripts EXIST;
- * existence is not launchability.
+ * The declared scripts the final gate must EXECUTE as one-shot commands: everything
+ * the launch contract declares that is neither boot-class (the boot check exercises
+ * those) nor already covered by the gate's integration commands (`covered`,
+ * case-insensitive — the test/build-shaped scripts that ran). Checking only that a
+ * script is DECLARED says nothing about whether running it works; existence is not
+ * launchability.
  */
 export declare function runnableDeclaredScripts(declared: string[], covered: string[]): string[];
 /**
@@ -59,8 +56,8 @@ export declare function missingDeclaredScripts(declared: string[], manifestScrip
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
  *
  * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
- * model cannot MISS a declared script buried far from the design's summary list (the
- * run-11 `test:ct` hole); the model still classifies each candidate against the
- * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
+ * model cannot MISS a declared script buried far from the design's summary list; the
+ * model still classifies each candidate against the design, and the host grounding
+ * still applies. Empty ⇒ the prompt is unchanged.
  */
 export declare const LAUNCH_EXTRACT_PROMPT: (feature: string, candidates?: string[]) => string;