@mjasnikovs/pi-task 0.21.10 → 0.23.0

package/README.md

@@ -65,7 +65,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume [--unattended]` | Resume the active `/task-auto` run at the next unfinished task. `--unattended` is the boot-hook form: in-flight runs only. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/task-config` | Toggle pi-task settings in an editor dialog: remote control, compress thinking, auto-commit, verify work, enforce guidelines, project tour, command timeout, stuck reply retry, and one `ext:` toggle per installed host extension. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote control, compress thinking, auto-commit, verify work, enforce guidelines, project tour, command timeout, stuck reply retry, debug logs, and one `ext:` toggle per installed host extension. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
@@ -183,6 +183,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
 | **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
+| **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 
 ## Configuration
@@ -195,6 +196,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
 | `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |
 | `PI_REMOTE_PUSH_LOG` | remote push | Path for the debug log (defaults to `/tmp/pi-task-push.log`). |
+| `PI_TASK_DEBUG_LOG` | task trail | Overrides the **debug logs** setting for one session: `off`, `events`, or `full`. For reproducing a report without walking someone through `/task-config`. An unrecognised value is ignored, not treated as `off`. |
 
 Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your `.gitignore` if you don't want them checked in.
 

package/dist/config/config.d.ts

@@ -96,7 +96,44 @@ export interface PiTaskConfig {
      * DEFAULT OFF — this is never the behaviour of a normal, watched run.
      */
     yoloMode: boolean;
+    /**
+     * How much the run writes to its `.pi-tasks/*-debug.log` forensic trail
+     * (task/debug-log.ts). NOTHING in pi-task ever reads these files back —
+     * `task-io.ts` only globs `TASK_NNNN.md`, and auto-commit's trail snapshot
+     * copies bytes without parsing them — so this knob is behaviour-neutral by
+     * construction. It trades disk and repo noise against the ability to explain
+     * a run after it has finished.
+     *
+     * `full` is every line the child model emitted plus every tool result;
+     * `events` keeps only decisions and guard actions; `off` writes nothing.
+     *
+     * DEFAULT `events`, not `off`, because the two levels are not the same kind
+     * of record. Measured on a real 247 KB `verify-debug.log` (IAR1, 1315 lines):
+     * the child's own output and the `↳` tool dumps are 85% of the bytes, while
+     * the `=== … ===` markers are 15% — and that 15% is the ONLY record of what
+     * the guards did (`GIT-STATE GUARD — child mutated graded state`, the
+     * write-capable child's `tree changes`, the FAIL reason). mx5 run 11's
+     * final-fix child deleted a source file; the tree-changes line is why that
+     * was findable at all. Silencing the chatter costs nothing; silencing the
+     * guard record makes the next incident unreconstructible, and a debug log
+     * cannot be recovered after the fact.
+     */
+    debugLogs: DebugLogLevel;
 }
+/** How verbose the `.pi-tasks/*-debug.log` trail is. See {@link PiTaskConfig.debugLogs}. */
+export type DebugLogLevel = 'off' | 'events' | 'full';
+/**
+ * The debug-log choices offered by /task-config, in cycle order (quietest →
+ * loudest, so the cycle reads as a volume dial). Unlike the timeout options the
+ * stored value IS the label — the level is already a word.
+ */
+export declare const DEBUG_LOG_OPTIONS: readonly DebugLogLevel[];
+/**
+ * Same pinning as the timeout sanitizers: a hand-edited `"debugLogs": true` or a
+ * level from a future version must not reach the writer as an unknown string —
+ * it falls back to the default rather than silently disabling the trail.
+ */
+export declare function sanitizeDebugLogs(value: unknown): DebugLogLevel;
 /**
  * The command-watchdog timeout choices offered by /task-config, newest-first in
  * the cycle order the picker shows. The stored config value is the ms number;

package/dist/config/config.js

@@ -4,6 +4,23 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
 import { DEFAULT_STREAM_INACTIVITY_MS } from '../shared/stream-watchdog.js';
+/**
+ * The debug-log choices offered by /task-config, in cycle order (quietest →
+ * loudest, so the cycle reads as a volume dial). Unlike the timeout options the
+ * stored value IS the label — the level is already a word.
+ */
+export const DEBUG_LOG_OPTIONS = ['off', 'events', 'full'];
+const DEFAULT_DEBUG_LOGS = 'events';
+/**
+ * Same pinning as the timeout sanitizers: a hand-edited `"debugLogs": true` or a
+ * level from a future version must not reach the writer as an unknown string —
+ * it falls back to the default rather than silently disabling the trail.
+ */
+export function sanitizeDebugLogs(value) {
+    return DEBUG_LOG_OPTIONS.includes(value) ?
+        value
+        : DEFAULT_DEBUG_LOGS;
+}
 /**
  * The command-watchdog timeout choices offered by /task-config, newest-first in
  * the cycle order the picker shows. The stored config value is the ms number;
@@ -61,7 +78,10 @@ const DEFAULTS = {
     requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
     streamInactivityMs: DEFAULT_STREAM_INACTIVITY_MS,
     // OFF: auto-answering is for unattended throwaway runs only.
-    yoloMode: false
+    yoloMode: false,
+    // EVENTS: the model chatter is 85% of the bytes and nobody reads it; the
+    // guard/verdict markers are the 15% that explains a failed run.
+    debugLogs: DEFAULT_DEBUG_LOGS
 };
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
@@ -96,6 +116,7 @@ if (!G.loaded) {
         // boolean counts; anything else falls back to the OFF default.
         if (typeof parsed.yoloMode !== 'boolean')
             delete parsed.yoloMode;
+        parsed.debugLogs = sanitizeDebugLogs(parsed.debugLogs);
         G.config = { ...DEFAULTS, ...parsed };
     }
     catch {

package/dist/config/register.js

@@ -2,7 +2,7 @@ import { SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
-import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
+import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 // Version in the title so a bug report or screenshot says which build it came
 // from without anyone having to go look it up.
@@ -160,6 +160,16 @@ const ITEMS = [
             + 'check is accepted and written down as debt, and a failed final check is retried '
             + 'until the budget runs out. Each auto-answer is marked (YOLO) in the task file. '
             + 'For throwaway projects you are not watching'
+    },
+    {
+        id: 'debugLogs',
+        label: 'debug logs',
+        description: 'How much of a run gets written to .pi-tasks/*-debug.log. "events" keeps the '
+            + 'decisions and the guard actions — what a checking step changed, why something '
+            + 'failed — a few lines per task. "full" adds everything the model said and every '
+            + 'command it ran, which is most of the size and only useful while you are digging '
+            + 'into a problem. "off" writes nothing, and nothing can be reconstructed later',
+        values: [...DEBUG_LOG_OPTIONS]
     }
 ];
 /** Human label for the stored command-timeout ms (falls back to the raw ms). */
