@mjasnikovs/pi-task 0.35.0 → 0.37.0

package/dist/remote/bridge.d.ts

@@ -57,6 +57,12 @@ export interface AskSpec {
      * {@link AskQuestionBoxSpec.manualLabel}). Ignored without `options`.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among `options` (see
+     * {@link AskQuestionBoxSpec.manualPosition}). Local picker only — remote
+     * browsers always render the text box above the action buttons.
+     */
+    manualPosition?: number;
     /**
      * Extra buttons the BROWSER card shows alongside the recommendation, each
      * answering with its own `value`. Unlike `options` — which are answers, and

package/dist/remote/bridge.js

@@ -101,6 +101,7 @@ export class SessionUI {
                     recommended: i === 0
                 })),
                 ...(spec.manualLabel !== undefined && { manualLabel: spec.manualLabel }),
+                ...(spec.manualPosition !== undefined && { manualPosition: spec.manualPosition }),
                 signal
             });
         }

package/dist/task/gate-deps.d.ts

@@ -38,6 +38,32 @@ export declare function collectChangedFiles(cwd: string, signal?: AbortSignal):
  * never a blocker. The `.pi-tasks/` bookkeeping is excluded from every git command.
  */
 export declare function collectAddedLines(cwd: string, signal?: AbortSignal): Promise<AddedLine[]>;
+/**
+ * Deterministic neutered-check-script pass (see script-escape.ts, mx5 run 13 PROMPT
+ * 4 item 4): check-class scripts that cannot report failure, in a manifest THIS
+ * task changed.
+ *
+ * Scoped to manifests the task touched, so the finding lands on the task that
+ * authored the script rather than being re-served to every later task. A script
+ * neutered by an earlier task is the whole-repo final gate's business, which
+ * re-checks the shipped manifest at run end regardless of who wrote it.
+ *
+ * Failures degrade to no findings — a sharpener, never a blocker.
+ */
+export declare function collectScriptEscapeFindings(cwd: string, signal?: AbortSignal): Promise<string[]>;
+/**
+ * Deterministic test-runner glob-collision pass (see runner-globs.ts, mx5 runs 7 AND
+ * 13, PROMPT 4 item 2): the manifest declares both `bun test` and `playwright test`
+ * without a provably disjoint file set, so `bun test` imports the playwright specs
+ * and dies during collection.
+ *
+ * Whole-repo rather than diff-scoped, unlike the neutered-script probe: a collision
+ * is a property of the PAIR of declarations, and the task that completes the pair is
+ * rarely the one that will be blamed by a diff. It is cheap (two small file reads)
+ * and silent unless both runners are actually declared. Failures degrade to no
+ * findings — a sharpener, never a blocker.
+ */
+export declare function collectRunnerGlobFindings(cwd: string): Promise<string[]>;
 /**
  * The working tree's current changes as a summary (write-guard shape): what a
  * write-capable gate child changed, given the tree was clean when it started.
@@ -87,6 +113,15 @@ export declare function gatePassesWithoutIgnored(cwd: string, paths: string[], r
  * a sharpener, never a blocker. Same fallback discipline as collectChangedFiles.
  */
 export declare function collectTaskTreeChanges(cwd: string, signal?: AbortSignal): Promise<TreeChangeSummary>;
+/**
+ * Deterministic test-assembly probe input (see test-assembly.ts, run-8 F4): read the
+ * task's own changed TEST files plus the repo's tracked source files, and return the
+ * finding lines naming any test that rebuilds a production assembly it never imports.
+ * Pure import-graph shape; failures degrade to no findings (the probe is a sharpener,
+ * never a blocker). `changed` is the already-collected task diff, reused so the probe
+ * costs one extra tracked-file listing, not a second diff.
+ */
+export declare function collectTestAssemblyFindings(cwd: string, changed: ChangedFile[], signal?: AbortSignal): Promise<string[]>;
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives

package/dist/task/gate-deps.js

@@ -24,7 +24,7 @@ import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
 import { recordAcceptDebt, recordEnforceKeptDebt, recordEnforceRevertDebt, recordFrozenBlockedDebt, recordCrossTaskDeletionDebt, recordYoloAcceptDebt, recordRootCauseDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
-import { runRepoHealthCheck } from './repo-health-check.js';
+import { runRepoHealthCheck, runRepoHealthCheckAsync } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels, discoverGateCommandBodies } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
 import { researchResolution } from './verify-resolution.js';
@@ -174,7 +174,7 @@ const MANIFEST_RE = /(^|\/)package\.json$/;
  *
  * Failures degrade to no findings — a sharpener, never a blocker.
  */
