@mjasnikovs/pi-task 0.38.7 → 0.38.9

package/dist/task/auto-orchestrator.d.ts

@@ -1,6 +1,9 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type GateDeps } from './task-gates.js';
 import { type FinalGateStageDeps } from './run-final-gate.js';
+import { type RequirementEntry } from './requirements.js';
+import { type ScoredPlan } from './coverage-loop.js';
+import { type DanglingRef } from './artifact-closure.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is the planning-only seam used by planAuto; everything else is one of
@@ -75,6 +78,84 @@ export declare function attachSpecRefs(titles: string[], refs: string[]): string
  * authoritative spec ref still rides on THIS step's own title via attachSpecRefs.
  */
 export declare function buildScopeFence(titles: string[], currentIndex: number): string;
+/**
+ * What ORIENT establishes about the feature before anyone is asked anything: the
+ * spec text the planning children will actually read, and the requirement ledger
+ * derived from it. Every later stage reads these; none of them writes one.
+ */
+export interface OrientedFeature {
+    /** The inlined spec, with phantom runtime specifiers struck out. */
+    featureForModel: string;
+    /** Manifest/config already on disk, fed to every triage call. '' when absent. */
+    existingFilesBlock: string;
+    /** Grounded requirement units extracted from the spec. */
+    reqEntries: RequirementEntry[];
+    /** How many of those a single task could own (cross-cutting ones excluded). */
+    ownableRequirements: number;
+    /** The task-count floor those ownable requirements imply. 0 ⇒ no channel. */
+    coarseFloor: number;
+}
+/**
+ * ORIENT — read the feature, strike what must never reach a planning child, and
+ * derive the requirement ledger. Depends on nothing but the feature and the tree,
+ * which is why it runs before clarify: the plan-shape fork below needs a real
+ * count to judge with. Every fallible part is best-effort; a fault degrades the
+ * channel it belongs to and never fails planning.
+ */
+export declare function orientFeature(cwd: string, feature: string, deps: AutoDeps): Promise<OrientedFeature>;
+/**
+ * ELICIT — clarify, sequential & adaptive: ask one question at a time, feeding every
+ * answer back into the next call so later questions react to earlier ones (e.g. a
+ * framework choice reshapes what gets asked). Each question is shown exactly like
+ * /task's grill dialog: a binary fork offers two options (A/B), otherwise the model's
+ * recommendation is shown as the input placeholder and in the title. Nothing is
+ * pre-filled into the editor — submitting an empty field is what accepts the
+ * recommendation; typing overrides it. Each generated question first runs the
+ * answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec already
+ * settles is auto-resolved and never shown — only genuine open forks reach the user.
+ * The model emits NONE when nothing remains.
+ *
+ * The ONLY stage that talks to the user, and so the only one that can be dismissed:
+ * `null` means the user cancelled and the cancellation has already been announced.
+ * Every other outcome is a transcript, possibly empty.
+ */
+export declare function elicitClarifications(ctx: ExtensionCommandContext, cwd: string, deps: AutoDeps, oriented: OrientedFeature): Promise<string | null>;
+/**
+ * What DECOMPOSE settles: the task list, plus the two things the coverage loop
+ * needs to ask for a better one. `decomposePrompt` and `parsePlan` are returned
+ * rather than rebuilt because COVER re-prompts with the identical prompt and must
+ * reconcile the reply identically — rebuilding either is how the two paths drift.
+ */
+export interface DecomposedPlan {
+    /** The reconciled, de-batched task titles. May be empty. */
+    planTitles: string[];
+    /** The exact prompt that produced them, for COVER's re-prompt. */
+    decomposePrompt: string;
+    /** Parse + fidelity-reconcile + de-batch, applied to EVERY decompose output. */
+    parsePlan: (raw: string) => string[];
+}
+/**
+ * DECOMPOSE — turn the settled feature into a task list, then defend that list's
+ * SHAPE: a plan under the granularity floor is sent back once to be split, and a
+ * suspect (empty or tiny) plan is regenerated on its own separate budget. Neither
+ * guard can block planning — a plan that survives both falls through to the judge.
+ */
+export declare function decomposePlan(cwd: string, deps: AutoDeps, oriented: OrientedFeature, clarifications: string): Promise<DecomposedPlan>;
+/** What COVER settles: the plan that ships, and the accounting behind it. */
+export interface CoveredPlan {
+    /** The best-covered plan seen across the rounds — adoption is monotone. */
+    best: ScoredPlan;
+    /** That plan's titles, which is what everything downstream persists. */
+    planTitles: string[];
+}
+/**
+ * COVER — judge the plan against the feature and re-prompt for a better one, up to
+ * a bounded number of rounds. Adoption is MONOTONE: a retry that drops a
+ * requirement the current plan owns is rejected, so coverage can only hold or grow,
+ * and the plan at exhaustion is the best one seen rather than the last one drawn.
+ * Best-effort throughout — a fault degrades a signal, it never blocks planning.
+ */
+export declare function coverPlan(ctx: ExtensionCommandContext, cwd: string, deps: AutoDeps, oriented: OrientedFeature, clarifications: string, decomposed: DecomposedPlan, specDangling: DanglingRef[]): Promise<CoveredPlan>;
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export declare function planAuto(ctx: ExtensionCommandContext, cwd: string, feature: string, deps: AutoDeps): Promise<string | null>;
 export declare function requestAutoCancel(): void;