@@ -295,6 +305,12 @@ async function handleTaskConfig(_args, ctx) {
             if (opt)
                 cfg.streamInactivityMs = opt.ms;
         }
+        else if (id === 'debugLogs') {
+            // The stored value IS the label here, but it must still go
+            // through the sanitizer — the generic `else` below would
+            // write the boolean `newValue === 'on'` into an enum field.
+            cfg.debugLogs = sanitizeDebugLogs(newValue);
+        }
         else {
             ;
             cfg[id] = newValue === 'on';

package/dist/shared/child-process.js

@@ -335,6 +335,40 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             else
                 stdout += chunk;
         });
+        // This accumulation is deliberately unbounded, unlike `discardStdout`
+        // above. The asymmetry was investigated on 2026-07-28 and the "stderr can
+        // overflow V8's max string length" hypothesis is REFUTED at ~5 orders of
+        // magnitude — do not re-open it without new volume evidence.
+        //
+        // Measured ceiling (binary search on `'a'.repeat`, not cited from memory):
+        // node v26.2.0 536,870,888 chars (512 MiB, 2^29-24), bun 1.3.14
+        // 2,147,483,647 (2 GiB). Both throw RangeError, not OOM — node's default
+        // heap is 4192 MiB, well clear of its own string ceiling. If it were ever
+        // reached the severity would be high: a throw in this handler escapes as
+        // an uncaughtException and the enclosing promise never settles (measured),
+        // so it would kill the host, not fail the child.
+        //
+        // Measured volume, real runs not synthetic: the largest single tool output
+        // in a full mx5 run is 5,043 bytes and that whole run's verify-debug.log is
+        // 112,216 bytes. The heaviest commands in the system are far under —
+        // pi-task's own 2,452-test suite emits 162 bytes of stderr, mx5's
+        // prettier+eslint+tsc lint 90, a cached `bun install` 0. Observed max is
+        // ~106,000x below the node ceiling; reaching it inside the 15-min command
+        // bound would need ~596 KB/s sustained on stderr for the full window.
+        //
+        // The structural reason is the population of children that reach here:
+        // `pi` model children (stderr near-empty), `git`, and one
+        // `npm install --loglevel=error`. Genuinely verbose work — test runners,
+        // builds, boot probes — does not use runChild; final-gate.ts spawns its own
+        // and already caps at 8000 chars. So `discardStdout`'s single caller
+        // (docs-core.ts) is not an oversight to mirror: it discards the verbose
+        // stream and KEEPS stderr precisely because stderr is that call's payload.
+        //
+        // A symmetric `discardStderr` would therefore have no caller, and a naive
+        // cap here would be actively unsafe: consumers disagree about which end
+        // carries the cause — phases.ts:474 takes the tail (-500), phases.ts:936
+        // takes the head (0, 300), and child-runner.ts:172 feeds the whole string
+        // into failure classification.
         proc.stderr?.on('data', (d) => {
             lastActivity = Date.now();
             streamWatch?.note();

package/dist/task/auto-orchestrator.js

@@ -38,10 +38,12 @@ import { describeDebt, recordFinalGateUnobservedDebt } from './accept-debt.js';
 import { applyDemotions, isNonProgress, normalizeFailureDetail, rankedFirstFailure, unobservedDebtReason } from './final-gate-progress.js';
 import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE, STRANDED_FIX_COMMIT, strandedFixNote } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
+import { debugLogLevel, shouldLogDebug } from './debug-log.js';
 import { isYoloMode, yoloPickAnswer, yoloFinalGateChoice, YOLO_STAMP } from './yolo.js';
 import { configureResearchRun, resumeResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
 import { reconcileTitleSources } from './decompose-fidelity.js';
+import { granularityFloor, granularitySplitHint, isPlanShapeQuestion, isTooCoarse, planShapeIsHostsToAnswer, PLAN_SHAPE_ANSWER } from './decompose-granularity.js';
 import { mandatesTestsInSameChange, rewriteBatchTestPlan } from './batch-test-task.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';
@@ -121,8 +123,16 @@ function mentionPath(token) {
  * before any task file — hence any per-task `TASK_XXXX-debug.log` — exists. Writes
  * to `.pi-tasks/plan-debug.log`; the `*-debug.log` suffix keeps it grep-compatible
  * with the per-task logs. Never throws (mkdir + append are best-effort).
+ *
+ * Every call site here records a plan DECISION (how many titles a round produced,
+ * whether a retry was adopted, which clarify answer was auto-resolved), so all of
+ * them are `'event'` — this file carries no model chatter and survives at the
+ * default level. It is also the only channel the plan phase has: it runs before
+ * any task file, hence any `TASK_NNNN-debug.log`, exists.
  */
 function logPlanDebug(cwd, msg) {
+    if (!shouldLogDebug('event', debugLogLevel()))
+        return;
     const line = `${new Date().toISOString()} ${msg}\n`;
     const dir = tasksDir(cwd);
     fsp.mkdir(dir, { recursive: true })
@@ -424,6 +434,54 @@ export async function planAuto(ctx, cwd, feature, deps) {
         taskId: '',
         signal: new AbortController().signal
     }).catch(() => '');
+    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
+    // extracted from whatever structure the spec has, BEFORE decompose — they ride
+    // 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).
+    let reqEntries = [];
+    try {
+        // Recall floor: the obligation-marked passages ride into the prompt as a
+        // checklist, and a marked passage that produced NO quote is hard evidence
+        // for one forced re-extraction (measured live: 1/5 extractions missed the
+        // entire marked testing section without this).
+        const passages = enumerateObligationPassages(featureForModel);
+        const extractOnce = async (hint) => keepGroundedRequirements(parseRequirementLines(await deps.runChild('requirement-extract', '', prependHint(hint, REQUIREMENT_EXTRACT_PROMPT(featureForModel, passages)))), featureForModel);
+        reqEntries = await extractOnce(null);
+        const uncovered = uncoveredPassages(passages, reqEntries);
+        if (uncovered.length > 0) {
+            logPlanDebug(cwd, `requirement extraction: ${uncovered.length} obligation-marked passage(s) `
+                + 'uncovered — forcing one re-extraction');
+            const retry = await extractOnce(extractionRetryHint(uncovered));
+            // Union of both grounded passes (keepGrounded dedupes).
+            reqEntries = keepGroundedRequirements([...reqEntries, ...retry], featureForModel);
+        }
+        // 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, featureForModel);
+        logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
+    }
+    catch {
+        // best-effort channel
+    }
+    // Granularity floor (mx5 Jul 25 vs Jul 27): the plan's task COUNT was being set
+    // by an auto-resolved clarify line the user never saw — the same spec planned
+    // into 41 tasks one day and 11 the next, with identical code. Derive the floor
+    // from the requirements a task can own, so an unreviewable "one task per
+    // milestone" decision cannot collapse the plan; it also gates whether the
+    // plan-shape fork below is the host's to answer at all. 0 ownable ⇒ no channel.
+    const ownableRequirements = reqEntries.filter(e => !isCrossCuttingRequirement(e.quote)).length;
+    const coarseFloor = granularityFloor(ownableRequirements);
+    if (coarseFloor > 0) {
+        logPlanDebug(cwd, `granularity floor: ${ownableRequirements} ownable requirement(s) ⇒ at least `
+            + `${coarseFloor} task(s)`);
+    }
     const answers = [];
     // Plain text of every question already shown, for the duplicate backstop.
     const askedQuestions = [];
@@ -458,6 +516,19 @@ export async function planAuto(ctx, cwd, feature, deps) {
         const shownQ = renderInlineMarkdown(question, theme);
         const plainQ = stripInlineMarkdown(question);
         askedQuestions.push(plainQ);
+        // PLAN SHAPE is the host's call, not the triage's (mx5 41→11 tasks on the
+        // same spec, same base commit, same code — see decompose-granularity.ts).
+        // The triage answers this fork for itself in 8/8 live reps and stamps it
+        // "already settled by the spec" while the spec settles no such thing, so the
+        // single most load-bearing decision in a run was an invisible coin flip.
+        // Answer it deterministically instead: same channel, same transcript, but a
+        // fixed value the user can read in the AUTO file and override next run.
+        if (planShapeIsHostsToAnswer(ownableRequirements) && isPlanShapeQuestion(plainQ)) {
+            logPlanDebug(cwd, `plan-shape question answered host-side (not the triage): ${plainQ.replace(/\s+/g, ' ').slice(0, 120)}`);
+            answers.push(`Q${answers.length + 1}: ${plainQ}\n`
+                + `A${answers.length + 1}: ${PLAN_SHAPE_ANSWER} (host-set — plan granularity is not left to chance)`);
+            continue;
+        }
         // Answer-side triage (grill parity): if the inlined spec already settles
         // this question, auto-resolve it and never show it. The resolved value is
         // recorded so decompose sees the decision and the next gen call's priorQA
@@ -544,37 +615,6 @@ export async function planAuto(ctx, cwd, feature, deps) {
         ctx.ui.notify('No clarifying questions needed — planning tasks…', 'info');
     }
     const clarifications = answers.join('\n');
-    // Requirement extraction (mx5 run 11, goal A): grounded requirement units,
-    // extracted from whatever structure the spec has, BEFORE decompose — they ride
-    // into the decompose prompt as a ledger (structure-mirroring can't discharge
-    // them) and drive the per-requirement coverage accounting below. 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
-        // checklist, and a marked passage that produced NO quote is hard evidence
-        // for one forced re-extraction (measured live: 1/5 extractions missed the
-        // entire marked testing section without this).
-        const passages = enumerateObligationPassages(featureForModel);
-        const extractOnce = async (hint) => keepGroundedRequirements(parseRequirementLines(await deps.runChild('requirement-extract', '', prependHint(hint, REQUIREMENT_EXTRACT_PROMPT(featureForModel, passages)))), featureForModel);
-        reqEntries = await extractOnce(null);
-        const uncovered = uncoveredPassages(passages, reqEntries);
-        if (uncovered.length > 0) {
-            logPlanDebug(cwd, `requirement extraction: ${uncovered.length} obligation-marked passage(s) `
-                + 'uncovered — forcing one re-extraction');
-            const retry = await extractOnce(extractionRetryHint(uncovered));
-            // Union of both grounded passes (keepGrounded dedupes).
-            reqEntries = keepGroundedRequirements([...reqEntries, ...retry], featureForModel);
-        }
-        // 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, featureForModel);
-        logPlanDebug(cwd, `requirement extraction: ${reqEntries.length} grounded requirement(s) kept`);
-    }
-    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
@@ -636,6 +676,20 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const listRaw = await deps.runChild('auto-decompose', 'read', decomposePrompt);
     let planTitles = parsePlan(listRaw);
     logPlanDebug(cwd, `decompose produced ${planTitles.length} title(s)`);
+    // BRACES for the floor: the prompt clause alone is a preference the model can
+    // ignore, so a plan under the floor is sent back ONCE to be split (never
+    // regenerated — a fresh roll can drop a covered area, mx5 run 12). Longer plan
+    // wins; a still-coarse plan falls through to the coverage judge as before, so
+    // this can never block planning.
+    if (isTooCoarse(planTitles.length, coarseFloor)) {
+        logPlanDebug(cwd, `plan under the granularity floor (${planTitles.length} < ${coarseFloor}) — `
+            + 'reprompting once to split');
+        const splitRaw = await deps.runChild('auto-decompose', 'read', prependHint(granularitySplitHint(planTitles.length, ownableRequirements), decomposePrompt));
+        const splitTitles = parsePlan(splitRaw);
+        logPlanDebug(cwd, `granularity split-retry produced ${splitTitles.length} title(s)`);
+        if (splitTitles.length > planTitles.length)
+            planTitles = splitTitles;
+    }
     // Distrust floor (see isSuspectPlan): a ≤2-title plan for a multi-KB spec is
     // regenerated once BEFORE the judge runs — the judge cannot be trusted to
     // catch it (3/10 live false-pass) and a hinted retry heals it reliably

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

@@ -16,6 +16,12 @@ export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) =>
  * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts) — emitted ONLY
  * when the decisions mandate tests-in-the-same-change, so every other run sees the
  * prompt it always saw. It is the belt; the host-side rewrite is the lever.
+ *
+ * Plan GRANULARITY is deliberately NOT a rule here — it rides in CLARIFICATIONS
+ * (decompose-granularity.ts). Live A/B: as a RULES line replacing "prefer a
+ * handful", it made plan size explode (81 and 85 titles for a spec whose healthy
+ * plan is ~30, one 120k-context blowup); as a clarification, with the counterweight
+ * below left intact, the same directive holds 20–39 across 16 reps.
  */
 export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string, requirementsLedger?: string, noBatchTests?: boolean) => string;
 /**

package/dist/task/auto-prompts.js

@@ -76,6 +76,12 @@ NONE`;
  * `noBatchTests` adds the anti-batch-test rule (batch-test-task.ts) — emitted ONLY
  * when the decisions mandate tests-in-the-same-change, so every other run sees the
  * prompt it always saw. It is the belt; the host-side rewrite is the lever.
+ *
+ * Plan GRANULARITY is deliberately NOT a rule here — it rides in CLARIFICATIONS
+ * (decompose-granularity.ts). Live A/B: as a RULES line replacing "prefer a
+ * handful", it made plan size explode (81 and 85 titles for a spec whose healthy
+ * plan is ~30, one 120k-context blowup); as a clarification, with the counterweight
+ * below left intact, the same directive holds 20–39 across 16 reps.
  */
 export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications, requirementsLedger = '', noBatchTests = false) => `Split this feature into an ordered list of implementation tasks. Each task
 will be handed, by its title, to a separate pipeline that does its own research

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

@@ -6,6 +6,7 @@
  * for phase-level child pi invocations.
  */
 import { type SpawnFn, type ContextSnapshot, type ToolCall, type LoopHit } from '../shared/child-process.js';
+import type { DebugLine } from './debug-log.js';
 export declare const LOOP_WINDOW = 20;
 export declare const LOOP_THRESHOLD = 5;
 export declare const MAX_LOOP_RESTARTS = 2;
@@ -44,8 +45,16 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
-    /** Write a timestamped line to the per-task debug log. Fire-and-forget. */
-    logDebug?: (msg: string) => void;
+    /**
+     * Write a timestamped line to the per-task debug log. Fire-and-forget, and
+     * UNSET entirely when the trail is off — so a caller must keep the `?.` and
+     * must not do work to build a message outside the call.
+     *
+     * `kind` defaults to `'event'` (a decision or guard action, kept at the
+     * default level). Pass `'stream'` for raw child output and tool results,
+     * which only the `full` level keeps. See debug-log.ts.
+     */
+    logDebug?: (msg: string, kind?: DebugLine) => void;
     /** Injectable delay for connection-error backoff; defaults to a real timer.
      *  Tests override it with a no-op so retries don't actually sleep. */
     sleepFor?: (ms: number) => Promise<void>;

package/dist/task/debug-log.d.ts

@@ -0,0 +1,34 @@
+import { type DebugLogLevel } from '../config/config.js';
+/**
+ * Escape hatch for reproducing a user's bug without walking them through
+ * /task-config. Follows the existing `PI_TASK_*` instrumentation convention
+ * (`PI_TASK_TYPEONLY_LOG`, `PI_REMOTE_PUSH_DEBUG`). An unrecognised value is
+ * ignored rather than treated as `off` — a typo in an env var must not silently
+ * throw the trail away.
+ */
+export declare const DEBUG_LOG_ENV = "PI_TASK_DEBUG_LOG";
+/** A trail line's kind — see the module note. Producers default to `'event'`. */
+export type DebugLine = 'event' | 'stream';
+/**
+ * The level in force: env override first, then the saved config. Read per call
+ * rather than cached, so flipping the setting mid-run takes effect on the next
+ * line instead of at the next restart.
+ */
+export declare function debugLogLevel(getEnv?: (k: string) => string | undefined): DebugLogLevel;
+/** Whether a line of this kind should be written at `level`. */
+export declare function shouldLogDebug(kind: DebugLine, level: DebugLogLevel): boolean;
+/**
+ * A timestamped fire-and-forget appender for one trail file, level-gated.
+ *
+ * `kind` defaults to `'event'` so a new call site is quiet-by-default in the
+ * useful direction: forgetting to classify a marker keeps it in the audit trail,
+ * whereas forgetting to classify chatter would only make the log bigger. Errors
+ * are swallowed — an unwritable trail must never fail the run it is describing.
+ */
+export declare function makeDebugAppender(logPath: string, appendFile?: (p: string, data: string) => Promise<unknown>): (msg: string, kind?: DebugLine) => void;
+/**
+ * Wrap a raw append in the level gate. Returns `undefined` when the level is
+ * `off`, so callers that hold an OPTIONAL `logDebug` leave it unset and every
+ * `logDebug?.(…)` in the pipeline short-circuits before it formats a string.
+ */
+export declare function gateDebugWriter(write: (msg: string) => void, getEnv?: (k: string) => string | undefined): ((msg: string, kind?: DebugLine) => void) | undefined;

package/dist/task/debug-log.js

@@ -0,0 +1,87 @@
+/**
+ * One place that decides whether a `.pi-tasks/*-debug.log` line gets written.
+ *
+ * THE TRAIL IS WRITE-ONLY. Nothing in pi-task reads these files back: `task-io.ts`
+ * globs `TASK_NNNN.md` and skips everything else, and auto-commit's `snapshotTrail`
+ * copies the bytes across a `reset --hard` without ever parsing them. Every producer
+ * is a `logDebug?.(…)` / `log(…)` side effect whose return value is discarded. So
+ * this gate cannot change what a run DOES — only what it can explain afterwards.
+ *
+ * TWO KINDS OF LINE, and the distinction is the whole point of having three levels
+ * rather than a boolean:
+ *
+ *   'stream' — what the child model said, and what its tools returned. Reproducible
+ *              by re-running, useful while you are actively debugging, and 85% of the
+ *              bytes (measured: a 247 KB IAR1 `verify-debug.log` is 1315 lines, of
+ *              which 521 are `↳` tool dumps and most of the rest is raw model text).
+ *
+ *   'event'  — a decision or a guard action: which phase started, why a worker was
+ *              retried or degraded, what the git-state guard restored, what a
+ *              write-capable child changed on disk, why a gate returned FAIL. Ten-ish
+ *              lines per task, and NOT reproducible — it is the only record that the
+ *              guard fired at all. mx5 run 11's final-fix child deleted a source file
+ *              and the `tree changes:` line is the reason anyone could tell.
+ *
+ * Hence the default is `events`, not `off`: the quiet default users want costs the
+ * chatter, not the audit trail.
+ */
+import * as fsp from 'node:fs/promises';
+import { getConfig, sanitizeDebugLogs } from '../config/config.js';
+/**
+ * Escape hatch for reproducing a user's bug without walking them through
+ * /task-config. Follows the existing `PI_TASK_*` instrumentation convention
+ * (`PI_TASK_TYPEONLY_LOG`, `PI_REMOTE_PUSH_DEBUG`). An unrecognised value is
+ * ignored rather than treated as `off` — a typo in an env var must not silently
+ * throw the trail away.
+ */
+export const DEBUG_LOG_ENV = 'PI_TASK_DEBUG_LOG';
+/**
+ * The level in force: env override first, then the saved config. Read per call
+ * rather than cached, so flipping the setting mid-run takes effect on the next
+ * line instead of at the next restart.
+ */
+export function debugLogLevel(getEnv = k => process.env[k]) {
+    const raw = getEnv(DEBUG_LOG_ENV)?.trim();
+    // sanitizeDebugLogs falls back to the DEFAULT for anything unrecognised, so
+    // an unset/typo'd var must be filtered out here rather than handed to it —
+    // otherwise `PI_TASK_DEBUG_LOG=verbose` would quietly override a saved `off`.
+    if (raw && sanitizeDebugLogs(raw) === raw)
+        return raw;
+    return getConfig().debugLogs;
+}
+/** Whether a line of this kind should be written at `level`. */
+export function shouldLogDebug(kind, level) {
+    if (level === 'off')
+        return false;
+    if (level === 'full')
+        return true;
+    return kind === 'event';
+}
+/**
+ * A timestamped fire-and-forget appender for one trail file, level-gated.
+ *
+ * `kind` defaults to `'event'` so a new call site is quiet-by-default in the
+ * useful direction: forgetting to classify a marker keeps it in the audit trail,
+ * whereas forgetting to classify chatter would only make the log bigger. Errors
+ * are swallowed — an unwritable trail must never fail the run it is describing.
+ */
+export function makeDebugAppender(logPath, appendFile = (p, data) => fsp.appendFile(p, data)) {
+    return (msg, kind = 'event') => {
+        if (!shouldLogDebug(kind, debugLogLevel()))
+            return;
+        void appendFile(logPath, `${new Date().toISOString()} ${msg}\n`).catch(() => { });
+    };
+}
+/**
+ * Wrap a raw append in the level gate. Returns `undefined` when the level is
+ * `off`, so callers that hold an OPTIONAL `logDebug` leave it unset and every
+ * `logDebug?.(…)` in the pipeline short-circuits before it formats a string.
+ */
+export function gateDebugWriter(write, getEnv) {
+    if (debugLogLevel(getEnv) === 'off')
+        return undefined;
+    return (msg, kind = 'event') => {
+        if (shouldLogDebug(kind, debugLogLevel(getEnv)))
+            write(msg);
+    };
+}

