@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/shared/stream-watchdog.js

@@ -2,25 +2,30 @@
  * Model-stream watchdog — the inactivity machine for a stream that goes SILENT
  * without erroring.
  *
- * WHY (mx5 run 14): three main-session implementation turns died mid-turn — the
- * session jsonl's last event is an ordinary assistant message, then nothing,
- * forever, while the model server stayed Up(healthy) the whole time. A hung or
- * silently-dropped stream throws NOTHING, so:
- *   - the connection-error retry (child-runner.ts) never fires: it needs a
- *     thrown/reported ModelError,
- *   - the command watchdog never fires: it only covers TOOL executions,
- *   - the child stall guard never fires: it treats a reachable endpoint as proof
- *     of life, which it is — the endpoint was fine, the stream was not.
- * Cost in run 14: ~2.9h of dead air awaiting manual restarts.
+ * WHY: a turn can die mid-stream — the last thing recorded is an ordinary
+ * assistant message, then nothing, while the model server stays healthy. A hung
+ * or silently-dropped stream throws NOTHING, so none of the three guards that
+ * already exist can see it:
+ *   - the connection-error retry never fires. child-runner reaches it only
+ *     inside `if (r.modelError)`, and a silent hang reports no error at all.
+ *   - the command watchdog never fires: it arms per tool call and covers only
+ *     TOOL executions.
+ *   - the child stall guard never fires: it kills only when a probe finds the
+ *     endpoint UNREACHABLE, and here the endpoint answers fine. The stream is
+ *     what died, not the server.
  *
- * WHAT THIS MEASURES: time since the LAST stream event of ANY kind — text token,
- * tool-call delta, thinking delta, provider response header. NOT wall-clock, and
- * NOT "time to first token". One token every 30s is a working local model and
- * must never be killed; zero events for the whole window is a hang.
+ * WHAT THIS MEASURES: time since the last sign of life, NOT wall-clock and NOT
+ * time-to-first-token. What counts as a sign differs by surface — for the main
+ * session it is any of six pi events (`before_provider_request`,
+ * `after_provider_response`, `turn_start`, `message_start`, `message_update`,
+ * `message_end`), with every text, thinking and tool-call delta arriving as
+ * `message_update`; for a child it is any stdout or stderr CHUNK. A slow model
+ * that emits something occasionally is working and must never be killed. Zero
+ * for the whole window is a hang.
  *
- * WHY THE DEFAULT IS GENEROUS: on a local llama-server a 32k-context prompt can
- * spend many minutes in prompt processing emitting nothing at all. A 60-120s
- * ceiling would kill every long prompt on local hardware. See
+ * WHY THE DEFAULT IS GENEROUS: prompt processing legitimately emits nothing
+ * while it runs, so a tight ceiling would kill honest long prompts. This guard
+ * exists to bound dead air, not to police slowness. See
  * DEFAULT_STREAM_INACTIVITY_MS.
  *
  * TWO SURFACES, one machine (same split as command-watchdog.ts):
@@ -36,20 +41,25 @@
  *                  blind re-send of a half-executed turn).
  */
 /**
- * Default inactivity ceiling: 10 minutes. Chosen from the constraint that a local
- * model's first token can legitimately be many minutes away — the guard exists to
- * turn hours of dead air into minutes, not to police slowness.
+ * Default inactivity ceiling. Sized by the constraint that a local model's first
+ * token can legitimately be a long way off, so the number has to clear honest
+ * prompt processing rather than sit close to it.
  */
 export const DEFAULT_STREAM_INACTIVITY_MS = 10 * 60_000;
