@mjasnikovs/pi-task 0.18.24 → 0.18.26

package/dist/task/auto-orchestrator.js

@@ -5,6 +5,7 @@
  * This module currently holds the planning half (AutoDeps + planAuto). The run
  * loop, command handlers, and defaultDeps are added by the next task.
  */
+import { existsSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { gateRunTask, markResumable } from './orchestrator.js';
@@ -35,6 +36,7 @@ import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, app
 import { reconcileTitleSources } from './decompose-fidelity.js';
 import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, 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';
 // Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
 // when the model emits NONE), but a model that never says NONE would otherwise
@@ -493,6 +495,25 @@ export async function planAuto(ctx, cwd, feature, deps) {
     catch {
         // best-effort channel
     }
+    // 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
     const decomposePrompt = AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications, buildRequirementsLedger(reqEntries));
     // Parse + FIDELITY RECONCILIATION (mx5 run 11, goal B): ground each title's
@@ -589,6 +610,13 @@ export async function planAuto(ctx, cwd, feature, deps) {
             }
         }
         const missing = [...verdictMissing, ...(acc?.unmapped ?? []).map(e => `"${e.quote}"`)];
+        // Unclaimed dangling artifacts are unowned areas: they force a coverage
+        // round that assigns a producing task, and clear as soon as a title
+        // names the file.
+        for (const d of specDangling) {
+            if (!titlesCoverArtifact(titles, d))
+                missing.push(danglingMissingText(d));
+        }
         return {
             plan: { titles, covered, missing },
             accounting: acc,
@@ -707,12 +735,23 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const carriedCrossCutting = accounting?.crossCutting ?? [];
     const carriedUnmapped = accounting?.unmapped ?? [];
     const carriedJudge = best.judgeMissing;
-    if (carriedCrossCutting.length > 0 || carriedUnmapped.length > 0 || carriedJudge.length > 0) {
-        await appendCarriedRequirements(cwd, carriedCrossCutting, carriedUnmapped, carriedJudge);
+    // Dangling artifacts still unclaimed by any title of the SHIPPING plan are a
+    // fourth channel: the producing obligation travels verbatim into every task
+    // (whichever task builds the referencing side must also produce the file),
+    // and the final gate re-checks the shipped tree regardless.
+    const carriedDangling = specDangling
+        .filter(d => !titlesCoverArtifact(planTitles, d))
+        .map(danglingCarryText);
+    if (carriedCrossCutting.length > 0
+        || carriedUnmapped.length > 0
+        || carriedJudge.length > 0
+        || carriedDangling.length > 0) {
+        await appendCarriedRequirements(cwd, carriedCrossCutting, carriedUnmapped, carriedJudge, carriedDangling);
         const parts = [
             carriedCrossCutting.length > 0 ? `${carriedCrossCutting.length} cross-cutting` : '',
             carriedUnmapped.length > 0 ? `${carriedUnmapped.length} unowned` : '',
-            carriedJudge.length > 0 ? `${carriedJudge.length} judge-flagged` : ''
+            carriedJudge.length > 0 ? `${carriedJudge.length} judge-flagged` : '',
+            carriedDangling.length > 0 ? `${carriedDangling.length} dangling-artifact` : ''
         ].filter(p => p.length > 0);
         ctx.ui.notify(`/task-auto: carrying ${parts.join(', ')} requirement(s) into every task`
             + ' — see .pi-tasks/requirements.md.', 'info');

package/dist/task/command-watchdog.d.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * Command watchdog — cancels a single tool execution that overruns the
+ * configured ceiling and reminds the model to bound its own commands.
+ *
+ * WHY: a local model in the MAIN session routinely runs a command that never
+ * returns — `godot --headless --check-only` with no timeout, a dev server, a
+ * hung test — and the run wedges until the user manually aborts and tells the
+ * model to add a timeout. pi's bash tool takes an OPTIONAL `timeout` with NO
+ * default (see pi-coding-agent tools/bash.js), so any command the model didn't
+ * bound runs forever. This supplies the missing default from the host side.
+ *
+ * HOW: arm a wall-clock timer on `tool_execution_start`, disarm it on
+ * `tool_execution_end`. If it elapses, `ctx.abort()` cancels the in-flight
+ * operation — which fires the tool's AbortSignal, and pi's bash executor kills
+ * the whole process tree on abort — then a follow-up user turn tells the model
+ * what happened so it retries with a timeout instead of hanging again.
+ *
+ * Tool-agnostic: it arms on ANY tool, honouring "any command can run forever",
+ * though in practice only bash runs long enough to trip it. The pure timer
+ * state lives in {@link CommandWatchdog}; all side effects (abort, reminder,
+ * per-call ctx lookup) live in the registration's `onFire`, so the machine is
+ * unit-testable without a real pi session.
+ */
+/** Opaque timer handle — a real `setTimeout` return in production, anything the
+ *  test's fake scheduler hands back under test. */
+export type TimerHandle = unknown;
+export interface WatchdogDeps {
+    /**
+     * The ceiling in ms, read PER command-start so a /task-config change takes
+     * effect on the next command with no reload. 0 (or any non-positive value)
+     * means the watchdog is off and never arms.
+     */
+    getTimeoutMs: () => number;
+    schedule: (fn: () => void, ms: number) => TimerHandle;
+    cancel: (handle: TimerHandle) => void;
+    /** Invoked when a command overruns: the registration aborts + reminds here. */
+    onFire: (toolCallId: string, toolName: string, timeoutMs: number) => void;
+}
+/**
+ * The reminder delivered to the model after its command is cancelled. Kept pure
+ * and exported so a test can assert its shape without driving the whole session.
+ */
+export declare function reminderMessage(toolName: string, timeoutMs: number): string;
+export declare class CommandWatchdog {
+    private readonly deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    private readonly active;
+    constructor(deps: WatchdogDeps);
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId: string, toolName: string): void;
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId: string): void;
+    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
+     *  stray timer can fire into a later, unrelated command. */
+    clearAll(): void;
+    private disarm;
+    private fire;
+}
+/**
+ * Wire the watchdog into the main session. Only ever active in the host session
+ * (children run `--no-extensions`), which is exactly where the observed hangs
+ * happen.
+ */
+export declare function registerCommandWatchdog(pi: ExtensionAPI): void;

package/dist/task/command-watchdog.js

@@ -0,0 +1,114 @@
+import { getConfig } from '../config/config.js';
+/**
+ * The reminder delivered to the model after its command is cancelled. Kept pure
+ * and exported so a test can assert its shape without driving the whole session.
+ */
+export function reminderMessage(toolName, timeoutMs) {
+    const mins = Math.max(1, Math.round(timeoutMs / 60_000));
+    return (`[SYSTEM] Your \`${toolName}\` call ran longer than ${mins} minute`
+        + `${mins === 1 ? '' : 's'} and was automatically cancelled — it looked stuck. `
+        // Anti-fabrication: a live run showed the model react to the cancel by
+        // reporting the killed command as succeeded ("the server is now running").
+        // State plainly that it produced nothing so the model can't claim success.
+        + `The command was killed before it finished and produced NO result, so do not `
+        + `report it as completed or successful, and do not claim that anything it would `
+        + `have started (a server, build, or process) is now running. `
+        + `If it was a genuinely long-running command, you MUST re-run it with an explicit `
+        + `timeout — set the bash tool's \`timeout\` parameter (in seconds) so it cannot hang `
+        + `again — or break it into smaller steps. Do NOT simply retry the same unbounded command.`);
+}
+export class CommandWatchdog {
+    deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    active = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId, toolName) {
+        const ms = this.deps.getTimeoutMs();
+        if (!(ms > 0))
+            return;
+        // A duplicate start for the same id must not leak the previous timer.
+        this.disarm(toolCallId);
+        const handle = this.deps.schedule(() => this.fire(toolCallId, toolName, ms), ms);
+        this.active.set(toolCallId, handle);
+    }
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId) {
+        this.disarm(toolCallId);
+    }
+    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
+     *  stray timer can fire into a later, unrelated command. */
+    clearAll() {
+        for (const handle of this.active.values())
+            this.deps.cancel(handle);
+        this.active.clear();
+    }
+    disarm(toolCallId) {
+        const handle = this.active.get(toolCallId);
+        if (handle !== undefined) {
+            this.deps.cancel(handle);
+            this.active.delete(toolCallId);
+        }
+    }
+    fire(toolCallId, toolName, ms) {
+        // If the tool ended in the same tick the timer fired, its entry is gone
+        // already — never abort a command that has just finished cleanly.
+        if (!this.active.has(toolCallId))
+            return;
+        this.active.delete(toolCallId);
+        this.deps.onFire(toolCallId, toolName, ms);
+    }
+}
+/**
+ * Wire the watchdog into the main session. Only ever active in the host session
+ * (children run `--no-extensions`), which is exactly where the observed hangs
+ * happen.
+ */
+export function registerCommandWatchdog(pi) {
+    // The ctx that owns each in-flight tool's AbortSignal, captured per start so
+    // the timer callback (which fires outside the event handler) aborts the
+    // right operation.
+    const ctxByCall = new Map();
+    const watchdog = new CommandWatchdog({
+        getTimeoutMs: () => getConfig().requestTimeoutMs,
+        schedule: (fn, ms) => {
+            const handle = setTimeout(fn, ms);
+            // Don't let a pending watchdog timer keep the process alive on exit.
+            if (typeof handle.unref === 'function') {
+                ;
+                handle.unref();
+            }
+            return handle;
+        },
+        cancel: handle => clearTimeout(handle),
+        onFire: (toolCallId, toolName, timeoutMs) => {
+            const ctx = ctxByCall.get(toolCallId);
+            ctxByCall.delete(toolCallId);
+            // Cancel the stuck command (kills the tool's whole process tree via
+            // the turn's AbortSignal), then start a fresh turn telling the model
+            // to bound its next attempt.
+            ctx?.abort();
+            pi.sendUserMessage(reminderMessage(toolName, timeoutMs), { deliverAs: 'followUp' });
+        }
+    });
+    pi.on('tool_execution_start', (event, ctx) => {
+        ctxByCall.set(event.toolCallId, ctx);
+        watchdog.onStart(event.toolCallId, event.toolName);
+    });
+    pi.on('tool_execution_end', event => {
+        ctxByCall.delete(event.toolCallId);
+        watchdog.onEnd(event.toolCallId);
+    });
+    // Safety net: nothing should outlive its turn, but if a start ever lacks a
+    // matching end, clear on turn/session teardown so no timer fires stale.
+    const reset = () => {
+        watchdog.clearAll();
+        ctxByCall.clear();
+    };
+    pi.on('turn_end', reset);
+    pi.on('session_shutdown', reset);
+}