package/dist/task/decompose-granularity.d.ts

@@ -0,0 +1,98 @@
+/**
+ * decompose-granularity — the deterministic FLOOR on how finely /task-auto cuts
+ * a feature into tasks.
+ *
+ * The failure this closes (mx5, Jul 25 vs Jul 27): the SAME design doc, from the
+ * SAME base commit, with a byte-identical planning path, planned once into 41
+ * tasks and once into 11. The whole 4x difference is one line of clarify text.
+ * /task-auto's clarify head asks a plan-shape question first ("one task per
+ * milestone, or split smaller?" — 8/8 live reps), the answer-side triage
+ * auto-resolves it 8/8 and stamps it "already settled by the spec", so the user
+ * never sees the fork; and the answer decides the whole plan. Live A/B, run 18's
+ * transcript with ONLY that line swapped (n=8/arm): coarse mean 11.4 titles vs
+ * fine mean 28.6, 63.5/64 pairwise wins, p<0.001.
+ *
+ * The spec does NOT settle it. mx5's §12 is titled "Build order (milestones)" —
+ * an ORDER, 9 items, not a task breakdown. So the plan's granularity, the single
+ * highest-leverage decision in a run (each title is handed to its own pipeline
+ * that researches and specs it alone), was being decided by a coin flip nobody
+ * could see, review, or reproduce.
+ *
+ * Surfacing the question does not fix it: under YOLO/unattended `yoloPickAnswer`
+ * takes the recommendation, which is the same stochastic line. The fix has to be
+ * host-side and deterministic, so this module derives the floor from integers the
+ * run already has — the count of grounded requirements that a task can OWN.
+ *
+ *   floor = ceil(ownable requirements / MAX_REQUIREMENTS_PER_TASK)
+ *
+ * MAX_REQUIREMENTS_PER_TASK = 2 is anchored on the two real mx5 plans, not on
+ * taste: the 41-task plan carried 0.8 ownable requirements per task, the collapsed
+ * 11-task plan carried 2.8. A ceiling of 2 sits between them — it rejects the
+ * collapse without demanding the finest plan ever observed.
+ *
+ * Spec-shape-agnostic: the only inputs are two integers. A CLI, a library, a
+ * refactor, a docs job all flow through the same arithmetic, and a feature with
+ * no extracted requirements (a one-liner, a doc-less request) yields floor 0 —
+ * the whole channel degrades to exactly the previous behaviour.
+ */
+/**
+ * The most distinct grounded requirements one task may carry before the plan is
+ * judged too coarse. See the module docstring for the mx5 anchoring.
+ */
+export declare const MAX_REQUIREMENTS_PER_TASK = 2;
+/**
+ * Fewest task titles a plan may have for `ownable` requirements. Zero when the
+ * requirement channel produced nothing, which disables every check below.
+ */
+export declare function granularityFloor(ownable: number): number;
+/** Is this plan too coarse for the requirements it has to carry? */
+export declare function isTooCoarse(titles: number, floor: number): boolean;
+/**
+ * Fewest ownable requirements a feature needs before the host takes the
+ * plan-shape fork away from the triage.
+ *
+ * Below this the fork is not load-bearing — the whole plan is one or two tasks
+ * either way — and seizing it does harm: live smoke over 24 prompts, the host
+ * directive turned "rename the `foo()` helper across the repo" (1 requirement)
+ * into a 6-task plan and "add a .editorconfig" (4) into 4. Every case at or above
+ * this cut planned inside its expected range. So: a feature with real breadth
+ * gets the deterministic answer, a chore keeps the old triage path untouched.
+ */
+export declare const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
+/** Does this feature have enough distinct deliverables for granularity to matter? */
+export declare function planShapeIsHostsToAnswer(ownable: number): boolean;
+/**
+ * Does this clarify question decide how finely the feature is CUT into tasks?
+ *
+ * Deterministic and narrow on purpose. It must fire on the fork the triage keeps
+ * answering for itself ("follow the milestones as-is, or split more granularly?")
+ * and stay off ordinary scope questions — an over-eager classifier would replace
+ * a real user decision with the host's. Matched against the plain-text question.
+ */
+export declare function isPlanShapeQuestion(question: string): boolean;
+/**
+ * BELT — the host's own answer to that fork, recorded in the clarify transcript in
+ * place of the triage's.
+ *
+ * WHY A CLARIFICATION AND NOT A DECOMPOSE RULE. Both were measured live. As a
+ * RULES line replacing "prefer a handful of substantial tasks", the same directive
+ * removed the collapse but destroyed plan-size control: 66, then 81 and 85 titles
+ * for a spec whose healthy plan is ~30, plus one decompose child that blew the
+ * model's 120k context window and killed the planning phase (the baseline produced
+ * no such failure in 27 reps). Naming a target count made it worse, not better.
+ * In the CLARIFICATIONS block, with the "prefer a handful" counterweight left
+ * intact, the identical directive held 20–39 titles across 16 reps. The channel is
+ * part of the lever, not a detail.
+ *
+ * Deliberately count-free: the spec-derived floor stays host-side, where it is
+ * enforced silently and cannot be chased.
+ */
+export declare const PLAN_SHAPE_QUESTION = "How finely should this feature be split into tasks?";
+export declare const PLAN_SHAPE_ANSWER: string;
+/**
+ * BRACES — the reprompt when the returned plan lands under the floor. Also
+ * countless, for the reason above: it asks for a SPLIT of the plan in hand rather
+ * than a fresh roll (a regeneration is a new stochastic draw over the whole plan
+ * and can drop an area the current one covers — mx5 run 12).
+ */
+export declare function granularitySplitHint(titles: number, ownable: number): string;

