@mjasnikovs/pi-task 0.22.0 → 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/task/auto-orchestrator.js

@@ -38,6 +38,7 @@ 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';
@@ -122,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 })

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/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.22.0",
+    "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",