package/dist/task/final-gate.js

@@ -47,6 +47,7 @@ import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts }
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
 import { taskThatIntroduced } from './task-provenance.js';
+import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -382,6 +383,12 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env }
         });
+        // Best-effort cleanup only: killGroup below can silently fail to reap the
+        // process (platform/sandbox-specific — observed on a GH Actions Linux
+        // runner where the group-kill did not take, hanging the whole `bun test
+        // --isolate` run on the leaked child's piped stdio). unref() so a child
+        // we already tried to kill can never itself keep this process alive.
+        child.unref();
         let out = '';
         let err = '';
         let listenerSeen = false;
@@ -772,6 +779,21 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
                 warnings.push(b.renderNote);
         }
     }
+    // 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 +
+    // main.js, so every non-API GET 404'd behind 32/32 green checkoffs.
+    // Deterministic scan of the shipped tree (literal refs only, positive
+    // producer evidence required — see artifact-closure.ts); each dangle is a
+    // ranked failure naming referencer + missing path. Rank 0: "the app cannot
+    // serve what it references" is the same load-bearing class as boot/render.
+    try {
+        for (const d of findDanglingArtifacts(cwd))
+            fail(danglingGateFailureText(d), 0);
+    }
+    catch {
+        // best-effort scan — a scanner fault must never break the gate
+    }
     if (failures.length > 0) {
         // Stable sort: boot/render (rank 0) leads, everything else keeps execution
         // order. One failure keeps the exact single-failure wording; several become

package/dist/task/requirements.d.ts

@@ -88,8 +88,13 @@ export declare function readRequirements(cwd: string): Promise<string>;
  *     was warned-about then dropped). These are plain strings, not quotes of the
  *     source; marked distinctly so a task can tell an inferred area from a verbatim
  *     obligation.