package/dist/task/auto-orchestrator.js

@@ -25,7 +25,7 @@ import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from
 import { armCancelListener, disarmCancelListener } from './cancel-input.js';
 import { beginRun, endRun } from './mid-run-input.js';
 import { reportDroppedInput } from './dropped-input.js';
-import { refineExistingFilesBlock } from './phases.js';
+import { refineExistingFilesBlock, SINGLE_READ_EXTENSION_PATH } from './phases.js';
 import { SessionUI, registerBridgeCommand, publishLifecycleNotice } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { startAutoLoader } from './widget.js';
@@ -409,21 +409,14 @@ async function schedulePendingRepairs(cwd, id, afterIndex, ctx, deps) {
         // the plan is best-effort here; the underlying debt is already recorded
     }
 }
-/** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
-export async function planAuto(ctx, cwd, feature, deps) {
-    // clarify — sequential & adaptive: ask one question at a time, feeding every
-    // answer back into the next call so later questions react to earlier ones
-    // (e.g. a framework choice reshapes what gets asked). Each question is shown
-    // exactly like /task's grill dialog: a binary fork offers two options (A/B),
-    // otherwise the model's recommendation is shown as the input placeholder and
-    // in the title. Nothing is pre-filled into the editor — submitting an empty
-    // field is what accepts the recommendation (see the typed.length === 0 branch
-    // below); typing overrides it. Each generated question first runs the
-    // answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec
-    // already settles is auto-resolved and never shown — only genuine open forks
-    // reach the user. The model emits NONE when nothing remains.
-    const theme = ctx.ui.theme;
-    const ui = new SessionUI(ctx);
+/**
+ * ORIENT — read the feature, strike what must never reach a planning child, and
+ * derive the requirement ledger. Depends on nothing but the feature and the tree,
+ * which is why it runs before clarify: the plan-shape fork below needs a real
+ * count to judge with. Every fallible part is best-effort; a fault degrades the
+ * channel it belongs to and never fails planning.
+ */
+export async function orientFeature(cwd, feature, deps) {
     // Inline any @file spec the user referenced so clarify/decompose reason over
     // the real content, not a one-line "Implement @file" that reads as trivial.
     const rawFeatureForModel = await expandFeatureMentions(cwd, feature);
@@ -456,12 +449,8 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // into the decompose prompt as a ledger (structure-mirroring can't discharge
     // them) and drive the per-requirement coverage accounting below.
     //
-    // Runs BEFORE clarify (it depends only on the inlined feature, never on the
-    // answers) so the plan-shape gate below has a real count to judge with: the
-    // host must not seize the granularity fork on a spec that has no breakdown to
-    // speak of. Best-effort:
-    // a fault leaves reqEntries empty and the whole channel degrades to the old
-    // behavior (one-liners / doc-less features naturally yield few or none).
+    // Best-effort: a fault leaves reqEntries empty and the whole channel degrades to
+    // the old behavior (one-liners / doc-less features naturally yield few or none).
     let reqEntries = [];
     try {
         // Recall floor: the obligation-marked passages ride into the prompt as a
@@ -499,6 +488,28 @@ export async function planAuto(ctx, cwd, feature, deps) {
         logPlanDebug(cwd, `granularity floor: ${ownableRequirements} ownable requirement(s) ⇒ at least `
             + `${coarseFloor} task(s)`);
     }
+    return { featureForModel, existingFilesBlock, reqEntries, ownableRequirements, coarseFloor };
+}
+/**
+ * ELICIT — clarify, sequential & adaptive: ask one question at a time, feeding every
+ * answer back into the next call so later questions react to earlier ones (e.g. a
+ * framework choice reshapes what gets asked). Each question is shown exactly like
+ * /task's grill dialog: a binary fork offers two options (A/B), otherwise the model's
+ * recommendation is shown as the input placeholder and in the title. Nothing is
+ * pre-filled into the editor — submitting an empty field is what accepts the
+ * recommendation; typing overrides it. Each generated question first runs the
+ * answer-side TRIAGE (triageClarifyQuestion): a question the inlined spec already
+ * settles is auto-resolved and never shown — only genuine open forks reach the user.
+ * The model emits NONE when nothing remains.
+ *
+ * The ONLY stage that talks to the user, and so the only one that can be dismissed:
+ * `null` means the user cancelled and the cancellation has already been announced.
+ * Every other outcome is a transcript, possibly empty.
+ */
+export async function elicitClarifications(ctx, cwd, deps, oriented) {
+    const { featureForModel, existingFilesBlock, ownableRequirements } = oriented;
+    const theme = ctx.ui.theme;
+    const ui = new SessionUI(ctx);
     const answers = [];
     // Plain text of every question already shown, for the duplicate backstop.
     const askedQuestions = [];
@@ -615,26 +626,16 @@ export async function planAuto(ctx, cwd, feature, deps) {
     if (answers.length === 0) {
         ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
     }
-    const clarifications = answers.join('\n');
-    // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
-    // files the spec REFERENCES (server snippets, prose "serve the built
-    // index.html") that neither its file tree, its parsed build outputs, nor the
-    // existing scaffold produce. Sentence-grounded coverage credited the SERVING
-    // side and reported "0 unowned" while nothing ever CREATED the file — so
-    // these ride the coverage loop's `missing` list as unowned areas until some
-    // task title claims the artifact (grounded in titles, which the coverage-map
-    // model cannot fake — the run-12 lesson). Deterministic and best-effort.
-    let specDangling = [];
-    try {
-        specDangling = findSpecDanglingArtifacts(featureForModel, rel => existsSync(path.join(cwd, rel)));
-        if (specDangling.length > 0) {
-            logPlanDebug(cwd, `artifact closure: ${specDangling.length} dangling runtime artifact(s) in the `
-                + `spec: ${specDangling.map(d => d.path).join(', ')}`);
-        }
-    }
-    catch {
-        // best-effort channel
-    }
+    return answers.join('\n');
+}
+/**
+ * DECOMPOSE — turn the settled feature into a task list, then defend that list's
+ * SHAPE: a plan under the granularity floor is sent back once to be split, and a
+ * suspect (empty or tiny) plan is regenerated on its own separate budget. Neither
+ * guard can block planning — a plan that survives both falls through to the judge.
+ */
+export async function decomposePlan(cwd, deps, oriented, clarifications) {
+    const { featureForModel, reqEntries, ownableRequirements, coarseFloor } = oriented;
     // Tests-in-the-same-change cadence (mx5 run 14, PROMPT item 6): when the
     // decisions mandate it, a whole-project batch test task contradicts them —
     // run 14 shipped one anyway (TASK_0037, 4.7h, yolo-accepted FAIL) because
@@ -729,6 +730,19 @@ export async function planAuto(ctx, cwd, feature, deps) {
         if (retryTitles.length > planTitles.length)
             planTitles = retryTitles;
     }
+    return { planTitles, decomposePrompt, parsePlan };
+}
+/**
+ * COVER — judge the plan against the feature and re-prompt for a better one, up to
+ * a bounded number of rounds. Adoption is MONOTONE: a retry that drops a
+ * requirement the current plan owns is rejected, so coverage can only hold or grow,
+ * and the plan at exhaustion is the best one seen rather than the last one drawn.
+ * Best-effort throughout — a fault degrades a signal, it never blocks planning.
+ */
+export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomposed, specDangling) {
+    const { featureForModel, reqEntries } = oriented;
+    const { decomposePrompt, parsePlan } = decomposed;
+    let planTitles = decomposed.planTitles;
     // Coverage gate: a stochastic degenerate completion (live mx5: ONE task +
     // natural EOS for an 18KB design doc) is nonempty, so the length guard below
     // never fires and the whole run "completes" after one task. Judge the list
@@ -905,6 +919,44 @@ export async function planAuto(ctx, cwd, feature, deps) {
             + 'task. To give it one, stop now and add it to the plan in .pi-tasks/; otherwise '
             + 'it proceeds.', 'warning');
     }
+    return { best, planTitles };
+}
+/** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
+export async function planAuto(ctx, cwd, feature, deps) {
+    // ORIENT. Reads the feature and the tree, asks nobody anything.
+    const oriented = await orientFeature(cwd, feature, deps);
+    // The floor and the ownable count are DECOMPOSE's to enforce; what the tail of
+    // this function still reads is the spec text and the requirement ledger.
+    const { featureForModel, reqEntries } = oriented;
+    // ELICIT. The only stage that talks to the user.
+    const clarifications = await elicitClarifications(ctx, cwd, deps, oriented);
+    if (clarifications === null)
+        return null; // dismissed; already announced
+    // Artifact-production closure, plan side (mx5 run 13, PROMPT 2): runtime
+    // files the spec REFERENCES (server snippets, prose "serve the built
+    // index.html") that neither its file tree, its parsed build outputs, nor the
+    // existing scaffold produce. Sentence-grounded coverage credited the SERVING
+    // side and reported "0 unowned" while nothing ever CREATED the file — so
+    // these ride the coverage loop's `missing` list as unowned areas until some
+    // task title claims the artifact (grounded in titles, which the coverage-map
+    // model cannot fake — the run-12 lesson). Deterministic and best-effort.
+    let specDangling = [];
+    try {
+        specDangling = findSpecDanglingArtifacts(featureForModel, rel => existsSync(path.join(cwd, rel)));
+        if (specDangling.length > 0) {
+            logPlanDebug(cwd, `artifact closure: ${specDangling.length} dangling runtime artifact(s) in the `
+                + `spec: ${specDangling.map(d => d.path).join(', ')}`);
+        }
+    }
+    catch {
+        // best-effort channel
+    }
+    // DECOMPOSE. Produces the task list and the means to ask for a better one.
+    const decomposedPlan = await decomposePlan(cwd, deps, oriented, clarifications);
+    // COVER. Judges the plan and re-prompts for a better one, monotonically.
+    const covered = await coverPlan(ctx, cwd, deps, oriented, clarifications, decomposedPlan, specDangling);
+    const best = covered.best;
+    const planTitles = covered.planTitles;
     // Carry what no single task owns (goal A(b)/(c)): cross-cutting requirements
     // become `.pi-tasks/requirements.md`, injected VERBATIM into every task's
     // refine/compose (run 11: §10's test-first cadence had no carrier — the "spec
@@ -942,6 +994,20 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ctx.ui.notify(`/task-auto: carrying ${parts.join(', ')} requirement(s) into every task`
             + ' — see .pi-tasks/requirements.md.', 'info');
     }
+    // Thread the feature's spec doc(s) into every title so each per-task
+    // pipeline — which only ever sees its title — reads the real spec instead of
+    // a lossy one-line paraphrase of it.
+    const refs = await readableMentions(cwd, feature);
+    const titles = attachSpecRefs(planTitles, refs);
+    if (titles.length === 0) {
+        announceDone(ctx, '/task-auto: no tasks produced from the feature.', 'warning');
+        return null;
+    }
+    // The two grounded extractions below run AFTER the empty-plan guard on purpose.
+    // They each spawn a child and each APPEND to a run-level artifact; on the
+    // empty-plan path the plan is discarded one line later, so running them first
+    // burned two model calls and left contracts.md / launch-contract.md carrying
+    // facts for a run that never produced a task.
     // Cross-slice contract registry (mx5 run 8, F3): now that the plan is settled,
     // extract the interface facts MORE THAN ONE slice must agree on — endpoint paths,
     // exported signatures, file layouts, env var names the DESIGN pins — into a
@@ -983,15 +1049,6 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ground: emitted => keepGroundedScripts(emitted, featureForModel),
         append: appendDeclaredScripts
     });
-    // Thread the feature's spec doc(s) into every title so each per-task
-    // pipeline — which only ever sees its title — reads the real spec instead of
-    // a lossy one-line paraphrase of it.
-    const refs = await readableMentions(cwd, feature);
-    const titles = attachSpecRefs(planTitles, refs);
-    if (titles.length === 0) {
-        announceDone(ctx, '/task-auto: no tasks produced from the feature.', 'warning');
-        return null;
-    }
     // Persist the TASK-MAPPED requirements keyed by the (spec-ref-attached) title
     // each task will carry (mx5 run 16: only cross-cutting entries travelled;
     // the 33 mapped ones shaped the title list and vanished — TASK_0008 narrowed
@@ -1079,6 +1136,13 @@ function defaultDeps(ctx, cwd, signal, title) {
         cwd,
         taskId: '',
         signal,
+        // IN-RUN thrash guard for the planning children (mx5-n 2026-08-14: a
+        // decompose child re-read DESIGN/marketplace.html until it filled a
+        // 120k window, and ran 16m23s without returning). Every planning child
+        // gets its source doc INLINED in its prompt, so a second read of a file
+        // it has already opened can only be thrash — which makes the read-once
+        // block safe here in a way it is not for a phase that must explore.
+        childExtensions: [SINGLE_READ_EXTENSION_PATH],
         onChildOutput: (line) => {
             lastLine = line;
         },

package/dist/task/child-runner.d.ts

@@ -58,14 +58,16 @@ export interface PhaseRunResult {
     /** Set when the child's final turn failed with stopReason "error" (model/provider failure). */
     modelError?: string;
 }