-async function collectScriptEscapeFindings(cwd, signal) {
+export async function collectScriptEscapeFindings(cwd, signal) {
     const changed = await collectChangedFiles(cwd, signal);
     const manifests = changed.map(f => f.path).filter(p => MANIFEST_RE.test(p));
     const findings = [];
@@ -217,7 +217,7 @@ async function readOrNull(cwd, rel) {
  * and silent unless both runners are actually declared. Failures degrade to no
  * findings — a sharpener, never a blocker.
  */
-async function collectRunnerGlobFindings(cwd) {
+export async function collectRunnerGlobFindings(cwd) {
     const manifestText = await readOrNull(cwd, 'package.json');
     if (manifestText === null)
         return [];
@@ -419,7 +419,7 @@ async function readRepoFile(cwd, rel) {
  * never a blocker). `changed` is the already-collected task diff, reused so the probe
  * costs one extra tracked-file listing, not a second diff.
  */
-async function collectTestAssemblyFindings(cwd, changed, signal) {
+export async function collectTestAssemblyFindings(cwd, changed, signal) {
     const changedTests = changed.filter(f => isTestFile(f.path));
     if (changedTests.length === 0)
         return [];
@@ -454,6 +454,11 @@ async function collectTestAssemblyFindings(cwd, changed, signal) {
  */
 export function buildGateDeps(params) {
     const { signal, parentContextWindow, runTask } = params;
+    // A/B seam (scripts/verify-deadair-ab.ts), same shape as CANCEL_AB_ARM in
+    // cancel-points.ts: reproduce the pre-fix gate — blocking sync repo health, no
+    // loader across the deterministic stage — so the dead air can be measured in the
+    // SAME binary rather than against a remembered baseline. Unset in every real run.
+    const deadAirBaseline = process.env.DEADAIR_AB_ARM === 'baseline';
     // Captured by each gate child's loader so the widget mirrors the child's latest
     // output line and context usage, exactly like the single-task phase widget.
     let lastLine;
@@ -475,7 +480,11 @@ export function buildGateDeps(params) {
     // disabled because re-running the same check is the job), with a status widget
     // and a per-gate debug log. Returns the closure runWorkVerification /
     // researchResolution expect as `runChild`.
-    const makeGateChild = (gateCtx, cwd2, taskTitle, kind, logFile) => async (tools, prompt, sig) => {
+    const makeGateChild = (gateCtx, cwd2, taskTitle, kind, logFile, 
+    /** `loader: false` when the CALLER already renders a loader that spans
+     *  this child (the verify gate does — see its dead-air note). Two
+     *  loaders on one widget key only fight each other. */
+    opts = {}) => async (tools, prompt, sig) => {
         lastLine = undefined;
         contextUsage = undefined;
         lastGuardReconcile = null;
@@ -493,16 +502,18 @@ export function buildGateDeps(params) {
         // Snapshot before, deterministically restore after; lint-fix is excluded
         // because editing is its job (it carries its own revert guard).
         const guardSnapshot = kind === 'verify' || kind === 'recommend' ? await captureGitState(cwd2, sig) : null;
-        const stopLoader = startAutoLoader(gateCtx, () => ({
-            title: taskTitle,
-            kind,
-            step: kind,
-            stepNum: 1,
-            stepTotal: 1,
-            startedAt,
-            lastLine,
-            contextUsage
-        }));
+        const stopLoader = opts.loader === false ?
+            () => { }
+            : startAutoLoader(gateCtx, () => ({
+                title: taskTitle,
+                kind,
+                step: kind,
+                stepNum: 1,
+                stepTotal: 1,
+                startedAt,
+                lastLine,
+                contextUsage
+            }));
         try {
             let r;
             try {
@@ -804,93 +815,145 @@ export function buildGateDeps(params) {
             catch {
                 spec = null;
             }
-            return runWorkVerification({
-                cwd: cwd2,
-                signal,
-                spec,
-                runChild: makeGateChild(verifyCtx, cwd2, taskTitle, 'verify', 'verify-debug.log'),
-                // Deterministic whole-repo static-analysis gate — runs the project's
-                // own lint/typecheck and fails on a real non-zero exit, independent of
-                // the model-authored VERIFY block (which may not lint at all).
-                repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
-                // Deterministic self-verification probe: test files the task itself
-                // authored/changed become prompt-level findings mandating the child
-                // to drive the real artifact before trusting their green result.
-                probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects),
-                // Deterministic test-assembly probe (F4): authored test files that
-                // rebuild production wiring — importing the leaf modules the shipped
-                // entry composes and assembling their own copy — become rule-3f
-                // findings so the child drives the REAL assembly, not the copy.
-                testAssemblyProbe: () => collectChangedFiles(cwd2, signal).then(changed => collectTestAssemblyFindings(cwd2, changed, signal)),
-                // Deterministic probe-gaming probe (F6): added lines whose stated
-                // purpose is to make a check pass rather than meet the requirement
-                // ("return 401 so the verification test passes") become rule-4c
-                // findings so the child verifies the real requirement, not the check.
-                probeGamingProbe: () => collectAddedLines(cwd2, signal).then(findProbeGaming),
-                // Deterministic cross-task deletion probe (mx5 run 12 PROMPT 2):
-                // tracked files this task's diff DELETES whose introducing commit
-                // belongs to a DIFFERENT task — a sibling's committed deliverable
-                // destroyed (typically to green a check). Injected under rule 4d and
-                // carried on a FAIL so an ACCEPT records durable debts.
-                crossTaskDeletionProbe: () => collectTaskTreeChanges(cwd2, signal).then(changes => findCrossTaskDeletions(changes, taskId, rel => taskThatIntroduced(cwd2, rel))),
-                // Deterministic sandbox-path-leak probe (mx5 run 13 PROMPT 4 item
-                // 1): absolute paths committed from the authoring child's own
-                // environment (`/workspace/src/shared`) that resolve nowhere here.
-                // Repaired deterministically where the relative form provably
-                // resolves; the remainder is injected under rule 4e, whose point is
-                // that such a path breaks the BUILD — so the checks that would have
-                // caught it report nothing rather than failing.
-                foreignPathProbe: () => collectForeignPathFindings(cwd2, signal, makeDebugAppender(path.join(tasksDir(cwd2), 'verify-debug.log'))),
-                // Deterministic neutered-check-script probe (mx5 run 13 PROMPT 4
-                // item 4): a check script this task authored that cannot fail
-                // (`… || true`, an inverted-grep launder). Injected under rule 4f,
-                // because the child provably cannot find this by running the
-                // script — it passes, which IS the defect.
-                scriptEscapeProbe: () => collectScriptEscapeFindings(cwd2, signal),
-                // Deterministic runner glob-collision probe (mx5 runs 7 AND 13,
-                // PROMPT 4 item 2): both `bun test` and `playwright test` declared
-                // with no proof their file sets are disjoint. Injected under rule
-                // 4g — the collision kills the suite during COLLECTION, which does
-                // not look like a test failure.
-                runnerGlobProbe: () => collectRunnerGlobFindings(cwd2),
-                // Deterministic prohibition probe: paths the spec forbids modifying
-                // that the task's diff modified anyway become prompt-level findings
-                // under the no-waiver rule — the child otherwise rarely runs `git
-                // diff` and cannot even see the violation.
-                prohibitionProbe: () => {
-                    const banned = spec ? extractProhibitions(spec) : [];
-                    if (banned.length === 0)
-                        return Promise.resolve([]);
-                    return collectChangedFiles(cwd2, signal).then(files => findProhibitionViolations(banned, files));
-                },
-                // Git-state guard result of the most recent child run: a verdict
-                // computed on a tree the child itself mutated is discarded — but ONLY
-                // when the mutation touched graded state (verdictTainted). A child
-                // that merely left test-runner output behind (test-results/,
-                // playwright-report/ …) judged an equivalent tree; its verdict stands
-                // and the artifacts were still cleaned (mx5 run 9 lost 7 verdicts this
-                // way — see git-state-guard.ts).
-                mutationCheck: () => lastGuardReconcile?.verdictTainted ?
-                    { mutated: true, detail: lastGuardReconcile.actions.join('; ') }
-                    : { mutated: false, detail: '' },
-                // Per-run environment-facts cache under .pi-tasks/ (survives
-                // discardEdits): earlier children's discoveries save this child
-                // the re-archaeology; its own ENV-NOTE lines are stored for the
-                // next one, stamped with this task's id as their origin so a
-                // later child sees a cited fact is second-hand and must
-                // re-validate before excusing a failure (F7). Facts only —
-                // verdict rules unaffected.
-                envNotes: {
-                    read: () => readEnvNotes(cwd2),
-                    append: notes => appendEnvNotes(cwd2, notes, taskId)
-                },
-                // Per-run cross-slice contract registry under .pi-tasks/ (F3): the
-                // verbatim interface facts the design pins that multiple slices
-                // share, so the verify child checks this slice's boundary against
-                // them. Empty on single-`/task` runs or a design with no shared
-                // boundary → no block.
-                contracts: () => readContracts(cwd2)
-            });
+            // DEAD AIR (the reason this loader exists). The gate's DETERMINISTIC
+            // stage — repo health plus ten probes — runs before the verify child,
+            // and the child's own loader only starts once the child does. The impl
+            // widget was cleared at `agent_end`, so until now the screen simply
+            // stopped: no spinner, no clock, no line (the `verifying…` notify cannot
+            // even paint, since pi-tui schedules renders on process.nextTick and the
+            // health check used to block the loop outright). MEASURED on real repos:
+            // 15s (mx5) to 69s (aiz-client) per health run, 0 of 686 expected 100ms
+            // timer ticks delivered. One loader now spans the WHOLE gate — the
+            // deterministic stage and the child — so the run is never silent.
+            const gateStartedAt = Date.now();
+            let stageLine;
+            // Clear the PREVIOUS child's trailer before the loader goes up: the
+            // deterministic stage has no child of its own, so a stale `↳` line from
+            // the last task's enforce pass would otherwise sit under the new
+            // status block as if it were live.
+            lastLine = undefined;
+            contextUsage = undefined;
+            const stopGateLoader = deadAirBaseline ?
+                () => { }
+                : startAutoLoader(verifyCtx, () => ({
+                    title: taskTitle,
+                    kind: 'verify',
+                    step: 'verify',
+                    stepNum: 1,
+                    stepTotal: 1,
+                    startedAt: gateStartedAt,
+                    lastLine: lastLine ?? stageLine,
+                    contextUsage
+                }));
+            try {
+                return await runWorkVerification({
+                    cwd: cwd2,
+                    signal,
+                    spec,
+                    // The child renders no loader of its own: the gate-wide one above is
+                    // already live and reads the same `lastLine`/`contextUsage` the child
+                    // feeds, so a second widget on the same key would only fight it.
+                    runChild: makeGateChild(verifyCtx, cwd2, taskTitle, 'verify', 'verify-debug.log', {
+                        loader: deadAirBaseline
+                    }),
+                    // Names the deterministic step in the live status line.
+                    onStage: label => {
+                        stageLine = label;
+                    },
+                    // Deterministic whole-repo static-analysis gate — runs the project's
+                    // own lint/typecheck and fails on a real non-zero exit, independent of
+                    // the model-authored VERIFY block (which may not lint at all). ASYNC:
+                    // the sync runner froze the event loop for the whole lint (see above).
+                    repoHealth: () => deadAirBaseline ?
+                        Promise.resolve(runRepoHealthCheck(cwd2))
+                        : runRepoHealthCheckAsync(cwd2, {
+                            signal,
+                            onCommand: c => {
+                                stageLine = `repo health · ${c}`;
+                            }
+                        }),
+                    // Deterministic self-verification probe: test files the task itself
+                    // authored/changed become prompt-level findings mandating the child
+                    // to drive the real artifact before trusting their green result.
+                    probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects),
+                    // Deterministic test-assembly probe (F4): authored test files that
+                    // rebuild production wiring — importing the leaf modules the shipped
+                    // entry composes and assembling their own copy — become rule-3f
+                    // findings so the child drives the REAL assembly, not the copy.
+                    testAssemblyProbe: () => collectChangedFiles(cwd2, signal).then(changed => collectTestAssemblyFindings(cwd2, changed, signal)),
+                    // Deterministic probe-gaming probe (F6): added lines whose stated
+                    // purpose is to make a check pass rather than meet the requirement
+                    // ("return 401 so the verification test passes") become rule-4c
+                    // findings so the child verifies the real requirement, not the check.
+                    probeGamingProbe: () => collectAddedLines(cwd2, signal).then(findProbeGaming),
+                    // Deterministic cross-task deletion probe (mx5 run 12 PROMPT 2):
+                    // tracked files this task's diff DELETES whose introducing commit
+                    // belongs to a DIFFERENT task — a sibling's committed deliverable
+                    // destroyed (typically to green a check). Injected under rule 4d and
+                    // carried on a FAIL so an ACCEPT records durable debts.
+                    crossTaskDeletionProbe: () => collectTaskTreeChanges(cwd2, signal).then(changes => findCrossTaskDeletions(changes, taskId, rel => taskThatIntroduced(cwd2, rel))),
+                    // Deterministic sandbox-path-leak probe (mx5 run 13 PROMPT 4 item
+                    // 1): absolute paths committed from the authoring child's own
+                    // environment (`/workspace/src/shared`) that resolve nowhere here.
+                    // Repaired deterministically where the relative form provably
+                    // resolves; the remainder is injected under rule 4e, whose point is
+                    // that such a path breaks the BUILD — so the checks that would have
+                    // caught it report nothing rather than failing.
+                    foreignPathProbe: () => collectForeignPathFindings(cwd2, signal, makeDebugAppender(path.join(tasksDir(cwd2), 'verify-debug.log'))),
+                    // Deterministic neutered-check-script probe (mx5 run 13 PROMPT 4
+                    // item 4): a check script this task authored that cannot fail
+                    // (`… || true`, an inverted-grep launder). Injected under rule 4f,
+                    // because the child provably cannot find this by running the
+                    // script — it passes, which IS the defect.
+                    scriptEscapeProbe: () => collectScriptEscapeFindings(cwd2, signal),
+                    // Deterministic runner glob-collision probe (mx5 runs 7 AND 13,
+                    // PROMPT 4 item 2): both `bun test` and `playwright test` declared
+                    // with no proof their file sets are disjoint. Injected under rule
+                    // 4g — the collision kills the suite during COLLECTION, which does
+                    // not look like a test failure.
+                    runnerGlobProbe: () => collectRunnerGlobFindings(cwd2),
+                    // Deterministic prohibition probe: paths the spec forbids modifying
+                    // that the task's diff modified anyway become prompt-level findings
+                    // under the no-waiver rule — the child otherwise rarely runs `git
+                    // diff` and cannot even see the violation.
+                    prohibitionProbe: () => {
+                        const banned = spec ? extractProhibitions(spec) : [];
+                        if (banned.length === 0)
+                            return Promise.resolve([]);
+                        return collectChangedFiles(cwd2, signal).then(files => findProhibitionViolations(banned, files));
+                    },
+                    // Git-state guard result of the most recent child run: a verdict
+                    // computed on a tree the child itself mutated is discarded — but ONLY
+                    // when the mutation touched graded state (verdictTainted). A child
+                    // that merely left test-runner output behind (test-results/,
+                    // playwright-report/ …) judged an equivalent tree; its verdict stands
+                    // and the artifacts were still cleaned (mx5 run 9 lost 7 verdicts this
+                    // way — see git-state-guard.ts).
+                    mutationCheck: () => lastGuardReconcile?.verdictTainted ?
+                        { mutated: true, detail: lastGuardReconcile.actions.join('; ') }
+                        : { mutated: false, detail: '' },
+                    // Per-run environment-facts cache under .pi-tasks/ (survives
+                    // discardEdits): earlier children's discoveries save this child
+                    // the re-archaeology; its own ENV-NOTE lines are stored for the
+                    // next one, stamped with this task's id as their origin so a
+                    // later child sees a cited fact is second-hand and must
+                    // re-validate before excusing a failure (F7). Facts only —
+                    // verdict rules unaffected.
+                    envNotes: {
+                        read: () => readEnvNotes(cwd2),
+                        append: notes => appendEnvNotes(cwd2, notes, taskId)
+                    },
+                    // Per-run cross-slice contract registry under .pi-tasks/ (F3): the
+                    // verbatim interface facts the design pins that multiple slices
+                    // share, so the verify child checks this slice's boundary against
+                    // them. Empty on single-`/task` runs or a design with no shared
+                    // boundary → no block.
+                    contracts: () => readContracts(cwd2)
+                });
+            }
+            finally {
+                stopGateLoader();
+            }
         },
         lintFix: async (fixCtx, cwd2, taskTitle, taskId, failReason) => {
             // Same frozen extraction the enforce guard and the verify rule-4b
@@ -911,7 +974,7 @@ export function buildGateDeps(params) {
                 signal,
                 failReason,
                 runChild: makeGateChild(fixCtx, cwd2, taskTitle, 'lint-fix', 'verify-debug.log'),
-                repoHealth: () => Promise.resolve(runRepoHealthCheck(cwd2)),
+                repoHealth: () => runRepoHealthCheckAsync(cwd2, { signal }),
                 git: async (args) => {
                     const r = await git(cwd2, args, signal);
                     return { exitCode: r.exitCode, stdout: r.stdout };
@@ -927,7 +990,29 @@ export function buildGateDeps(params) {
             });
         },
         // Deterministic static check + tree helpers for the enforce pre-commit gate.
-        repoHealth: cwd2 => Promise.resolve(runRepoHealthCheck(cwd2)),
+        // Runs TWICE per task there (a baseline before the edit pass, a differential
+        // check after it), each one as long as the project's own lint — so it gets
+        // the same treatment as the verify-side run: async, and under a live loader
+        // naming the command, instead of a frozen screen.
+        repoHealth: (healthCtx, cwd2, label) => {
+            const startedAt = Date.now();
+            let running;
+            const stop = startAutoLoader(healthCtx, () => ({
+                title: label,
+                kind: 'enforce',
+                step: 'repo health',
+                stepNum: 1,
+                stepTotal: 1,
+                startedAt,
+                lastLine: running ? `repo health · ${running}` : 'repo health'
+            }));
+            return runRepoHealthCheckAsync(cwd2, {
+                signal,
+                onCommand: c => {
+                    running = c;
+                }
+            }).finally(stop);
+        },
         dirty: async (cwd2) => {
             const r = await git(cwd2, ['status', '--porcelain', '--', '.', EXCLUDE_TASKS_DIR], signal);
             return r.exitCode === 0 && r.stdout.trim().length > 0;

package/dist/task/plan-io.d.ts

@@ -43,13 +43,31 @@ export declare function buildPlanBody(task: string): string;
  * there is no hidden channel.
  */
 export declare function formatPlanDecisions(entries: readonly PlanEntry[]): string;
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export declare const HANDOFF_DELIVERABLE_RULE: string;
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export declare function buildHandoffPrompt(task: string, entries: readonly PlanEntry[]): string;

package/dist/task/plan-io.js

@@ -73,20 +73,43 @@ export function buildPlanBody(task) {
 export function formatPlanDecisions(entries) {
     return entries.length === 0 ? '(none yet)' : formatPlanTranscript(entries);
 }
+/**
+ * The line that pins the DELIVERABLE, and it is not optional.
+ *
+ * The task prompt leads the handoff verbatim, and users reach /task-plan by
+ * phrasing the request as planning — live (aiz-client TASK_PLAN_0001,
+ * 2026-08-05): "Lets plan new tab and report @src/app/reports/". /task's refine
+ * read the verb as the deliverable and produced a task titled "Plan the addition
+ * of a new sub-tab…", whose ACCEPTANCE was "a planning document exists with
+ * placeholder sections" and whose VERIFY asserted that no `.ts`/`.tsx` file had
+ * changed. It passed. Nothing was built.
+ *
+ * Planning already happened — this prompt IS its output — so the handoff says so
+ * rather than letting the request's own wording re-open it. It rides on every
+ * handoff, decisions or none: the verb leaks regardless of how much got settled.
+ */
+export const HANDOFF_DELIVERABLE_RULE = 'PLANNING IS ALREADY DONE. This prompt is the OUTPUT of an interactive planning session '
+    + 'that has now ended; you are the implementation step. Build the thing. Do not produce a '
+    + 'plan, a design, a proposal, or a "planning-only" deliverable, do not write a document '
+    + 'whose acceptance is that no code changed, and do not defer the work pending user '
+    + 'confirmation — no user is available from here on.';
 /**
  * The prompt handed to /task when the user proceeds to execution.
  *
  * The task prompt leads, exactly as a bare `/task <prompt>` would, so refine sees
- * a normal task description first; the decisions follow as an authoritative block.
- * Anything the user did NOT settle is simply absent — /task's own grill phase asks
- * about what is left, which is why this block never invents a decision to fill a
- * gap.
+ * a normal task description first; the deliverable rule and then the decisions
+ * follow as an authoritative block. Anything the user did NOT settle is simply
+ * absent — /task's own grill phase asks about what is left, which is why this
+ * block never invents a decision to fill a gap. A question the user left
+ * unanswered is likewise absent: "(skipped)" is not a decision, and carrying it
+ * as one is how a non-answer becomes an instruction.
  */
 export function buildHandoffPrompt(task, entries) {
-    const decisions = entries.filter(e => e.kind !== 'note');
+    const decisions = entries.filter(e => e.kind !== 'note' && !(e.kind === 'decision' && /^\(skipped/i.test(e.answer.trim())));
+    const head = `${task.trim()}\n\n${HANDOFF_DELIVERABLE_RULE}`;
     if (decisions.length === 0)
-        return task.trim();
-    return (`${task.trim()}\n\n`
+        return head;
+    return (`${head}\n\n`
         + `PLANNING DECISIONS — these were settled with the user before this task was started. `
         + `They are authoritative: implement them as written, and do not re-open or contradict `
         + `them. They may not cover everything; decide anything they leave open as usual.\n\n`

package/dist/task/plan-prompts.js

@@ -67,6 +67,14 @@ repo, and any stated constraints; it is shown to the user as a recommendation th
 accept or override. When the question is a genuine binary "A or B?" fork, also give
 the single best alternative as an ALT line; otherwise emit only the one SUGGESTED.
 
+The SUGGESTED must DECIDE. Never recommend asking, clarifying, confirming, or
+checking with the user, and never recommend waiting, deferring, or leaving the
+question open — the user is answering this very question right now, so "find out
+from the user" is not an answer, it is the question you just asked. If you truly
+cannot tell which way to go, still commit to the option you would take if it were
+your call, and let the user override it. A default that could not be implemented
+as written is not a default.
+
 OUTPUT FORMAT (exact) — read as much as you like, but your written REPLY is 2 or
 3 lines and nothing else:
 - Do NOT report what you read. No preamble, no analysis, no findings, no numbered

package/dist/task/plan-session.d.ts

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -85,6 +88,32 @@ export declare function pickQuestion<T extends {
  * Deliberately shallow — an "X or Y?" in the question's own clause.
  */
 export declare function looksLikeFork(question: string): boolean;
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export declare function isDeferralSuggestion(suggested: string): boolean;
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export declare function planDecisiveHint(question: string, suggested: string): string;
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -109,6 +138,7 @@ export type PlanAskSpec = AskSpec & {
         value: string;
     }[];
     manualLabel: string;
+    manualPosition: number;
     actions: {
         label: string;
         value: string;
@@ -155,9 +185,10 @@ interface PendingQuestion {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
 /**
@@ -165,6 +196,8 @@ export declare function buildQuestionSpec(p: PendingQuestion): PlanAskSpec;
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export declare function buildIdleSpec(): PlanAskSpec;
 /**

package/dist/task/plan-session.js

@@ -20,7 +20,10 @@
  *                                    doubles as "state a decision" when the model
  *                                    has nothing to ask
  *   ▶ proceed to execution        — stop planning, hand the decisions to /task
- *                                    (PLAN_PROCEED)
+ *                                    (PLAN_PROCEED). Always the LAST card in the
+ *                                    box — it ends the session, so it sits under
+ *                                    every move that continues it, including the
+ *                                    free-text card (see `manualPosition`).
  *
  * The loop is pure with respect to I/O: every side effect (child calls, dialogs,
  * persistence) arrives through {@link PlanSessionDeps}, so the whole interaction
@@ -98,6 +101,51 @@ export function pickQuestion(parsed) {
 export function looksLikeFork(question) {
     return /\bor\b/i.test(question.split('?')[0] ?? '');
 }
+/**
+ * Does the recommended default DEFER the decision instead of making one?
+ *
+ * The prompt asks for a "concrete, decisive default", and nothing enforced it.
+ * Live (aiz-client TASK_PLAN_0001, 2026-08-05): the model asked "what specific
+ * report should this new tab display?" and recommended
+ * "clarify with the user what the report is meant to show before proceeding".
+ * The user pressed enter, so it was recorded `(accepted recommendation)` and rode
+ * into /task's handoff as an AUTHORITATIVE decision — an order not to proceed,
+ * addressed to a run where no user exists. /task duly built a task whose
+ * ACCEPTANCE was "a planning document with placeholder sections" and whose VERIFY
+ * asserted that no source file had changed.
+ *
+ * A deferral is not an answer, and the one place it can never be one is here: the
+ * user IS present during planning, so "ask the user" is a null move — that IS the
+ * question. Detection is anchored to the START of the default, which keeps it off
+ * legitimate product behaviour ("prompt the user to confirm deletion" decides
+ * something; "ask the user which report" decides nothing).
+ */
+export function isDeferralSuggestion(suggested) {
+    const s = suggested.trim().replace(/^["'`*_\s]+/, '');
+    return (/^(ask|clarify|confirm|check|discuss|decide)\b[^.]{0,60}\b(with |from |the )?user\b/i.test(s)
+        || /^(wait|hold off|hold|defer|postpone|pause|park)\b/i.test(s)
+        || /^(tbd|to be (determined|decided|defined|specified))\b/i.test(s)
+        || /^(pending|awaiting|await)\b/i.test(s)
+        || /^leave (it|this|that)?\s*(to|for|open|undecided|unspecified)\b/i.test(s)
+        || /^the user (must|should|needs? to|has to|will)\b/i.test(s)
+        || /^(do not|don'?t|no)\b[^.]{0,40}\b(proceed|implement|build|start|write|decide)\b/i.test(s));
+}
+/**
+ * Corrective re-prompt for a default that deferred the decision. Same one-shot
+ * budget and same quote-it-back shape as {@link planForkHint}, because the child
+ * is stateless and cannot otherwise know what it just recommended.
+ */
+export function planDecisiveHint(question, suggested) {
+    return ('[SYSTEM NOTE: Your previous reply asked this question:\n'
+        + `"${question}"\n`
+        + `and recommended: "${suggested}"\n`
+        + 'That recommendation DEFERS the decision instead of making one — it tells the user to '
+        + 'ask, clarify, wait, or leave it open. The user is answering this question RIGHT NOW, so '
+        + '"find out from the user" is not an answer, it is the question you just asked. Ask the '
+        + 'SAME question again — do not change the subject — and this time make SUGGESTED a '
+        + 'concrete choice that could be implemented as written, naming real things from the repo. '
+        + 'If the question is a genuine A-or-B fork, add the ALT line too. Nothing else.]');
+}
 /**
  * Corrective re-prompt for a fork-shaped question that shipped only ONE option.
  *
@@ -124,9 +172,10 @@ export function planForkHint(question) {
 /**
  * Build the picker for a pending model question: the recommendation first (index
  * 0 is the green RECOMMENDED card), the alternative second when the question is a
- * binary fork, then the two control actions. The free-text card is appended by
+ * binary fork, then the two control actions. The free-text card is supplied by
  * askQuestionBox itself — that is the "answer in your own words" affordance, and
- * it is the same card grill and clarify already show.
+ * it is the same card grill and clarify already show — placed just above the
+ * trailing "proceed to execution" card so proceed stays last.
  */
 export function buildQuestionSpec(p) {
     const options = [];
@@ -153,7 +202,10 @@ export function buildQuestionSpec(p) {
         allowSkip: false,
         options: [...options, ...actions],
         actions,
-        manualLabel: PLAN_ANSWER_LABEL
+        manualLabel: PLAN_ANSWER_LABEL,
+        // The free-text card goes ABOVE "proceed to execution" — proceed ends the
+        // session, so it is the last card in the box, under every other move.
+        manualPosition: options.length + actions.length - 1
     };
 }
 /**
@@ -161,11 +213,13 @@ export function buildQuestionSpec(p) {
  * questions, or the cap/duplicate backstop stopped it. The same three moves are
  * still on offer; only "answer this question" is gone, because there is no
  * question, so the free-text card becomes "add a decision of your own".
+ * Proceed stays last here, as it is under a question: handing off to /task ends
+ * planning, so it never sits where a reflexive first-item press can hit it.
  */
 export function buildIdleSpec() {
     const actions = [
-        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED },
-        { label: PLAN_ASK_LABEL, value: PLAN_ASK }
+        { label: PLAN_ASK_LABEL, value: PLAN_ASK },
+        { label: PLAN_PROCEED_LABEL, value: PLAN_PROCEED }
     ];
     return {
         localTitle: PLAN_NO_QUESTIONS,
@@ -177,7 +231,8 @@ export function buildIdleSpec() {
         allowSkip: false,
         options: actions,
         actions,
-        manualLabel: PLAN_STATE_LABEL
+        manualLabel: PLAN_STATE_LABEL,
+        manualPosition: actions.length - 1
     };
 }
 /**
@@ -278,11 +333,31 @@ export async function runPlanSession(deps) {
                 formatHint = PLAN_FORMAT_HINT;
                 continue;
             }
+            // A default that defers decides nothing, and an accepted deferral
+            // reaches /task dressed as an authoritative decision. One re-prompt to
+            // make it decisive; if it comes back deferring anyway the option is
+            // DROPPED rather than shown, so an empty submit records "(skipped)" —
+            // an unanswered question — instead of a decision the user never made.
+            const defers = suggested !== undefined && isDeferralSuggestion(suggested);
+            if (defers && formatHint === null) {
+                deps.logDebug?.('plan: SUGGESTED deferred the decision — one re-prompt');
+                formatHint = planDecisiveHint(plain, suggested);
+                continue;
+            }
+            // When only the recommendation defers, the ALT is still a real
+            // commitment: promote it so the question keeps a usable default.
+            const usableSuggested = defers ? alt : suggested;
+            const usableAlt = defers ? undefined : alt;
+            if (defers) {
+                deps.logDebug?.(usableSuggested === undefined ?
+                    'plan: SUGGESTED still deferred — question shown with no recommendation'
+                    : 'plan: SUGGESTED still deferred — promoted the ALT to the recommendation');
+            }
             // A question that offers a choice but ships one option leaves the
             // user typing out the alternative the model just named. Same one-shot
             // budget, quoting the question back so the (stateless) child re-asks
             // this one instead of a new one.
-            if (alt === undefined && formatHint === null && looksLikeFork(plain)) {
+            if (usableAlt === undefined && formatHint === null && !defers && looksLikeFork(plain)) {
                 deps.logDebug?.('plan: fork-shaped question with no ALT — one re-prompt');
                 formatHint = planForkHint(plain);
                 continue;
@@ -294,13 +369,13 @@ export async function runPlanSession(deps) {
             pending = {
                 plain,
                 shown: render(question),
-                ...(suggested !== undefined && {
-                    suggested: stripInlineMarkdown(suggested),
-                    shownSuggested: render(suggested)
+                ...(usableSuggested !== undefined && {
+                    suggested: stripInlineMarkdown(usableSuggested),
+                    shownSuggested: render(usableSuggested)
                 }),
-                ...(alt !== undefined && {
-                    alt: stripInlineMarkdown(alt),
-                    shownAlt: render(alt)
+                ...(usableAlt !== undefined && {
+                    alt: stripInlineMarkdown(usableAlt),
+                    shownAlt: render(usableAlt)
                 })
             };
         }

package/dist/task/question-box.d.ts

@@ -84,6 +84,14 @@ export interface AskQuestionBoxSpec {
      * what the card actually does.
      */
     manualLabel?: string;
+    /**
+     * Where the free-text card sits among the options. Defaults to the end, which
+     * is right when the picker is answering a question. /task-plan passes an
+     * earlier index so its "proceed to execution" card — the one that ENDS the
+     * session — is literally the last entry in the list, and never sits above a
+     * card the user is more likely to want.
+     */
+    manualPosition?: number;
 }
 /**
  * Show the boxed picker and resolve to the chosen option's `value`, the text the

package/dist/task/question-box.js

@@ -143,12 +143,14 @@ export class QuestionBoxComponent {
  */
 export async function askQuestionBox(ctx, spec) {
     const { question, options, inputTitle, signal } = spec;
+    const manualIndex = Math.max(0, Math.min(options.length, spec.manualPosition ?? options.length));
+    const asCard = (o) => ({ label: o.label, recommended: o.recommended });
     const cards = [
-        ...options.map(o => ({ label: o.label, recommended: o.recommended })),
-        { label: spec.manualLabel ?? MANUAL_CARD_LABEL }
+        ...options.slice(0, manualIndex).map(asCard),
+        { label: spec.manualLabel ?? MANUAL_CARD_LABEL },
+        ...options.slice(manualIndex).map(asCard)
     ];
     const colors = boxColors(ctx.ui.theme);
-    const manualIndex = options.length;
     const choice = await ctx.ui.custom((_tui, _theme, _kb, done) => {
         if (signal.aborted) {
             done(undefined);
@@ -167,5 +169,5 @@ export async function askQuestionBox(ctx, spec) {
     if (choice === manualIndex) {
         return ctx.ui.input(inputTitle, undefined, { signal });
     }
-    return options[choice]?.value;
+    return options[choice < manualIndex ? choice : choice - 1]?.value;
 }

package/dist/task/repo-health-check.d.ts

@@ -40,5 +40,27 @@ export declare function discoverHealthCommands(cwd: string): {
  *
  * A generous per-command timeout guards against a wedged tool; a timeout is treated
  * as an inconclusive skip, not a fault (it is an environment problem, not the code's).
+ *
+ * SYNCHRONOUS — it blocks the event loop for as long as the project's own lint takes
+ * (MEASURED: 15s on mx5, 69s on aiz-client), so nothing can render or animate while
+ * it runs. Gate callers must use {@link runRepoHealthCheckAsync} instead; this stays
+ * for callers that genuinely have no async seam.
  */
 export declare function runRepoHealthCheck(cwd: string, timeoutMs?: number): HealthOutcome;
+/** Progress hook: called with each command's label as it STARTS, so a caller can
+ *  keep a live status line naming what is currently running. */
+export type HealthProgress = (command: string) => void;
+/**
+ * Same check, same verdicts, without blocking the event loop.
+ *
+ * The gate runs this immediately after the implementation turn ends, when the impl
+ * widget has just been cleared — the sync version froze the whole TUI there for the
+ * duration of the project's lint (MEASURED: 0 of 686 expected 100ms timer ticks
+ * fired during a 69s aiz-client run), so no spinner, clock or queued notify could
+ * paint. `onCommand` lets the caller name the running command in a live status line.
+ */
+export declare function runRepoHealthCheckAsync(cwd: string, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onCommand?: HealthProgress;
+}): Promise<HealthOutcome>;

package/dist/task/repo-health-check.js

@@ -29,7 +29,7 @@
  * environment gap, not a code fault, so that command is SKIPPED — only a command that
  * actually ran and returned non-zero fails the check.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
@@ -106,6 +106,38 @@ export function discoverHealthCommands(cwd) {
     }
     return { ecosystem: null, cmds: [] };
 }
+/**
+ * Verdict for ONE finished command: 'skip' (environment gap — cannot conclude),
+ * 'pass', or the FAIL outcome. Shared by the sync and async runners so their
+ * semantics cannot drift apart — the async runner exists only to stop blocking the
+ * event loop, and a behaviour difference between the two would be a silent gate
+ * change rather than a UI fix.
+ */
+function classifyHealthRun(bin, args, ecosystem, r) {
+    // Tool missing (ENOENT) or killed by timeout → cannot conclude; skip it.
+    if (r.failedToStart || r.status === null)
+        return 'skip';
+    // "Command not found" INSIDE the script chain (e.g. `bun run lint` before
+    // node_modules exists — seen live failing TASK_0001's first verify). Same
+    // environment gap as ENOENT, just surfaced through the runner's shell —
+    // as exit 127 where a posix shell ran it, else by the runner's own wording
+    // (Windows bun reports the miss itself and exits 1).
+    if (isCommandNotFound(r.status, `${r.stdout ?? ''}\n${r.stderr ?? ''}`))
+        return 'skip';
+    if (r.status !== 0) {
+        return {
+            ok: false,
+            reason: `\`${bin} ${args.join(' ')}\` exited ${r.status}`,
+            ecosystem,
+            output: captureHealthOutput(r.stdout, r.stderr)
+        };
+    }
+    return 'pass';
+}
+/** The nothing-to-run outcome, shared by both runners. */
+function noCommandOutcome(ecosystem) {
+    return { ok: true, reason: 'no repo-wide static-analysis command found', ecosystem, output: '' };
+}
 /**
  * Run the discovered static checks whole-repo and let the real exit codes decide.
  * Deterministic and synchronous under the hood (a wrapper keeps the caller async).
@@ -117,17 +149,16 @@ export function discoverHealthCommands(cwd) {
  *
  * A generous per-command timeout guards against a wedged tool; a timeout is treated
  * as an inconclusive skip, not a fault (it is an environment problem, not the code's).
+ *
+ * SYNCHRONOUS — it blocks the event loop for as long as the project's own lint takes
+ * (MEASURED: 15s on mx5, 69s on aiz-client), so nothing can render or animate while
+ * it runs. Gate callers must use {@link runRepoHealthCheckAsync} instead; this stays
+ * for callers that genuinely have no async seam.
  */
 export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
     const { ecosystem, cmds } = discoverHealthCommands(cwd);
-    if (!ecosystem || cmds.length === 0) {
-        return {
-            ok: true,
-            reason: 'no repo-wide static-analysis command found',
-            ecosystem,
-            output: ''
-        };
-    }
+    if (!ecosystem || cmds.length === 0)
+        return noCommandOutcome(ecosystem);
     for (const [bin, args] of cmds) {
         // Runner resolution (mx5 run 16): a PATH-stripped environment must not
         // silently skip the statics when the runner sits at a known install
@@ -139,24 +170,77 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
             timeout: timeoutMs,
             env: runnerEnv(runner)
         });
-        // Tool missing (ENOENT) or killed by timeout → cannot conclude; skip it.
-        if (r.error || r.status === null)
+        const verdict = classifyHealthRun(bin, args, ecosystem, {
+            failedToStart: r.error !== undefined,
+            status: r.status,
+            stdout: r.stdout ?? '',
+            stderr: r.stderr ?? ''
+        });
+        if (verdict === 'skip' || verdict === 'pass')
             continue;
-        // "Command not found" INSIDE the script chain (e.g. `bun run lint` before
-        // node_modules exists — seen live failing TASK_0001's first verify). Same
-        // environment gap as ENOENT, just surfaced through the runner's shell —
-        // as exit 127 where a posix shell ran it, else by the runner's own wording
-        // (Windows bun reports the miss itself and exits 1).
-        if (isCommandNotFound(r.status, `${r.stdout ?? ''}\n${r.stderr ?? ''}`))
+        return verdict;
+    }
+    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem, output: '' };
+}
+/** Spawn one health command without blocking the event loop. Mirrors spawnSync's
+ *  result shape (status null when killed, failedToStart on ENOENT). */
+function spawnHealthCommand(bin, args, cwd, timeoutMs, signal) {
+    return new Promise(resolve => {
+        const runner = resolveRunner(bin);
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const child = spawn(runner.bin, args, { cwd, env: runnerEnv(runner) });
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(r);
+        };
+        const kill = () => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        };
+        const timer = setTimeout(kill, timeoutMs);
+        timer.unref?.();
+        const onAbort = () => kill();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        child.on('error', () => done({ failedToStart: true, status: null, stdout, stderr }));
+        child.on('close', (code) => done({ failedToStart: false, status: code, stdout, stderr }));
+    });
+}
+/**
+ * Same check, same verdicts, without blocking the event loop.
+ *
+ * The gate runs this immediately after the implementation turn ends, when the impl
+ * widget has just been cleared — the sync version froze the whole TUI there for the
+ * duration of the project's lint (MEASURED: 0 of 686 expected 100ms timer ticks
+ * fired during a 69s aiz-client run), so no spinner, clock or queued notify could
+ * paint. `onCommand` lets the caller name the running command in a live status line.
+ */
+export async function runRepoHealthCheckAsync(cwd, opts = {}) {
+    const { ecosystem, cmds } = discoverHealthCommands(cwd);
+    if (!ecosystem || cmds.length === 0)
+        return noCommandOutcome(ecosystem);
+    for (const [bin, args] of cmds) {
+        opts.onCommand?.(`${bin} ${args.join(' ')}`);
+        const r = await spawnHealthCommand(bin, args, cwd, opts.timeoutMs ?? 600_000, opts.signal);
+        const verdict = classifyHealthRun(bin, args, ecosystem, r);
+        if (verdict === 'skip' || verdict === 'pass')
             continue;
-        if (r.status !== 0) {
-            return {
-                ok: false,
-                reason: `\`${bin} ${args.join(' ')}\` exited ${r.status}`,
-                ecosystem,
-                output: captureHealthOutput(r.stdout, r.stderr)
-            };
-        }
+        return verdict;
     }
     return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem, output: '' };
 }

package/dist/task/task-gates.d.ts

@@ -99,7 +99,11 @@ export interface GateDeps {
      * revert cycle. Checking before committing skips that cycle. Absent → the old
      * commit-then-differential path runs unchanged.
      */
-    repoHealth?: (cwd: string) => Promise<{
+    /** Deterministic whole-repo static check for the enforce pre-commit gate. Takes
+     *  the live ctx and a label so the implementation can render a status line while
+     *  it runs — it is as slow as the project's own lint (15–69s measured), and a
+     *  gate step that long with no widget is indistinguishable from a hang. */
+    repoHealth?: (ctx: ExtensionCommandContext, cwd: string, label: string) => Promise<{
         ok: boolean;
         reason: string;
         output?: string;

package/dist/task/task-gates.js

@@ -419,7 +419,9 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // good work for a fault it did not cause). Only meaningful in edit mode (flag
         // makes no edits); the task's work is already committed so this reflects the
         // committed state the pass is about to build on.
-        const healthBefore = mode === 'edit' && deps.repoHealth ? await deps.repoHealth(p.cwd) : undefined;
+        const healthBefore = mode === 'edit' && deps.repoHealth ?
+            await deps.repoHealth(active, p.cwd, p.title)
+            : undefined;
         const verdict = await deps.enforce(active, p.cwd, p.title, mode);
         // FROZEN-PATH WRITE-DENY (mechanical, not prompt — the "MUST NOT edit"
         // instruction is A/B-proven ~0–1/5 reliable on the weak model): the enforce
@@ -466,7 +468,7 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // unreproducible precisely because only the exit code was recorded.
         let enforceEditsBlocked = false;
         if (mode === 'edit' && deps.repoHealth && editsMade !== false) {
-            const after = await deps.repoHealth(p.cwd);
+            const after = await deps.repoHealth(active, p.cwd, p.title);
             // A regression needs a clean (or unknown) baseline turning to a fail. If
             // healthBefore is undefined (repoHealth was absent at baseline time) treat
             // the baseline as clean — the conservative absolute behavior.

package/dist/task/verify-work.d.ts

@@ -122,6 +122,14 @@ export interface VerificationDeps {
         ok: boolean;
         reason: string;
     }>;
+    /**
+     * Progress hook for the DETERMINISTIC stage — the repo-health run plus the ten
+     * probes below, all of which run BEFORE the child (and therefore before the
+     * child's own status widget exists). Called with a short label as each step
+     * starts, so the caller can keep a live line on screen through what was
+     * otherwise the run's longest stretch of dead air (MEASURED at 15–69s per
+     * repo-health run). ABSENT → no progress reporting, same behaviour as before. */
+    onStage?: (stage: string) => void;
     /**
      * DETERMINISTIC substitution probe (see substitution-probe.ts): scans the task's
      * changed test files for test-the-copy shapes and returns finding lines to inject

package/dist/task/verify-work.js

@@ -597,7 +597,16 @@ export async function runWorkVerification(deps) {
     // 5/5 false-PASS live) — because it does not depend on that block. A fail is the
     // ordinary verify-FAIL outcome, so it flows into the existing resolution picker.
     // Absent dep, or a no-op result (no tooling to run), falls through to the model.
+    const stage = (label) => {
+        try {
+            deps.onStage?.(label);
+        }
+        catch {
+            // progress reporting must never break the gate
+        }
+    };
     if (deps.repoHealth) {
+        stage('repo health');
         const h = await deps.repoHealth();
         if (!h.ok)
             return { ok: false, reason: `repo health: ${h.reason}` };
@@ -609,6 +618,7 @@ export async function runWorkVerification(deps) {
     // verification (it is an optional sharpener, the gate still runs without it).
     let findings = [];
     if (deps.probe) {
+        stage('substitution probe');
         try {
             findings = await deps.probe();
         }
@@ -618,6 +628,7 @@ export async function runWorkVerification(deps) {
     }
     let prohibitions = [];
     if (deps.prohibitionProbe) {
+        stage('prohibition probe');
         try {
             prohibitions = await deps.prohibitionProbe();
         }
@@ -629,6 +640,7 @@ export async function runWorkVerification(deps) {
     // block verification — it is an optional sharpener like the substitution probe.
     let testAssembly = [];
     if (deps.testAssemblyProbe) {
+        stage('test-assembly probe');
         try {
             testAssembly = await deps.testAssemblyProbe();
         }
@@ -640,6 +652,7 @@ export async function runWorkVerification(deps) {
     // block verification — an optional sharpener like the other diff-shape probes.
     let probeGaming = [];
     if (deps.probeGamingProbe) {
+        stage('probe-gaming probe');
         try {
             probeGaming = await deps.probeGamingProbe();
         }
@@ -652,6 +665,7 @@ export async function runWorkVerification(deps) {
     // failure must never block verification.
     let crossDeletions = [];
     if (deps.crossTaskDeletionProbe) {
+        stage('cross-task deletion probe');
         try {
             crossDeletions = await deps.crossTaskDeletionProbe();
         }
@@ -663,6 +677,7 @@ export async function runWorkVerification(deps) {
     // under rule 4e. A probe failure must never block verification.
     let foreignPaths = [];
     if (deps.foreignPathProbe) {
+        stage('foreign-path probe');
         try {
             foreignPaths = await deps.foreignPathProbe();
         }
@@ -674,6 +689,7 @@ export async function runWorkVerification(deps) {
     // 4f. A probe failure must never block verification.
     let scriptEscapes = [];
     if (deps.scriptEscapeProbe) {
+        stage('script-escape probe');
         try {
             scriptEscapes = await deps.scriptEscapeProbe();
         }
@@ -685,6 +701,7 @@ export async function runWorkVerification(deps) {
     // never block verification.
     let runnerGlobs = [];
     if (deps.runnerGlobProbe) {
+        stage('runner-glob probe');
         try {
             runnerGlobs = await deps.runnerGlobProbe();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",