@mjasnikovs/pi-task 0.19.0 → 0.20.1

package/dist/remote/register.js

@@ -1,5 +1,5 @@
 import { getConfig } from '../config/config.js';
-import { getBridge, dispatchRemoteLine, dispatchRemoteNewSession, makeShimmedCtx, interruptAgent } from './bridge.js';
+import { getBridge, dispatchRemoteLine, dispatchRemoteNewSession, makeShimmedCtx, interruptAgent, registerBridgeCommand } from './bridge.js';
 import { setupEvents } from './events.js';
 import { reset, addUserTurn } from './session-state.js';
 import { html } from './ui.js';
@@ -84,7 +84,10 @@ export function registerRemote(pi) {
             S.send = null;
         }
     });
-    pi.registerCommand('remote', {
+    // Bridge-registered (not pi.registerCommand) so `/remote stop` also works when
+    // typed in the browser — the web UI advertises it, and while a /task-auto run
+    // holds the host command loop the browser is the only live input surface.
+    registerBridgeCommand(pi, 'remote', {
         description: 'Show the remote QR code & URLs.',
         handler: async (args, ctx) => {
             if (!getConfig().remote) {

package/dist/task/auto-orchestrator.js

@@ -41,7 +41,7 @@ import { configureResearchRun, resumeResearchRun } from '../workers/research-cac
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
 import { reconcileTitleSources } from './decompose-fidelity.js';
 import { mandatesTestsInSameChange, rewriteBatchTestPlan } from './batch-test-task.js';
-import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
+import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, writeOwnedRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
 import { decideAdoption, groundedCoverage } from './coverage-loop.js';
 import { findSpecDanglingArtifacts, titlesCoverArtifact, danglingMissingText, danglingCarryText } from './artifact-closure.js';
 import { LAUNCH_EXTRACT_PROMPT, enumerateScriptCandidates, parseScriptLines, keepGroundedScripts, appendDeclaredScripts } from './launch-contract.js';
@@ -567,7 +567,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
         }
         // Bound with marked-passage priority — a plain first-N cap truncates the
         // doc's tail sections (measured live: an eager model fills 40 top-down).
-        reqEntries = capRequirements(reqEntries, passages);
+        reqEntries = capRequirements(reqEntries, passages, featureForModel);
         logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
     }
     catch {
@@ -903,6 +903,17 @@ export async function planAuto(ctx, cwd, feature, deps) {
         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
+    // §9's "serves `/api` + static `dist/`" out of its spec with nothing to stop
+    // it). Inert until the owned-requirements injection is wired into the phase
+    // prompts; recorded regardless so the plan's mapping is auditable per run.
+    if (accounting && accounting.mapped.length > 0) {
+        await writeOwnedRequirements(cwd, accounting.mapped
+            .filter(m => m.task >= 1 && m.task <= titles.length)
+            .map(m => ({ quote: m.req.quote, anchor: m.req.anchor, title: titles[m.task - 1] })));
+    }
     // persist
     const id = await allocateAutoId(cwd);
     const now = new Date().toISOString();

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

@@ -62,6 +62,9 @@ type BootOutcome = {
     /** Set when the render check could not OBSERVE the served page (no browser,
      *  undeterminable port) — surfaced by the gate as an UNOBSERVED warning. */
     renderNote?: string;
+    /** skip only: the boot command never spawned (ENOENT) — feeds the
+     *  full-blindness guard (mx5 run 16), unlike a 127 where the runner ran. */
+    spawnFailed?: boolean;
 } | {
     outcome: 'fail';
     detail: string;
@@ -218,6 +221,32 @@ export declare function discoverGateCommandLabels(cwd: string): string[];
  * this box; the same wording in a `test` run is a real failure the suite must own).
  */
 export declare const INFRA_GAP_OUTPUT_RE: RegExp;
+/**
+ * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
+ * DISCOVERED but every single one skipped as an environment gap, so the gate
+ * decided on statics alone and stamped a permanently blank app green. Per-command
+ * env-gap skips stay legitimate (a missing browser must not fail a suite); what
+ * may never happen again is ALL of them skipping while the gate still reports
+ * PASS — a gate that observed nothing dynamic has no basis to vouch for the
+ * assembled app. Pure so the semantics are unit-tested; the caller feeds it the
+ * attempt/observation counters and runner resolvability.
+ */
+export declare function observabilityGapFailure(args: {
+    /** Dynamic commands the gate discovered and tried to run. */
+    attempted: number;
+    /** Of those, how many it actually OBSERVED (a real pass OR a real fail —
+     *  either proves the command ran; only skips observe nothing). */
+    observed: number;
+    /** Of the skips, how many were SPAWN failures (runner never ran, ENOENT).
+     *  Tool-level gaps (missing browser, 127 inside the chain, timeout) prove
+     *  the runner itself works and keep the classic env-gap contract — the
+     *  blindness class fires only when EVERY attempt failed to even spawn. */
+    spawnFailures: number;
+    /** Distinct runner bins across the attempted commands. */
+    runnerBins: string[];
+    /** Is this runner spawnable (bare or via a known install location)? */
+    runnerResolvable: (bin: string) => boolean;
+}): string | null;
 export { taskThatIntroduced };
 /**
  * Run the final gate: static analysis first, then the lockfile consistency

package/dist/task/final-gate.js

@@ -47,6 +47,7 @@ import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtN
 import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
+import { resolveRunner, runnerEnv } from './runner-resolve.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
 function packageScripts(cwd) {
@@ -515,13 +516,17 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     // Only served apps get an assigned port: a CLI project has nothing to bind, and
     // an unexpected PORT in its env is noise.
     const assignedPort = expectServer ? await (opts.deps?.pickPort ?? pickFreePort)() : null;
+    // Runner resolution (mx5 run 16): same contract as runGateCommand — resolve
+    // the runner and carry its directory on PATH so the boot script's own chain
+    // can re-invoke it.
+    const runner = resolveRunner(bin);
     return new Promise(resolve => {
-        const child = spawn(bin, args, {
+        const child = spawn(runner.bin, args, {
             cwd,
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: {
-                ...process.env,
+                ...runnerEnv(runner),
                 ...(assignedPort !== null ? { PORT: String(assignedPort) } : {})
             }
         });
@@ -628,7 +633,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
             }
             passAndKill();
         }, graceMs);
-        child.on('error', () => settle({ outcome: 'skip' }));
+        child.on('error', () => settle({ outcome: 'skip', spawnFailed: true }));
         child.on('exit', (status, signal) => {
             if (status === 0) {
                 if (expectServer && !listenerSeen) {
@@ -713,26 +718,59 @@ export const INFRA_GAP_OUTPUT_RE = /ECONNREFUSED|connection refused|ENOTFOUND|EA
  * command that actually ran and exited non-zero for a real reason fails.
  */
 function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
+    // Runner resolution (mx5 run 16): a login-shell-stripped PATH left `bun`
+    // unspawnable, so every dynamic check skipped and the gate went blind. The
+    // resolved binary is spawned, and its directory rides on the child's PATH so
+    // the SCRIPT CHAIN can re-invoke the runner (`bun run test` runs `bun test`
+    // inside — a bare 127 there is the same blindness one level down).
     // env passed explicitly: bun's spawnSync resolves the binary against a
     // startup snapshot of the environment, not the live process.env.
-    const r = spawnSync(bin, args, {
+    const runner = resolveRunner(bin);
+    const r = spawnSync(runner.bin, args, {
         cwd,
         encoding: 'utf8',
         timeout: timeoutMs,
-        env: { ...process.env }
+        env: runnerEnv(runner)
     });
-    if (r.error || r.status === null || r.status === 127)
-        return { outcome: 'skip' };
+    if (r.error)
+        return { outcome: 'skip', spawnFailed: true };
+    if (r.status === null || r.status === 127)
+        return { outcome: 'skip', spawnFailed: false };
     if (r.status !== 0) {
         const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
         if (ENV_GAP_OUTPUT_RE.test(output))
-            return { outcome: 'skip' };
+            return { outcome: 'skip', spawnFailed: false };
         if (extraGapRe?.test(output))
-            return { outcome: 'skip' };
+            return { outcome: 'skip', spawnFailed: false };
         return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
     }
     return { outcome: 'pass' };
 }
+/**
+ * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
+ * DISCOVERED but every single one skipped as an environment gap, so the gate
+ * decided on statics alone and stamped a permanently blank app green. Per-command
+ * env-gap skips stay legitimate (a missing browser must not fail a suite); what
+ * may never happen again is ALL of them skipping while the gate still reports
+ * PASS — a gate that observed nothing dynamic has no basis to vouch for the
+ * assembled app. Pure so the semantics are unit-tested; the caller feeds it the
+ * attempt/observation counters and runner resolvability.
+ */
+export function observabilityGapFailure(args) {
+    if (args.attempted === 0 || args.observed > 0)
+        return null;
+    if (args.spawnFailures < args.attempted)
+        return null;
+    const unresolvable = args.runnerBins.filter(b => !args.runnerResolvable(b));
+    const runnerNote = unresolvable.length > 0 ?
+        ` — the project's own runner ${unresolvable
+            .map(b => `\`${b}\``)
+            .join(', ')} is not spawnable here (not on PATH nor any known install location)`
+        : '';
+    return (`observability gap: ${args.attempted} integration/boot command(s) exist but NONE `
+        + `could even spawn in this environment${runnerNote}; `
+        + `the gate observed nothing dynamic and cannot vouch for the assembled app`);
+}
 /**
  * Boot check hit an address-in-use bind failure. If the port is held by one of OUR
  * own orphaned gate children (a `dev`/`start` run), reap it and retry the boot once
@@ -833,15 +871,29 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         return withDebts({ ok: true, reason: 'no integration command found (statics passed)' });
     }
     const ran = [];
+    // Full-skip blindness counters (mx5 run 16): every dynamic spawn counts an
+    // attempt; a real pass OR a real fail counts an observation; skips observe
+    // nothing. If everything discovered ends up skipped, observabilityGapFailure
+    // turns the silence into a rank-0 failure instead of a static-only PASS.
+    let dynAttempted = 0;
+    let dynObserved = 0;
+    let dynSpawnFailures = 0;
+    const dynBins = new Set();
     for (const { prefix, list } of [
         { prefix: 'lockfile check: ', list: lockCmds },
         { prefix: '', list: cmds }
     ]) {
         for (const cmd of list) {
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
+            dynAttempted += 1;
+            dynBins.add(cmd[0]);
             const r = runGateCommand(cwd, cmd, timeoutMs);
-            if (r.outcome === 'skip')
+            if (r.outcome === 'skip') {
+                if (r.spawnFailed)
+                    dynSpawnFailures += 1;
                 continue;
+            }
+            dynObserved += 1;
             if (r.outcome === 'fail') {
                 fail(`${prefix}\`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`);
                 continue;
@@ -872,11 +924,16 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
                 continue;
             const cmd = ['bun', ['run', name]];
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
+            dynAttempted += 1;
+            dynBins.add(cmd[0]);
             const r = runGateCommand(cwd, cmd, Math.min(timeoutMs, 180_000), INFRA_GAP_OUTPUT_RE);
             if (r.outcome === 'skip') {
+                if (r.spawnFailed)
+                    dynSpawnFailures += 1;
                 skippedLaunch.push(name);
                 continue;
             }
+            dynObserved += 1;
             if (r.outcome === 'fail') {
                 fail(`launch script: \`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`);
                 continue;
@@ -901,6 +958,8 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // failures no longer shadow it. Its failures rank FIRST in the aggregate.
     if (boot) {
         const label = `${boot[0]} ${boot[1].join(' ')}`;
+        dynAttempted += 1;
+        dynBins.add(boot[0]);
         const expectServer = detectsServedApp(cwd, planText);
         // Render check (mx5 runs 8/11): for a served app, load the live page in a
         // headless browser and judge the RENDERED DOM — curl can't run JS, so a
@@ -918,6 +977,10 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         if (b.outcome === 'orphan-port') {
             b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDepsWithRender, expectServer);
         }
+        if (b.outcome !== 'skip')
+            dynObserved += 1;
+        else if (b.spawnFailed)
+            dynSpawnFailures += 1;
         if (b.outcome === 'fail') {
             fail(`boot check: \`${label}\` ${b.detail}`, 0);
         }
@@ -938,6 +1001,19 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
                 warnings.push(b.renderNote);
         }
     }
+    // Full-skip blindness guard (mx5 run 16): commands were discovered but every
+    // one skipped → rank-0 failure, never a static-only PASS. Runner resolvability
+    // is checked through resolveRunner so the failure text can name the missing
+    // runner when that is the cause (the run-16 shape: login-shell PATH lost bun).
+    const gap = observabilityGapFailure({
+        attempted: dynAttempted,
+        observed: dynObserved,
+        spawnFailures: dynSpawnFailures,
+        runnerBins: [...dynBins],
+        runnerResolvable: b => resolveRunner(b).ok
+    });
+    if (gap)
+        fail(gap, 0);
     // Artifact-production closure (mx5 run 13, PROMPT 2): a runtime file
     // reference with NO producer anywhere ships silently — the server read
     // `Bun.file('dist/index.html')` while the build emitted only app.css +

package/dist/task/phases.js

@@ -37,7 +37,7 @@ import { findSynthesizedApis, synthesizedApiReaskHint } from './api-synthesis.js
 import { findGrepOnlyVerify, grepOnlyVerifyDefectText, GREP_THEATER_RETRY_HINT } from './verify-quality.js';
 import { existsSync } from 'node:fs';
 import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from './contracts.js';
-import { readRequirements, buildRequirementsBlock } from './requirements.js';
+import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, ownedForTitle, appendOwnedConstraints } from './requirements.js';
 import { runPhaseChild, runPhaseWithLoopGuard, runWithEmphasisRetry, prependHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer, YOLO_STAMP } from './yolo.js';
@@ -152,7 +152,26 @@ export async function phaseContractsBlock(deps) {
 export async function phaseCarriedBlocks(deps) {
     const contracts = await phaseContractsBlock(deps);
     const requirements = buildRequirementsBlock(await readRequirements(deps.cwd).catch(() => ''));
-    return [contracts, requirements].filter(b => b.length > 0).join('\n');
+    const owned = buildOwnedRequirementsBlock(await ownedForThisTask(deps));
+    return [contracts, requirements, owned].filter(b => b.length > 0).join('\n');
+}
+/**
+ * The owned (task-mapped) requirements for THIS task (mx5 run 16): matched by
+ * the plan title the coverage map keyed them to, which is the task's stored
+ * `raw prompt` section verbatim. Empty outside /task-auto runs, for spliced
+ * repair tasks, and when the plan recorded no mapping — all of which degrade to
+ * the pre-run-16 behavior. This is the BELT (prompt block, into refine +
+ * compose); appendOwnedConstraints on the final spec is the BRACES — the belt
+ * alone folded the clause in only 2/8 live reps per fixture.
+ */
+async function ownedForThisTask(deps) {
+    try {
+        const title = (await readSection(deps.cwd, deps.taskId, 'raw prompt')) ?? '';
+        return ownedForTitle(await readOwnedRequirements(deps.cwd), title.trim());
+    }
+    catch {
+        return [];
+    }
 }
 export const phaseRefine = async (deps, raw, planContext) => {
     const existingFiles = await refineExistingFilesBlock(deps).catch(() => '');
@@ -1302,7 +1321,27 @@ export const PHASES = [
         field: 'spec',
         run: (d, p) => phaseCompose(d, p.refined, p.research, p.qa)
     },
-    { name: 'critique', section: 'spec', field: 'spec', run: critiqueWithFallback }
+    {
+        name: 'critique',
+        section: 'spec',
+        field: 'spec',
+        run: async (d, p) => {
+            const spec = await critiqueWithFallback(d, p);
+            // BRACES (mx5 run 16): after the LAST spec-producing step, append any
+            // owned design obligation the spec still omits as a CONSTRAINTS
+            // bullet. The belt block upstream is obeyed ~25% (measured); a
+            // host-side append is obeyed by construction. Idempotent: quotes the
+            // spec already carries (belt-obeying reps) are skipped.
+            const owned = await ownedForThisTask(d);
+            if (owned.length === 0)
+                return spec;
+            const out = appendOwnedConstraints(spec, owned);
+            if (out !== spec) {
+                d.logDebug?.('owned-requirements braces: appended omitted design obligation(s) to CONSTRAINTS');
+            }
+            return out;
+        }
+    }
 ];
 export async function postCommitPhase(phase, deps, pc, out) {
     if (phase.name !== 'refine')

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

@@ -32,6 +32,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
+import { resolveRunner, runnerEnv } from './runner-resolve.js';
 /** How much of a failing command's output to keep — bounded so a wedged tool that
  *  spews megabytes cannot bloat the trail. stderr leads (a crash trace lives there). */
 const HEALTH_OUTPUT_MAX_LINES = 40;
@@ -128,7 +129,16 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
         };
     }
     for (const [bin, args] of cmds) {
-        const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
+        // Runner resolution (mx5 run 16): a PATH-stripped environment must not
+        // silently skip the statics when the runner sits at a known install
+        // location; the resolved dir also rides on PATH for the script chain.
+        const runner = resolveRunner(bin);
+        const r = spawnSync(runner.bin, args, {
+            cwd,
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            env: runnerEnv(runner)
+        });
         // Tool missing (ENOENT) or killed by timeout → cannot conclude; skip it.
         if (r.error || r.status === null)
             continue;

package/dist/task/requirements.d.ts

@@ -13,13 +13,25 @@ export declare function parseRequirementLines(text: string): RequirementEntry[];
  *  passages from doc-order truncation. */
 export declare function keepGroundedRequirements(entries: RequirementEntry[], sourceDoc: string): RequirementEntry[];
 /**
- * Bound the list WITHOUT doc-order truncation: measured live, an eager model
- * extracts 40+ items top-down (every §1 decision row), so a plain first-N cap
- * systematically drops the TAIL sections — exactly where mx5 keeps its testing
- * obligations. Rule (deterministic priority, not a knob): entries quoting an
- * obligation-marked passage survive first; the remainder fills in given order.
+ * Bound the list WITHOUT doc-order truncation. Two measured failure shapes drive
+ * the rule:
+ *  - an eager model extracts 40+ items top-down (every §1 decision row), so a
+ *    plain first-N cap systematically drops the TAIL sections — exactly where
+ *    mx5 keeps its testing obligations;
+ *  - "given order" as the tie-break re-creates the same tail bias one level up
+ *    (mx5 run 16, measured live: the model emitted 185 requirements, 178
+ *    grounded — INCLUDING §9's "serves `/api` + static `dist/`", the clause
+ *    whose loss shipped a permanently blank app — and the cap's doc-order fill
+ *    cut all 138 past the cap, every one from the design's tail).
+ * Rule (deterministic priority, not a knob): entries quoting an obligation-
+ * marked passage survive first; the remaining budget is filled ROUND-ROBIN
+ * across the source doc's sections (each section's entries in doc order), so
+ * every section keeps its head obligations and no section is wholesale dropped.
+ * Bucketing is by the quote's POSITION in the source doc — grounded substring,
+ * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
+ * cannot be located) the fill degrades to the old given-order behavior.
  */
-export declare function capRequirements(entries: RequirementEntry[], passages: string[]): RequirementEntry[];
+export declare function capRequirements(entries: RequirementEntry[], passages: string[], sourceDoc?: string): RequirementEntry[];
 /**
  * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
  * paragraphs carrying an obligation marker (word-bounded "required"/"must").
@@ -101,6 +113,44 @@ export declare function appendCarriedRequirements(cwd: string, crossCutting: Req
  * and the VERIFY mandate is explicit — goal C rides here.
  */
 export declare function buildRequirementsBlock(requirements: string): string;
+export interface OwnedRequirement {
+    /** The verbatim design quote (the obligation). */
+    quote: string;
+    anchor: string;
+    /** The plan title of the task the coverage map assigned it to — matched
+     *  against the executing task's title at phase time (ids don't exist yet at
+     *  plan time, and spliced repair tasks shift them). */
+    title: string;
+}
+export declare function ownedRequirementsFile(cwd: string): string;
+/** Persist the task-mapped requirements (host-side, plan time). Overwrites —
+ *  the mapping is recomputed whole per plan round. Best-effort like the carried
+ *  artifact. */
+export declare function writeOwnedRequirements(cwd: string, owned: OwnedRequirement[]): Promise<void>;
+export declare function readOwnedRequirements(cwd: string): Promise<OwnedRequirement[]>;
+export declare function parseOwnedRequirements(text: string): OwnedRequirement[];
+/** The owned entries whose plan title matches THIS task's title (normalised
+ *  equality — titles travel verbatim from the plan list into task creation;
+ *  spliced repair tasks simply match nothing). */
+export declare function ownedForTitle(owned: OwnedRequirement[], title: string): OwnedRequirement[];
+/** The injection block for a task's OWN mapped obligations. Mirrors
+ *  buildRequirementsBlock (the directive pattern that measurably works) but is
+ *  singular in address: these are not "wherever they touch", they ARE this
+ *  task's obligations and must survive into the spec. */
+export declare function buildOwnedRequirementsBlock(owned: OwnedRequirement[]): string;
+/**
+ * BRACES for the owned channel (the PROMPT-1 pattern): deterministically append
+ * each owned obligation the composed spec does not already carry as a
+ * CONSTRAINTS bullet. Measured need (scripts/live-owned-requirement-compose-ab
+ * .ts, 8 reps/arm on two real run-16 losses): with the belt block alone compose
+ * folded the clause into CONSTRAINTS/ACCEPTANCE in only 2/8 reps per fixture
+ * (baseline 0/8) — an instruction the model mostly ignores, the PROMPT-4 shape.
+ * A host-side append cannot be ignored. "Already carries" = the normalised
+ * quote appears anywhere in the spec — belt-obeying reps aren't double-stated.
+ * No CONSTRAINTS section (shape-invalid spec) → returned unchanged; this runs
+ * only on specs the shape gate already accepted.
+ */
+export declare function appendOwnedConstraints(spec: string, owned: OwnedRequirement[]): string;
 /** The decompose-prompt ledger block (goal E's belt): the grounded requirement
  *  list rides into decompose so structure-mirroring can't discharge it. */
 export declare function buildRequirementsLedger(requirements: RequirementEntry[]): string;

package/dist/task/requirements.js

@@ -80,13 +80,25 @@ export function keepGroundedRequirements(entries, sourceDoc) {
     return kept;
 }
 /**
- * Bound the list WITHOUT doc-order truncation: measured live, an eager model
- * extracts 40+ items top-down (every §1 decision row), so a plain first-N cap
- * systematically drops the TAIL sections — exactly where mx5 keeps its testing
- * obligations. Rule (deterministic priority, not a knob): entries quoting an
- * obligation-marked passage survive first; the remainder fills in given order.
+ * Bound the list WITHOUT doc-order truncation. Two measured failure shapes drive
+ * the rule:
+ *  - an eager model extracts 40+ items top-down (every §1 decision row), so a
+ *    plain first-N cap systematically drops the TAIL sections — exactly where
+ *    mx5 keeps its testing obligations;
+ *  - "given order" as the tie-break re-creates the same tail bias one level up
+ *    (mx5 run 16, measured live: the model emitted 185 requirements, 178
+ *    grounded — INCLUDING §9's "serves `/api` + static `dist/`", the clause
+ *    whose loss shipped a permanently blank app — and the cap's doc-order fill
+ *    cut all 138 past the cap, every one from the design's tail).
+ * Rule (deterministic priority, not a knob): entries quoting an obligation-
+ * marked passage survive first; the remaining budget is filled ROUND-ROBIN
+ * across the source doc's sections (each section's entries in doc order), so
+ * every section keeps its head obligations and no section is wholesale dropped.
+ * Bucketing is by the quote's POSITION in the source doc — grounded substring,
+ * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
+ * cannot be located) the fill degrades to the old given-order behavior.
  */
-export function capRequirements(entries, passages) {
+export function capRequirements(entries, passages, sourceDoc) {
     if (entries.length <= MAX_REQUIREMENTS)
         return entries;
     const norms = passages.map(normalise);
@@ -96,7 +108,73 @@ export function capRequirements(entries, passages) {
     };
     const marked = entries.filter(covers);
     const rest = entries.filter(e => !covers(e));
-    return [...marked, ...rest].slice(0, MAX_REQUIREMENTS);
+    const budget = MAX_REQUIREMENTS - Math.min(marked.length, MAX_REQUIREMENTS);
+    return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(rest, budget, sourceDoc)];
+}
+/** The doc split into heading-delimited sections, each pre-normalised for
+ *  containment tests. Text before the first heading is its own section. */
+function normalisedSections(doc) {
+    const out = [];
+    let current = [];
+    for (const line of doc.replace(/\r\n?/g, '\n').split('\n')) {
+        if (/^#{1,6}\s+\S/.test(line)) {
+            if (current.length > 0)
+                out.push(normalise(current.join('\n')));
+            current = [line];
+            continue;
+        }
+        current.push(line);
+    }
+    if (current.length > 0)
+        out.push(normalise(current.join('\n')));
+    return out.filter(s => s.length > 0);
+}
+/** Round-robin fill across doc sections: bucket each entry by the FIRST section
+ *  whose normalised text contains its quote (the same containment rule that
+ *  grounded it), take each bucket's entries in in-section order, one per bucket
+ *  per round. Entries that cannot be located (or no doc) go to a trailing
+ *  bucket in given order — the pre-run-16 behavior, never worse. */
+function sectionFairFill(entries, budget, sourceDoc) {
+    if (budget <= 0)
+        return [];
+    if (!sourceDoc)
+        return entries.slice(0, budget);
+    const sections = normalisedSections(sourceDoc);
+    const buckets = new Map();
+    entries.forEach((e, given) => {
+        const q = normalise(e.quote);
+        let b = sections.findIndex(s => s.includes(q));
+        let at;
+        if (b < 0) {
+            b = sections.length; // unlocatable → trailing bucket, given order
+            at = given;
+        }
+        else {
+            at = sections[b].indexOf(q);
+        }
+        const list = buckets.get(b) ?? [];
+        list.push({ e, at });
+        buckets.set(b, list);
+    });
+    const ordered = [...buckets.keys()].sort((a, b) => a - b);
+    for (const k of ordered)
+        buckets.get(k).sort((a, b) => a.at - b.at);
+    const out = [];
+    for (let round = 0; out.length < budget; round++) {
+        let took = false;
+        for (const k of ordered) {
+            const list = buckets.get(k);
+            if (round >= list.length)
+                continue;
+            out.push(list[round].e);
+            took = true;
+            if (out.length >= budget)
+                break;
+        }
+        if (!took)
+            break;
+    }
+    return out;
 }
 /**
  * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
@@ -392,6 +470,109 @@ export function buildRequirementsBlock(requirements) {
         ''
     ].join('\n');
 }
+// ─── Owned (task-mapped) requirements — the run-16 channel gap ──────────────
+//
+// Of run 16's 40 kept requirements only the 6 CROSS-CUTTING ones were persisted
+// and injected; the 33 TASK-MAPPED ones rode the decompose ledger (shaping the
+// title list) and then vanished — nothing ever showed a task its OWN mapped
+// obligations. TASK_0008's refine read §9's "serves `/api` + static `dist/`",
+// quoted it in a grill question, and still narrowed the composed spec to
+// "SPA fallback serves index.html"; the shipped server never served the client
+// bundle and the app was permanently blank. An obligation the coverage map
+// assigned to a task must travel INTO that task as verbatim authoritative text,
+// exactly like the cross-cutting channel that measurably works.
+const OWNED_REQUIREMENTS_FILE = 'requirements-owned.md';
+export function ownedRequirementsFile(cwd) {
+    return path.join(tasksDir(cwd), OWNED_REQUIREMENTS_FILE);
+}
+/** Persist the task-mapped requirements (host-side, plan time). Overwrites —
+ *  the mapping is recomputed whole per plan round. Best-effort like the carried
+ *  artifact. */
+export async function writeOwnedRequirements(cwd, owned) {
+    try {
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        const lines = owned.map(o => `OWNED: "${o.quote}"${o.anchor ? ` [anchor: ${o.anchor}]` : ''} [title: ${o.title.replace(/\n/g, ' ')}]`);
+        await fsp.writeFile(ownedRequirementsFile(cwd), lines.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort artifact
+    }
+}
+export async function readOwnedRequirements(cwd) {
+    try {
+        return parseOwnedRequirements(await fsp.readFile(ownedRequirementsFile(cwd), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+export function parseOwnedRequirements(text) {
+    const out = [];
+    for (const m of text.matchAll(/^OWNED:\s*"([^"\n]+)"(?:\s*\[anchor:\s*([^\]]*)\])?\s*\[title:\s*([^\n]+)\]\s*$/gim)) {
+        out.push({
+            quote: m[1].trim(),
+            anchor: (m[2] ?? '').trim(),
+            title: m[3].replace(/\]\s*$/, '').trim()
+        });
+    }
+    return out;
+}
+/** The owned entries whose plan title matches THIS task's title (normalised
+ *  equality — titles travel verbatim from the plan list into task creation;
+ *  spliced repair tasks simply match nothing). */
+export function ownedForTitle(owned, title) {
+    const t = normalise(title);
+    if (t.length === 0)
+        return [];
+    return owned.filter(o => normalise(o.title) === t);
+}
+/** The injection block for a task's OWN mapped obligations. Mirrors
+ *  buildRequirementsBlock (the directive pattern that measurably works) but is
+ *  singular in address: these are not "wherever they touch", they ARE this
+ *  task's obligations and must survive into the spec. */
+export function buildOwnedRequirementsBlock(owned) {
+    if (owned.length === 0)
+        return '';
+    return [
+        "THIS TASK'S OWN REQUIREMENTS — obligations the SOURCE design states for exactly this",
+        "task's slice (verbatim quotes; AUTHORITATIVE — the design outranks any narrower",
+        'restatement, including the refined prompt above):',
+        ...owned.map(o => `- "${o.quote}"${o.anchor ? ` [anchor: ${o.anchor}]` : ''}`),
+        'Every entry must be SATISFIED BY THIS TASK and must appear in the spec: state it (or',
+        'its concrete consequence) under CONSTRAINTS or ACCEPTANCE, and make VERIFY exercise',
+        'it where runnable. Never weaken an entry to a narrower behavior — if the quote says',
+        'more than the refined prompt, the quote wins.',
+        ''
+    ].join('\n');
+}
+/**
+ * BRACES for the owned channel (the PROMPT-1 pattern): deterministically append
+ * each owned obligation the composed spec does not already carry as a
+ * CONSTRAINTS bullet. Measured need (scripts/live-owned-requirement-compose-ab
+ * .ts, 8 reps/arm on two real run-16 losses): with the belt block alone compose
+ * folded the clause into CONSTRAINTS/ACCEPTANCE in only 2/8 reps per fixture
+ * (baseline 0/8) — an instruction the model mostly ignores, the PROMPT-4 shape.
+ * A host-side append cannot be ignored. "Already carries" = the normalised
+ * quote appears anywhere in the spec — belt-obeying reps aren't double-stated.
+ * No CONSTRAINTS section (shape-invalid spec) → returned unchanged; this runs
+ * only on specs the shape gate already accepted.
+ */
+export function appendOwnedConstraints(spec, owned) {
+    if (owned.length === 0)
+        return spec;
+    const m = /^CONSTRAINTS[ \t]*$/m.exec(spec);
+    if (!m)
+        return spec;
+    const already = normalise(spec);
+    const missing = owned.filter(o => !already.includes(normalise(o.quote)));
+    if (missing.length === 0)
+        return spec;
+    const insertAt = m.index + m[0].length;
+    const bullets = missing
+        .map(o => `  - "${o.quote}"${o.anchor ? ` [${o.anchor}]` : ''} — owned requirement from the source design (AUTHORITATIVE; satisfy it in this task, do not narrow it)`)
+        .join('\n');
+    return `${spec.slice(0, insertAt)}\n${bullets}${spec.slice(insertAt)}`;
+}
 /** The decompose-prompt ledger block (goal E's belt): the grounded requirement
  *  list rides into decompose so structure-mirroring can't discharge it. */
 export function buildRequirementsLedger(requirements) {

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

@@ -0,0 +1,28 @@
+export interface ResolvedRunner {
+    /** Spawnable form: the bare name when PATH serves it, else an absolute path. */
+    bin: string;
+    /** Directory to prepend to PATH for the spawned script chain; null when the
+     *  bare name already resolves (nothing to add). */
+    pathPrefix: string | null;
+    /** false → the runner is not spawnable anywhere this module knows to look. */
+    ok: boolean;
+}
+/** Test hook: resolution is cached per bin name for the life of the process (the
+ *  gate spawns the same runner many times); tests reset between cases. */
+export declare function clearRunnerCache(): void;
+/**
+ * A spawnable form of `bin`: bare name if PATH serves it, else the first
+ * well-known location that exists AND runs, else `{ok: false}` with the bare
+ * name unchanged (spawn sites then behave exactly as before this module —
+ * ENOENT → the caller's env-gap contract).
+ */
+export declare function resolveRunner(bin: string, opts?: {
+    probe?: (bin: string) => boolean;
+    env?: NodeJS.ProcessEnv;
+}): ResolvedRunner;
+/**
+ * The env a spawn site should pass so the resolved runner's script chain can
+ * re-invoke it: base env with the runner's directory prepended to PATH. With no
+ * prefix (bare name resolved, or unresolvable) the base env is returned as-is.
+ */
+export declare function runnerEnv(runner: ResolvedRunner, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/task/runner-resolve.js

@@ -0,0 +1,95 @@
+/**
+ * runner-resolve — make the deterministic gates able to SPAWN the project's own
+ * runner when the host PATH lost it.
+ *
+ * The failure this closes (mx5 run 16, validated): pi was launched inside the
+ * sandbox through a LOGIN shell, whose /etc/profile reset PATH and dropped
+ * ~/.bun/bin — so `bun` was unspawnable in every gate spawn. Under the env-gap
+ * contract (ENOENT / exit 127 → skip, deliberately, so a missing tool is never a
+ * code fault) EVERY dynamic check silently skipped: bun test, the boot of
+ * `bun run dev`, and therefore the render check built for exactly the blank-page
+ * class the run shipped. The gate converged on static checks alone and stamped
+ * the run green while the binary sat at ~/.bun/bin/bun the whole time.
+ *
+ * Resolution is discovery, never installation: try the bare name first (PATH
+ * serves it → nothing changes), then probe well-known install locations. Each
+ * probe is a real `<candidate> --version` spawn — an existing but broken binary
+ * must not count as resolved.
+ *
+ * The PATH PREFIX matters as much as the binary: a resolved `bun run test` still
+ * re-invokes `bun` (and the repo's own bins) INSIDE the script chain, and those
+ * inner calls exit 127 without the runner's directory on PATH — the same silent
+ * blindness one level down (run 16's final-fix child hit exactly this and had to
+ * hand-export PATH). Spawn sites must therefore use runnerEnv(), not just the
+ * resolved binary.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Well-known install locations per runner, probed in order AFTER the bare name.
+ *  Only ever read — nothing is installed. */
+function candidatePaths(bin, env) {
+    const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
+    const exe = process.platform === 'win32' ? `${bin}.exe` : bin;
+    const list = [];
+    if (bin === 'bun') {
+        if (env.BUN_INSTALL)
+            list.push(path.join(env.BUN_INSTALL, 'bin', exe));
+        list.push(path.join(home, '.bun', 'bin', exe));
+    }
+    list.push(path.join(home, '.local', 'bin', exe), path.join('/usr/local/bin', exe), path.join('/usr/bin', exe), path.join('/opt/homebrew/bin', exe));
+    return list;
+}
+/** Does `bin` actually run? A real spawn, not an existence check — a present but
+ *  broken binary (wrong arch, dangling symlink) must not count as resolved. */
+function defaultProbe(bin) {
+    const r = spawnSync(bin, ['--version'], {
+        encoding: 'utf8',
+        timeout: 8_000,
+        env: { ...process.env }
+    });
+    return !r.error && r.status === 0;
+}
+const cache = new Map();
+/** Test hook: resolution is cached per bin name for the life of the process (the
+ *  gate spawns the same runner many times); tests reset between cases. */
+export function clearRunnerCache() {
+    cache.clear();
+}
+/**
+ * A spawnable form of `bin`: bare name if PATH serves it, else the first
+ * well-known location that exists AND runs, else `{ok: false}` with the bare
+ * name unchanged (spawn sites then behave exactly as before this module —
+ * ENOENT → the caller's env-gap contract).
+ */
+export function resolveRunner(bin, opts = {}) {
+    const cached = cache.get(bin);
+    if (cached)
+        return cached;
+    const probe = opts.probe ?? defaultProbe;
+    const env = opts.env ?? process.env;
+    let resolved;
+    if (probe(bin)) {
+        resolved = { bin, pathPrefix: null, ok: true };
+    }
+    else {
+        const hit = candidatePaths(bin, env).find(p => existsSync(p) && probe(p));
+        resolved =
+            hit ?
+                { bin: hit, pathPrefix: path.dirname(hit), ok: true }
+                : { bin, pathPrefix: null, ok: false };
+    }
+    cache.set(bin, resolved);
+    return resolved;
+}
+/**
+ * The env a spawn site should pass so the resolved runner's script chain can
+ * re-invoke it: base env with the runner's directory prepended to PATH. With no
+ * prefix (bare name resolved, or unresolvable) the base env is returned as-is.
+ */
+export function runnerEnv(runner, base = process.env) {
+    if (!runner.pathPrefix)
+        return { ...base };
+    return { ...base, PATH: `${runner.pathPrefix}${path.delimiter}${base.PATH ?? ''}` };
+}

package/package.json

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