+ *   • `danglingArtifacts` — runtime files the spec references but nothing
+ *     produces (mx5 run 13: the served `index.html` no task, tree entry, or
+ *     build output ever created), still unclaimed by any title at coverage
+ *     exhaustion. Deterministically extracted (artifact-closure.ts), so like
+ *     judge areas they are host-authored strings, not source quotes.
  */
-export declare function appendCarriedRequirements(cwd: string, crossCutting: RequirementEntry[], unresolved?: RequirementEntry[], judgeFlagged?: string[]): Promise<void>;
+export declare function appendCarriedRequirements(cwd: string, crossCutting: RequirementEntry[], unresolved?: RequirementEntry[], judgeFlagged?: string[], danglingArtifacts?: string[]): Promise<void>;
 /**
  * The read-only block refine/compose receive when carried requirements exist.
  * Verbatim content travels with every task (the directive pattern that works),

package/dist/task/requirements.js

@@ -320,10 +320,19 @@ function formatEntry(e, marker) {
  *     was warned-about then dropped). These are plain strings, not quotes of the
  *     source; marked distinctly so a task can tell an inferred area from a verbatim
  *     obligation.
+ *   • `danglingArtifacts` — runtime files the spec references but nothing
+ *     produces (mx5 run 13: the served `index.html` no task, tree entry, or
+ *     build output ever created), still unclaimed by any title at coverage
+ *     exhaustion. Deterministically extracted (artifact-closure.ts), so like
+ *     judge areas they are host-authored strings, not source quotes.
  */
-export async function appendCarriedRequirements(cwd, crossCutting, unresolved = [], judgeFlagged = []) {
-    if (crossCutting.length === 0 && unresolved.length === 0 && judgeFlagged.length === 0)
+export async function appendCarriedRequirements(cwd, crossCutting, unresolved = [], judgeFlagged = [], danglingArtifacts = []) {
+    if (crossCutting.length === 0
+        && unresolved.length === 0
+        && judgeFlagged.length === 0
+        && danglingArtifacts.length === 0) {
         return;
+    }
     try {
         const existing = (await readRequirements(cwd)).split('\n').filter(l => l.trim().length > 0);
         const seen = new Set(existing.map(l => {
@@ -337,6 +346,10 @@ export async function appendCarriedRequirements(cwd, crossCutting, unresolved =
             [
                 judgeFlagged.map(q => ({ quote: q, anchor: '' })),
                 'judge-flagged uncovered area, no task owns this — surfaced at plan time'
+            ],
+            [
+                danglingArtifacts.map(q => ({ quote: q, anchor: '' })),
+                'dangling runtime artifact, nothing produces it — surfaced at plan time'
             ]
         ]) {
             for (const e of entries) {

package/package.json

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