-export declare function childArgs(tools: string): string[];
+export declare function childArgs(tools: string, extensions?: readonly string[]): string[];
 export declare const USER_CANCELLED = "__user_cancelled__";
 /**
  * Run a child pi process with JSON event-stream output, loop detection, and
  * context-usage tracking. This is the typed convenience wrapper used by
  * phase-level code.
  */
-export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn): Promise<PhaseRunResult>;
+export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn, 
+/** Internal `-e` extension paths for in-run guards (see childArgs). */
+extensions?: readonly string[]): Promise<PhaseRunResult>;
 interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -79,6 +81,17 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
+    /**
+     * Internal `-e` extension paths loaded into this child for IN-RUN guards.
+     *
+     * The point of a guard that runs inside the child is that it does not have
+     * to kill it: pi turns a `tool_call` handler's `{block, reason}` into an
+     * error tool result, so the model reads the reason as its own tool output
+     * and continues with its context intact. The host's only alternative is to
+     * kill and re-spawn from nothing, which just re-runs a model that
+     * deterministically re-thrashes (workers/single-read-guard.ts).
+     */
+    childExtensions?: readonly string[];
     /**
      * Wall-clock budget for ONE spawn of this child, in ms. Defaults to
      * PHASE_CHILD_TIMEOUT_MS; `0` disables the cap. Mirrors runWorker's

package/dist/task/child-runner.js

@@ -127,7 +127,7 @@ export function connectionRetryBackoffMs(attempt) {
 }
 const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 // ─── Spawn helpers ───────────────────────────────────────────────────────────
-export function childArgs(tools) {
+export function childArgs(tools, extensions = []) {
     // `--mode json` puts the child into the structured event stream the
     // unified runner parses in `mode: 'json-events'`. Without it the child
     // emits plain text, every line fails JSON.parse, finalText stays empty,
@@ -142,8 +142,13 @@ export function childArgs(tools) {
     // The prompt is NOT an argv element: it goes to the child over stdin (see
     // runChild below / getPiInvocation), so a large inlined-design prompt can't
     // overflow the OS command-line limit (Windows `spawn ENAMETOOLONG`).
+    //
+    // `extensions` are internal `-e` loads for in-run guards (the caller supplies
+    // the path). A no-tools child cannot make a tool call, so it never carries
+    // one — the guards all hang off pi's `tool_call` hook.
     const toolFlags = tools === '' ? ['--no-tools'] : ['--tools', tools];
-    return [...childBaseArgs(), '--mode', 'json', ...toolFlags];
+    const internal = tools === '' ? [] : extensions;
+    return [...childBaseArgs(internal), '--mode', 'json', ...toolFlags];
 }
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
@@ -154,8 +159,10 @@ export const USER_CANCELLED = '__user_cancelled__';
  * context-usage tracking. This is the typed convenience wrapper used by
  * phase-level code.
  */