package/dist/task/decompose-granularity.js

@@ -0,0 +1,124 @@
+/**
+ * decompose-granularity — the deterministic FLOOR on how finely /task-auto cuts
+ * a feature into tasks.
+ *
+ * The failure this closes (mx5, Jul 25 vs Jul 27): the SAME design doc, from the
+ * SAME base commit, with a byte-identical planning path, planned once into 41
+ * tasks and once into 11. The whole 4x difference is one line of clarify text.
+ * /task-auto's clarify head asks a plan-shape question first ("one task per
+ * milestone, or split smaller?" — 8/8 live reps), the answer-side triage
+ * auto-resolves it 8/8 and stamps it "already settled by the spec", so the user
+ * never sees the fork; and the answer decides the whole plan. Live A/B, run 18's
+ * transcript with ONLY that line swapped (n=8/arm): coarse mean 11.4 titles vs
+ * fine mean 28.6, 63.5/64 pairwise wins, p<0.001.
+ *
+ * The spec does NOT settle it. mx5's §12 is titled "Build order (milestones)" —
+ * an ORDER, 9 items, not a task breakdown. So the plan's granularity, the single
+ * highest-leverage decision in a run (each title is handed to its own pipeline
+ * that researches and specs it alone), was being decided by a coin flip nobody
+ * could see, review, or reproduce.
+ *
+ * Surfacing the question does not fix it: under YOLO/unattended `yoloPickAnswer`
+ * takes the recommendation, which is the same stochastic line. The fix has to be
+ * host-side and deterministic, so this module derives the floor from integers the
+ * run already has — the count of grounded requirements that a task can OWN.
+ *
+ *   floor = ceil(ownable requirements / MAX_REQUIREMENTS_PER_TASK)
+ *
+ * MAX_REQUIREMENTS_PER_TASK = 2 is anchored on the two real mx5 plans, not on
+ * taste: the 41-task plan carried 0.8 ownable requirements per task, the collapsed
+ * 11-task plan carried 2.8. A ceiling of 2 sits between them — it rejects the
+ * collapse without demanding the finest plan ever observed.
+ *
+ * Spec-shape-agnostic: the only inputs are two integers. A CLI, a library, a
+ * refactor, a docs job all flow through the same arithmetic, and a feature with
+ * no extracted requirements (a one-liner, a doc-less request) yields floor 0 —
+ * the whole channel degrades to exactly the previous behaviour.
+ */
+/**
+ * The most distinct grounded requirements one task may carry before the plan is
+ * judged too coarse. See the module docstring for the mx5 anchoring.
+ */
+export const MAX_REQUIREMENTS_PER_TASK = 2;
+/**
+ * Fewest task titles a plan may have for `ownable` requirements. Zero when the
+ * requirement channel produced nothing, which disables every check below.
+ */
+export function granularityFloor(ownable) {
+    return ownable <= 0 ? 0 : Math.ceil(ownable / MAX_REQUIREMENTS_PER_TASK);
+}
+/** Is this plan too coarse for the requirements it has to carry? */
+export function isTooCoarse(titles, floor) {
+    return floor > 0 && titles < floor;
+}
+/**
+ * Fewest ownable requirements a feature needs before the host takes the
+ * plan-shape fork away from the triage.
+ *
+ * Below this the fork is not load-bearing — the whole plan is one or two tasks
+ * either way — and seizing it does harm: live smoke over 24 prompts, the host
+ * directive turned "rename the `foo()` helper across the repo" (1 requirement)
+ * into a 6-task plan and "add a .editorconfig" (4) into 4. Every case at or above
+ * this cut planned inside its expected range. So: a feature with real breadth
+ * gets the deterministic answer, a chore keeps the old triage path untouched.
+ */
+export const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
+/** Does this feature have enough distinct deliverables for granularity to matter? */
+export function planShapeIsHostsToAnswer(ownable) {
+    return ownable >= MIN_REQUIREMENTS_FOR_PLAN_SHAPE;
+}
+/**
+ * Does this clarify question decide how finely the feature is CUT into tasks?
+ *
+ * Deterministic and narrow on purpose. It must fire on the fork the triage keeps
+ * answering for itself ("follow the milestones as-is, or split more granularly?")
+ * and stay off ordinary scope questions — an over-eager classifier would replace
+ * a real user decision with the host's. Matched against the plain-text question.
+ */
+export function isPlanShapeQuestion(question) {
+    const q = question.toLowerCase();
+    // The fork has to be about the BREAKDOWN itself…
+    const aboutBreakdown = /\b(task breakdown|break(ing)? (it|this|the \w+) down|decompos\w*|split\w*|subdivid\w*|granular\w*|fine[- ]grained|one task per|task per (milestone|section|step|phase|feature)|per[- ](milestone|route|component|page|module)\b|(own|separate|standalone|dedicated|self[- ]contained|single)\s+(\w+\s+)?tasks?\b)/.test(q);
+    if (!aboutBreakdown)
+        return false;
+    // …and offer a coarse/fine choice over the plan's own units.
+    return /\b(milestone|section|step|phase|task|tasks)\b/.test(q);
+}
+/**
+ * BELT — the host's own answer to that fork, recorded in the clarify transcript in
+ * place of the triage's.
+ *
+ * WHY A CLARIFICATION AND NOT A DECOMPOSE RULE. Both were measured live. As a
+ * RULES line replacing "prefer a handful of substantial tasks", the same directive
+ * removed the collapse but destroyed plan-size control: 66, then 81 and 85 titles
+ * for a spec whose healthy plan is ~30, plus one decompose child that blew the
+ * model's 120k context window and killed the planning phase (the baseline produced
+ * no such failure in 27 reps). Naming a target count made it worse, not better.
+ * In the CLARIFICATIONS block, with the "prefer a handful" counterweight left
+ * intact, the identical directive held 20–39 titles across 16 reps. The channel is
+ * part of the lever, not a detail.
+ *
+ * Deliberately count-free: the spec-derived floor stays host-side, where it is
+ * enforced silently and cannot be chased.
+ */
+export const PLAN_SHAPE_QUESTION = 'How finely should this feature be split into tasks?';
+export const PLAN_SHAPE_ANSWER = 'subdivide into smaller per-deliverable tasks — one task per route, page, screen,'
+    + ' module, schema, or pipeline stage — rather than one task per milestone or spec'
+    + ' section. A milestone or section that spans several deliverables becomes several'
+    + ' tasks. (host-set: the spec fixes the build ORDER, not the task breakdown, so'
+    + ' pi-task settles granularity deterministically instead of guessing per run)';
+/**
+ * BRACES — the reprompt when the returned plan lands under the floor. Also
+ * countless, for the reason above: it asks for a SPLIT of the plan in hand rather
+ * than a fresh roll (a regeneration is a new stochastic draw over the whole plan
+ * and can drop an area the current one covers — mx5 run 12).
+ */
+export function granularitySplitHint(titles, ownable) {
+    return (`[SYSTEM NOTE: your plan of ${titles} task(s) is too coarse for the`
+        + ` ${ownable} required contents this spec lists — several tasks each bundle work`
+        + ' that belongs in separate ones. Emit the SAME plan with those tasks SPLIT: keep'
+        + ' every task that is already one deliverable, and break each one that bundles'
+        + ' several routes, pages, modules, or pipeline stages into one task per piece.'
+        + ' Do not drop anything, do not merge, do not pad with trivia — split what is'
+        + ' already there.]');
+}