-/** Whole minutes, floored at 1, for the human-facing window in every message. */
+/** Whole minutes for the human-facing window in every message: rounded to
+ *  nearest, then floored at 1 so a sub-minute window never reads "0 minutes". */
 function minutes(ms) {
     const mins = Math.max(1, Math.round(ms / 60_000));
     return `${mins} minute${mins === 1 ? '' : 's'}`;
 }
 /**
- * How often the machine checks the idle clock. A poll (rather than re-arming a
- * timeout on every token) keeps cost O(1) per window instead of O(1) per token —
- * a streaming turn emits thousands of events. Same idiom as the child stall guard.
+ * How often the machine checks the idle clock. A poll, rather than re-arming a
+ * timeout on every token, keeps the cost per window constant instead of per
+ * event — and "thousands of events" is not a figure of speech: one captured turn
+ * emitted over two thousand, nearly all of them `message_update`.
+ *
+ * A quarter of the window, clamped: never tighter than 50ms, never looser than
+ * 30s. The child stall guard polls with the same shape and its own divisor.
  */
 export function pollIntervalMs(timeoutMs) {
     return Math.max(50, Math.min(Math.floor(timeoutMs / 4), 30_000));
@@ -64,12 +74,14 @@ export class StreamWatchdog {
      * legitimately idle, and that window belongs to the command watchdog, not to
      * this one — without it a 10-minute build looks identical to a hung stream.
      *
-     * A SET, not a boolean: pi runs a tool batch in parallel (agent-loop.js
-     * `executeToolCallsParallel` emits every tool_execution_start up front, then one
-     * end per call as each settles, and answers an immediate call inline while an
-     * earlier one is still running). A boolean would be cleared by the FIRST end and
-     * leave the still-running sibling — the long build — exposed to a false fire.
-     * Same per-toolCallId idiom the command watchdog uses.
+     * A SET, not a boolean, and pi's own loop is why. `executeToolCallsParallel`
+     * in agent-loop.js emits EVERY `tool_execution_start` up front, before any
+     * call is prepared; a call that prepares "immediate" gets its end emitted
+     * inline right there, while the rest are deferred as closures and settle
+     * through a `Promise.all`. So an end can arrive while earlier siblings are
+     * still running. A boolean would be cleared by that first end and leave the
+     * long build exposed to a false fire. Same per-toolCallId idiom the command
+     * watchdog uses.
      */
     active = new Set();
     /** Nesting depth for callers that cannot supply an id, counted so an unkeyed
@@ -152,18 +164,20 @@ export class StreamWatchdog {
  * cancels it on stop/fire, and runChild's cleanup() stops the watchdog on every
  * settle path (close, error, abort), so it cannot outlive the child it watches.
  *
- * The poll is REF'd, deliberately. It used to be unref'd, on the reasoning that a
- * pending watchdog poll should never keep the process alive at exit — but under
- * Bun on WINDOWS an unref'd timer does not fire at all once nothing ref'd is
- * pending. Measured on a windows-latest runner (bun 1.3.14): an unref'd interval
- * with nothing else pending never fired in 20s, while the identical ref'd one
- * fired at 101ms; on linux both fire at 100ms.
+ * The poll is REF'd, deliberately. Unref'd reads better — a pending watchdog poll
+ * should never keep the process alive at exit — but an unref'd timer is only
+ * guaranteed to fire while something ref'd is still pending, and that guarantee
+ * is not the platform-independent thing it looks like.
+ *
+ * Measured here, on both runtimes: with nothing else pending an unref'd timer
+ * never fires at all, the process just exits; with a spawned child holding its
+ * stdout and stderr pipes open it fires on schedule throughout. A silent child
+ * is the SECOND case — its pipes are still ref'd work — so on this platform the
+ * unref would not have broken the child guard. The reason to keep it ref'd is
+ * that this machine also runs in the main session, where no such handle is
+ * guaranteed, and the failure mode is silent: a watchdog that never fires looks
+ * exactly like a stream that never hung.
  *
- * That state — no ref'd work outstanding — is EXACTLY the state this watchdog
- * exists to police: a child whose model stream has gone silent. So the unref
- * disabled the guard precisely when it was needed, and every stream-stall
- * integration test hung forever on windows (CI runs 30476786365, 30477802633,
- * 30478455402 — it hangs at v0.24.1 too, so this predates that release).
  * A poll that can delay exit by one interval is the cheaper failure.
  */
 export const realStreamTimerDeps = {
@@ -173,10 +187,13 @@ export const realStreamTimerDeps = {
 };
 /**
  * The cause string a CHILD's stream stall is reported as. Phrased so
- * {@link isConnectionError} (child-runner.ts) matches it — the whole point is to
- * route a silent hang into the retry path that already exists for a LOUD
- * connection failure, rather than inventing a second one. Honest about who
- * killed it: pi-task aborted the request, the provider did not report anything.
+ * {@link isConnectionError} (child-runner.ts) matches it — checked by running the
+ * round-trip, and it does. The whole point is to route a silent hang into the
+ * retry path that already exists for a LOUD connection failure rather than
+ * inventing a second one, so the phrase "connection lost" is load-bearing, not
+ * decoration: reword it past that predicate and stream stalls stop retrying.
+ * Honest about who killed it, too — pi-task aborted the request, the provider
+ * reported nothing.
  */
 export function streamStallCause(idleMs) {
     return (`model stream inactivity: no stream events for ${minutes(idleMs)} — `

package/dist/task/accept-debt.d.ts

@@ -3,19 +3,17 @@ import { type CommandRunner } from './command-run.js';
  * Provenance of a recorded defect:
  *   - 'accepted'       — the user chose ACCEPT despite a verify-FAIL (the original class).
  *   - 'enforce-revert' — an enforce-pass re-verify FAILED and the enforce edits were
- *     reverted; the FAIL indicted the ORIGINAL work (mx5 run 10 TASK_0004: "Missing
- *     server entry point … the Hono server cannot be started"), so the terminal defect
+ *     reverted, but the FAIL indicted the ORIGINAL work, so the terminal defect
  *     was FOUND and then erased by the very mechanism that found it. Persisted here so
  *     the final gate re-checks and surfaces it instead of letting it die with the revert.
  *   - 'enforce-kept'   — the same enforce re-verify FAIL, but the failing check named
  *     only files the ENFORCE COMMIT does not touch, so reverting that commit could not
- *     possibly repair it (mx5 run 18 TASK_0024: a one-line paren removal in `Admin.tsx`
- *     was reverted over a `MyListings.spec.tsx` CT failure it cannot reach, and the
- *     final gate re-made the identical change 5 minutes later). The edits are KEPT and
+ *     possibly repair it — reverting a change in one file over a failure in a file
+ *     it cannot reach only loses the change. The edits are KEPT and
  *     the defect is recorded here — keeping the work must never mean losing the finding.
  *   - 'frozen-blocked' — a repo-health verify-FAIL whose only fix is an edit to a path
- *     THIS task's spec froze (mx5 run 12: `bun run lint` permanently red because the
- *     created files need a tsconfig registration every spec forbids). Cross-task
+ *     THIS task's spec froze — a lint left permanently red because the files it
+ *     created need a registration every spec forbids editing. Cross-task
  *     contradiction: no unattended re-run can converge, so the gate loop records the
  *     defect and routes to the human picker instead of burning AUTOFIX rounds.
  *   - 'yolo-accepted'   — YOLO MODE (unattended auto-pick, see yolo.ts) took the
@@ -24,16 +22,16 @@ import { type CommandRunner } from './command-run.js';
  *     weighed this failing artifact and blessed it, which is exactly the assurance
  *     an auto-pick cannot give. Same re-check treatment, honest provenance.
  *   - 'cross-task-deletion' — the task's work DELETED a sibling task's committed
- *     deliverable (mx5 run 12 PROMPT 2: a fix child deleted TASK_0020's playwright ct
- *     files to green a lint) and the user ACCEPTed the verify-FAIL anyway, so the
+ *     deliverable — a fix child deleting a sibling's test files to green a lint —
+ *     and the user ACCEPTed the verify-FAIL anyway, so the
  *     deletion ships in the next commit. Recorded so the final gate re-checks it:
  *     resolved iff the named file is back in the tree (a later task restored it),
  *     otherwise surfaced.
  *   - 'final-gate' — the final integration gate DEMOTED one of its own checks to
- *     UNOBSERVED (mx5 run 14): two fix attempts that both changed the tree and
+ *     UNOBSERVED: two fix attempts that both changed the tree and
  *     re-ran the gate produced a byte-identical ranked-first failure, so the check
- *     is unfalsifiable in this environment (run 14: the boot probe needed `ss` or
- *     `lsof` and the sandbox had neither) and no further attempt can move it. The
+ *     is unfalsifiable in this environment — the boot probe needing a tool the
+ *     sandbox does not have, say — and no further attempt can move it. The
  *     run is allowed to converge on the REMAINING checks, carrying this one here
  *     so the next run's gate re-checks and re-surfaces it rather than losing it.
  *     Also recorded for the ZERO-OBSERVATION verdict (final-gate.ts
@@ -42,13 +40,13 @@ import { type CommandRunner } from './command-run.js';
  *     completed on statics alone. Same treatment for the same reason: unprovable
  *     here, so carry it forward rather than let a silent PASS bury it.
  *   - 'root-cause' — the task's verify FAILed because of a PRE-EXISTING defect in a
- *     file a DIFFERENT task created, which this task's own work never touched (mx5
- *     run 14: TASK_0007's `test/teardown.ts` TRUNCATE bug FAILed TASK_0013 and
- *     TASK_0019). The current task is not at fault, so its work — and, at the
+ *     file a DIFFERENT task created, which this task's own work never touched. One
+ *     such defect can FAIL several later tasks in a row. The current task is not
+ *     at fault, so its work — and, at the
  *     enforce site, the enforce pass's edits — are KEPT rather than reverted; the
  *     defect is recorded here and a scoped repair task is queued into the plan
- *     (root-cause-repair.ts). Before this class existed the ledger recorded the same
- *     root cause twice and nothing ever scheduled a fix, so it survived ~24h.
+ *     (root-cause-repair.ts). Recording without queuing would let the same root
+ *     cause be re-recorded by each task it fails, with nothing ever fixing it.
  */
 export type DebtOrigin = 'accepted' | 'enforce-revert' | 'enforce-kept' | 'frozen-blocked' | 'cross-task-deletion' | 'yolo-accepted' | 'final-gate' | 'root-cause';
 /** One recorded defect: the task, why its VERIFY failed, and how it was recorded. */
@@ -61,16 +59,15 @@ export interface AcceptDebt {
      * Set (never serialized) when the recorded reason CONFLICTS with the run itself:
      * it asserts a file's existence is the failure, but that file is another task's
      * committed deliverable (see annotateDebtConflicts). A conflicting debt is a
-     * PLAN defect to surface, never an instruction to act on — mx5 run 11's autofix
-     * child `rm`'d TASK_0008's verified admin page to satisfy exactly such a claim.
+     * PLAN defect to surface, never an instruction to act on. An autofix child
+     * seeded with such a claim will delete the file to satisfy it.
      */
     conflict?: string;
     /**
      * The ONE command this debt's own reason NAMES, quoted verbatim in backticks and
-     * present byte-identically in the owning task's VERIFY block (nexttask 5, mx5 run
-     * 19 TASK_0009). Set at record time by classifyVerifyCommand; absent whenever the
-     * reason names no such command — which is most of them (measured: 2 of 19
-     * PROJECT-pool debts, `scripts/debt-verify-class-baserate.ts`).
+     * present byte-identically in the owning task's VERIFY block. Set at record
+     * time by classifyVerifyCommand, and absent whenever the reason names no such
+     * command — which is the common case, since most FAIL reasons are prose.
      *
      * It exists so the run-end re-check can settle the debt the way the debt was
      * created: by RUNNING the command and reading its exit status. Never
@@ -105,17 +102,16 @@ export declare function readAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
  * Best-effort by construction (appendDebt swallows its own faults): the ledger is an
  * auditing aid and must never break the gate sequence that calls it.
  *
- * `origin` is REQUIRED and deliberately has no default. It used to default to
- * 'accepted' (the legacy 2-field on-disk shape), and that default silently absorbed
- * a dropped argument: the eight-recorder collapse migrated one call in
- * scripts/ignored-writes-ab.ts without its origin, so a run-level 'final-gate'
- * demotion was stamped as a human 'accepted'. The wrappers each carried their class
- * in the NAME, so no migration of them could lose it; a defaulted parameter can.
- * Making it explicit turns that whole class of slip into a compile error.
+ * `origin` is REQUIRED and deliberately has no default. A default of 'accepted'
+ * would be the tempting one, since that is the legacy 2-field on-disk shape — and
+ * that is exactly what makes it dangerous. A dropped argument would then be
+ * absorbed in silence, stamping a run-level 'final-gate' demotion as a human
+ * 'accepted': the one confusion this type exists to prevent. Requiring it turns
+ * that slip into a compile error instead.
  */
 export declare function recordDebt(cwd: string, taskId: string, reason: string, origin: DebtOrigin): Promise<void>;
 /**
- * The reason text a CROSS-TASK DELETION debt stores (mx5 run 12 PROMPT 2): the task's
+ * The reason text a CROSS-TASK DELETION debt stores: the task's
  * work deleted a file a DIFFERENT task's commit introduced, verify FAILed, and the
  * user ACCEPTed — so the deletion survives into the next commit. The shape is fixed
  * and machine-parseable so the final gate's re-check can extract the path and prove
@@ -151,9 +147,9 @@ export declare function isStaticClassDebt(reason: string): boolean;
  * VERIFY fence, or a reason that quotes nothing all yield null, and null simply
  * means the debt keeps today's behaviour (surfaced, never auto-closed).
  *
- * The STRICT parse matters here. mx5 run 19's `TASK_0001.md` opens ```sh and never
- * closes it, so the lenient parser hands back the phase-timings table and every
- * appended gate-trail line as "VERIFY commands" — including sentences that quote
+ * The STRICT parse matters here. A spec that opens ```sh and never closes it
+ * makes the lenient parser hand back the phase-timings table and every appended
+ * gate-trail line as "VERIFY commands" — including sentences that quote
  * `bun run lint`. Matching a reason against that would mint a stored, re-runnable
  * command with fabricated provenance, which is the one thing this class may not do.
  */
@@ -176,7 +172,7 @@ export interface VerifyRerunResult {
  * task or a human restored it, so the deletion no longer holds); every other debt
  * stays OPEN (unprovable ⇒ surface, never re-hide) — unless it carries a stored
  * `verifyCommand` and `rerunVerify` re-runs that command to a ZERO exit, which is the
- * third class (nexttask 5): the debt named a command, the command was run, and it
+ * third class: the debt named a command, the command was run, and it
  * passed. FP-safe: the only auto-closes are ones a deterministic check can stand
  * behind, and here the check is the task spec's own command.
  */
@@ -184,7 +180,7 @@ export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
     staticOk: boolean;
     fileExists?: (rel: string) => boolean;
     /**
-     * Re-run a debt's stored VERIFY command (nexttask 5). Absent ⇒ the class is
+     * Re-run a debt's stored VERIFY command. Absent ⇒ the class is
      * inert and every debt behaves exactly as it did before it existed. Only
      * `pass` may close a debt; `fail` and `gap` both leave it open, and the
      * caller is expected to have made `pass` mean "ran, exited 0, and changed
@@ -201,7 +197,7 @@ export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
  * token immediately followed by "exists" / "still exists", or by "must/should not
  * exist". Only this narrow shape qualifies: a reason that merely MENTIONS a path
  * (a prohibition violation, a broken import) is an ordinary defect claim, not an
- * existence assertion, and must never be flagged (run 11's T1/T7 debts name paths
+ * existence assertion, and must never be flagged (such debts name paths
  * this way and are genuine).
  */
 export declare function extractExistenceClaims(reason: string): string[];
@@ -228,7 +224,7 @@ export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;
  */
 export declare function describeDebt(d: AcceptDebt): string;
 /**
- * ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+ * ACCEPT-debt re-check: read the ledger of tasks
  * the user accepted despite a verify-FAIL and re-check each against the CURRENT
  * tree. A static-class debt whose statics now pass is provably RESOLVED (a later
  * task fixed it) and pruned from the ledger; every other debt cannot be proven
@@ -237,9 +233,9 @@ export declare function describeDebt(d: AcceptDebt): string;
  * accept-debt.ts). Best-effort: a ledger read/write failure must never break the
  * caller.
  *
- * FACTORED OUT of runFinalIntegrationGate (nexttask 6): the derivation has to be
+ * FACTORED OUT of runFinalIntegrationGate: the derivation has to be
  * runnable at a SECOND moment — after a converged final-gate autofix, where the
- * orchestrator used to rebuild its gate outcome as a bare `{ok, reason}` and drop
+ * orchestrator rebuilds its gate outcome as a bare `{ok, reason}` and drops
  * `openDebts` entirely. The report a run ends on has to be derived from the tree
  * the run ends with, not from the tree as it was before the fix pass.
  *
@@ -263,9 +259,11 @@ run?: CommandRunner, signal?: AbortSignal): Promise<{
  * a passing tree and have that count as the debt being fixed — the run would then be
  * certifying its own side effect. So tracked state is captured before and after, and
  * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
- * change named. Untracked output is left alone: it is what a build legitimately
- * produces, and `git status --porcelain` in a repo with the usual ignores does not
- * see it.
+ * change named. Untracked output is left alone because the guard asks git not to
+ * report it: `--untracked-files=no` is doing that work, NOT the project's ignore
+ * rules. Checked both ways — with and without a matching `.gitignore`, the flag
+ * returns an empty status for a fresh untracked build directory, while plain
+ * `--porcelain` reports it when it is not ignored.
  *
  * A repository the guard cannot read (no git, git absent) is not a licence to skip
  * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an