-export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn) {
-    const invocation = getPiInvocation(childArgs(tools), prompt);
+export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn, 
+/** Internal `-e` extension paths for in-run guards (see childArgs). */
+extensions) {
+    const invocation = getPiInvocation(childArgs(tools, extensions), prompt);
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
         mode: 'json-events',
@@ -289,7 +296,7 @@ export async function runPhaseChild(deps, name, tools, prompt) {
         const clock = phaseTimeout(deps.signal, budgetMs);
         let r;
         try {
-            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn);
+            r = await runChild(deps.cwd, tools, prependHint(hint, prompt), clock.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn, deps.childExtensions);
         }
         finally {
             clock.cleanup();

package/dist/task/phases.d.ts

@@ -111,6 +111,15 @@ export declare function searchConfigured(getEnv?: (k: string) => string | undefi
 /** Extra prompt block for the APIS worker when search is available — trigger-framed
  *  (the validated shape for getting a local model to actually reach for search). */
 export declare const RESEARCH_SEARCH_HINT: string;
+/**
+ * In-process guards loaded into the TOOLING worker only: block a re-read of any
+ * file already read, and block any byte-identical grep/find/ls repeat, feeding
+ * the model "you already have this, answer now" instead of letting it re-run.
+ * TOOLING reads each file once and never needs an identical search twice in any
+ * healthy recorded run, so neither rule has a legitimate false positive here.
+ * See single-read-guard.ts.
+ */
+export declare const SINGLE_READ_EXTENSION_PATH: string;
 /**
  * The TOOLING worker only needs to know which verification commands the task
  * cares about — never the per-file edit list. Big refined prompts embed a long

package/dist/task/phases.js

@@ -332,7 +332,7 @@ export const RESEARCH_SEARCH_HINT = '\n\nLIVE WEB — use pi-worker-search for e
  * healthy recorded run, so neither rule has a legitimate false positive here.
  * See single-read-guard.ts.
  */
-const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/single-read-extension.js', import.meta.url));
+export const SINGLE_READ_EXTENSION_PATH = fileURLToPath(new URL('../workers/single-read-extension.js', import.meta.url));
 /**
  * Task-file heading under which a research worker's validated output is cached.
  * A resumed research phase reads these to skip workers that already succeeded,

package/dist/task/run-final-gate.d.ts

@@ -30,7 +30,8 @@ import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { CommitResult } from './auto-commit.js';
 import type { FinalGateOutcome } from './final-gate.js';
 import type { FinalGateFixFn } from './gate-deps.js';
-import { type AcceptDebt } from './accept-debt.js';
+import { type AcceptDebt, type DebtOrigin } from './accept-debt.js';
+import { type OwnedRequirement } from './requirements.js';
 /**
  * The seams this stage drives. A strict subset of what /task-auto builds, and
  * deliberately narrow: every optional dep absent degrades to a documented earlier
@@ -86,6 +87,20 @@ export interface FinalGateStageDeps {
      *  file) — the same auditability contract the per-task records carry. Best-effort:
      *  absent in tests → skipped; a failure never breaks the gate. */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
+    /**
+     * Write one ACCEPT debt to the ledger. The run-level twin of `GateDeps.recordDebt`,
+     * and injectable for the same reason: without it a test that only wants to observe
+     * WHICH debts a scenario carries has to write, and then read back, the real ledger
+     * on disk. Absent → the real `accept-debt.ts` writer, so production wiring and the
+     * prior behaviour are unchanged.
+     */
+    recordDebt?: (cwd: string, taskId: string, reason: string, origin: DebtOrigin) => Promise<void>;
+    /**
+     * Read the owned-requirement ledger, to report obligations a task DETACHED and no
+     * later task claimed. Absent → the real `requirements.ts` reader (prior behaviour);
+     * injectable so that check is testable without seeding a real ledger file.
+     */
+    ownedRequirements?: (cwd: string) => Promise<OwnedRequirement[]>;
 }
 /** Inputs that vary per caller. */
 export interface FinalGateStageParams {

package/dist/task/run-final-gate.js

@@ -73,7 +73,7 @@ export async function runFinalGateStage(active, deps, p) {
      * What they no longer each restate is WHERE the debt goes: the run's own id, under
      * origin 'final-gate', which is what the next run's gate re-checks.
      */
-    const carryDebt = (reason) => recordDebt(cwd, id, reason, 'final-gate');
+    const carryDebt = (reason) => (deps.recordDebt ?? recordDebt)(cwd, id, reason, 'final-gate');
     // Set when the gate finished having observed NOTHING dynamic. Declared out here so
     // the run-completion announcement can say so.
     let unobservedNote = null;
@@ -147,7 +147,7 @@ export async function runFinalGateStage(active, deps, p) {
     // satisfy it, nexttask 2) and no later task claimed. Detach never deletes the
     // quote, so the run ends holding it — say so, or the resolution would be a quieter
     // version of the deletion it exists to prevent.
-    const unclaimed = unclaimedPendingRequirements(await readOwnedRequirements(cwd).catch(() => []));
+    const unclaimed = unclaimedPendingRequirements(await (deps.ownedRequirements ?? readOwnedRequirements)(cwd).catch(() => []));
     for (const o of unclaimed) {
         await recGate(`owned requirement UNCLAIMED — "${o.quote.slice(0, 200)}"`
             + ` [frozen in "${o.title.slice(0, 60)}"; no task claimed`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.7",
+    "version": "0.38.9",
     "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",