package/dist/task/gate-deps.js

@@ -43,6 +43,7 @@ import { captureGitState, reconcileGitState } from './git-state-guard.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { formatLoopHint } from './child-runner.js';
 import { getConfig } from '../config/config.js';
+import { makeDebugAppender } from './debug-log.js';
 import { startAutoLoader } from './widget.js';
 import { resolveContextUsage } from './context-usage.js';
 /** Max chars of a tool result kept in the gate debug log (mx5 run 10 item 6). */
@@ -352,10 +353,11 @@ export function buildGateDeps(params) {
         contextUsage = undefined;
         lastGuardReconcile = null;
         const startedAt = Date.now();
-        const logPath = path.join(tasksDir(cwd2), logFile);
-        const log = (msg) => {
-            void fsp.appendFile(logPath, `${new Date().toISOString()} ${msg}\n`).catch(() => { });
-        };
+        // `kind` defaults to 'event': every marker below (start/end, the
+        // git-state guard's restore, the loop warning, a write-capable child's
+        // tree changes) is a guard record that survives at the default level.
+        // Only the child's own stdout and its tool results pass 'stream'.
+        const log = makeDebugAppender(path.join(tasksDir(cwd2), logFile));
         log(`=== ${kind} start: ${taskTitle} ===`);
         // GIT-STATE GUARD: these children are read-only BY CONTRACT, but the
         // contract is prompt-level and the live model breaks it (mx5 run 6: the
@@ -399,14 +401,17 @@ export function buildGateDeps(params) {
                     streamInactivityMs: getConfig().streamInactivityMs,
                     loop: { pathThreshold: Number.POSITIVE_INFINITY },
                     onLine: line => {
+                        // `lastLine` feeds the LIVE status widget and is not
+                        // logging — it stays outside the gate, or a quiet
+                        // trail would also blank the progress display.
                         lastLine = line;
-                        log(line);
+                        log(line, 'stream');
                     },
                     // Log tool OUTPUTS, not just the command (mx5 run 10 item 6):
                     // without the result "verify claimed curl PASS on a server that
                     // cannot serve" is undecidable from the log. Truncated, tail-kept
                     // (a bind failure / status usually lands at the end), error-flagged.
-                    onToolResult: ({ name, isError, text }) => log(`↳ ${name} [${isError ? 'ERR' : 'ok'}]: ${truncateToolResult(text)}`),
+                    onToolResult: ({ name, isError, text }) => log(`↳ ${name} [${isError ? 'ERR' : 'ok'}]: ${truncateToolResult(text)}`, 'stream'),
                     onContextUsage: snapshot => {
                         contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
                     }
@@ -549,12 +554,7 @@ export function buildGateDeps(params) {
                     contextUsage = undefined;
                     const startedAt = Date.now();
                     // Per-pass debug log; the enforce child is otherwise unobservable.
-                    const enforceLogPath = path.join(tasksDir(cwd2), 'enforce-debug.log');
-                    const logEnforce = (msg) => {
-                        void fsp
-                            .appendFile(enforceLogPath, `${new Date().toISOString()} ${msg}\n`)
-                            .catch(() => { });
-                    };
+                    const logEnforce = makeDebugAppender(path.join(tasksDir(cwd2), 'enforce-debug.log'));
                     logEnforce(`=== enforce start: ${taskTitle} ===`);
                     const stopLoader = startAutoLoader(enforceCtx, () => ({
                         title: taskTitle,
@@ -587,8 +587,9 @@ export function buildGateDeps(params) {
                             // literally-identical call repeated past threshold does.
                             loop: { pathThreshold: Number.POSITIVE_INFINITY },
                             onLine: line => {
+                                // `lastLine` drives the live widget, not the trail.
                                 lastLine = line;
-                                logEnforce(line);
+                                logEnforce(line, 'stream');
                             },
                             onContextUsage: snapshot => {
                                 contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
@@ -666,9 +667,7 @@ export function buildGateDeps(params) {
                 // resolves; the remainder is injected under rule 4e, whose point is
                 // that such a path breaks the BUILD — so the checks that would have
                 // caught it report nothing rather than failing.
-                foreignPathProbe: () => collectForeignPathFindings(cwd2, signal, msg => void fsp
-                    .appendFile(path.join(tasksDir(cwd2), 'verify-debug.log'), `${new Date().toISOString()} ${msg}\n`)
-                    .catch(() => { })),
+                foreignPathProbe: () => collectForeignPathFindings(cwd2, signal, makeDebugAppender(path.join(tasksDir(cwd2), 'verify-debug.log'))),
                 // Deterministic neutered-check-script probe (mx5 run 13 PROMPT 4
                 // item 4): a check script this task authored that cannot fail
                 // (`… || true`, an inverted-grep launder). Injected under rule 4f,
@@ -785,11 +784,7 @@ export function buildGateDeps(params) {
             // preserve registry), never a per-task union.
             treeChanges: () => collectTreeChanges(cwd2, signal),
             probeScan: () => collectAddedLines(cwd2, signal).then(findProbeGaming),
-            log: msg => {
-                void fsp
-                    .appendFile(path.join(tasksDir(cwd2), 'final-gate-debug.log'), `${new Date().toISOString()} ${msg}\n`)
-                    .catch(() => { });
-            }
+            log: makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))
         }),
         recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {
             // Read the same composed spec the verify gate judged against, so the

package/dist/task/orchestrator.js

@@ -28,6 +28,7 @@ import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.
 import { publishViewer, publishNotify, publishLifecycleNotice, registerBridgeCommand, getBridge, SessionUI } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
+import { gateDebugWriter } from './debug-log.js';
 import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
 import { buildGateDeps } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
@@ -191,13 +192,15 @@ export class TaskRunner {
             await this._onStart(id);
         // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
         const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
-        this._deps.logDebug = (msg) => {
+        // Left UNSET at level `off`, so the ~39 `logDebug?.(…)` sites downstream
+        // short-circuit before they format a string and the file is never created.
+        this._deps.logDebug = gateDebugWriter((msg) => {
             const line = `${new Date().toISOString()} ${msg}\n`;
             fsp.appendFile(debugLogPath, line).catch(() => {
                 /* ignore */
             });
-        };
-        this._deps.logDebug(`run: start phase=${resumePhase}`);
+        });
+        this._deps.logDebug?.(`run: start phase=${resumePhase}`);
         // Register as active.
         this._widgetState.taskId = id;
         this._widgetState.title = title;

package/dist/task/phases.js

@@ -630,7 +630,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             ...(spec.tools ? { tools: spec.tools } : {}),
             ...(spec.extensions ? { extensions: spec.extensions } : {}),
             onLine: line => {
-                deps.logDebug?.(`${spec.label}: ${line}`);
+                // The one 'stream' site in this file: raw research-worker
+                // output. Every other logDebug here records a decision.
+                // onChildOutput drives the widget and is not gated.
+                deps.logDebug?.(`${spec.label}: ${line}`, 'stream');
                 deps.onChildOutput?.(`${spec.label}: ${line}`);
             }
         }));

package/package.json

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