@mjasnikovs/pi-task 0.42.0 → 0.42.2

package/dist/index.js

@@ -7,6 +7,7 @@ import { registerRemote } from './remote/register.js';
 import { registerCommandWatchdog } from './task/command-watchdog.js';
 import { registerStreamWatchdog } from './task/stream-watchdog.js';
 import { registerImplementationGuards } from './task/implementation-guards.js';
+import { registerTaskDirCustody } from './task/task-dir-custody.js';
 import { registerModelHoldRestore } from './task/model-hold-stash.js';
 export default function (pi) {
     registerConfig(pi);
@@ -18,5 +19,6 @@ export default function (pi) {
     registerCommandWatchdog(pi);
     registerStreamWatchdog(pi);
     registerImplementationGuards(pi);
+    registerTaskDirCustody(pi);
     registerModelHoldRestore(pi);
 }

package/dist/task/gate-child.js

@@ -27,6 +27,7 @@
 import { formatLoopHint } from './loop-detector.js';
 import { classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { notifyRun } from '../remote/bridge.js';
+import { restoreTaskDir, snapshotTaskDir, taskDirRestoredNotice } from './task-dir-custody.js';
 /**
  * What each kind may do. Adding a child is a row; it cannot be added without
  * deciding all four questions, which is the point.
@@ -69,6 +70,9 @@ export function makeGateChild(deps) {
         const log = deps.makeDebugAppender(deps.logPath);
         log(`=== ${deps.kind} start: ${deps.taskTitle} ===`);
         const guardSnapshot = row.guarded ? await deps.captureGitState(deps.cwd, sig) : null;
+        // Every kind, whatever its tools: the git-state guard and the discard both
+        // leave `.pi-tasks` alone.
+        const taskDir = await snapshotTaskDir(deps.cwd);
         const frame = deps.loader === false ?
             null
             : () => ({
@@ -132,6 +136,12 @@ export function makeGateChild(deps) {
             finally {
                 // Restore whatever the child moved BEFORE any verdict or failure is
                 // acted on — a crashed child must not skip the restore either.
+                const restored = await restoreTaskDir(deps.cwd, taskDir);
+                if (restored.length > 0) {
+                    log(`=== ${deps.kind} TASK-DIR CUSTODY — restored: ${restored.join(', ')} ===`);
+                    notifyRun(deps.ctx, `${deps.taskTitle}: `
+                        + taskDirRestoredNotice(`the ${deps.kind} child`, restored), 'warning');
+                }
                 if (guardSnapshot) {
                     const rec = await deps.reconcileGitState(deps.cwd, guardSnapshot, sig);
                     deps.onReconcile?.(rec);

package/dist/task/implementation-scope.d.ts

@@ -1,8 +1,8 @@
 /**
- * The implementation-turn bracket: one entry arms both the status widget and the
- * runaway guard, one `leave` disarms both.
+ * The implementation-turn bracket: one entry arms the status widget and the
+ * runaway guard and takes custody of the task dir, one `leave` ends all three.
  *
- * The two modules keep their own lifecycle handlers, and they draw the turn
+ * Each module keeps its own lifecycle handlers, and the first two draw the turn
  * boundary differently on purpose: the widget hides on `agent_end` (a sub-turn is
  * over, the screen should say so), the guard survives until `agent_settled`
  * (compactions and retries fire `agent_end` INSIDE a turn — see its header). What
@@ -13,12 +13,14 @@
 import { type ImplWidgetMeta } from './impl-widget.js';
 /**
  * `oneShot` true (fire-and-forget /task) lets each module's own settle handler
- * disarm after the single turn; false (awaited /task-auto) keeps both armed
+ * end it after the single turn; false (awaited /task-auto) keeps all three
  * across resume and steer turns until `leave` is called.
  *
  * `leave` is idempotent: a second call is a no-op, so a caller can put it in a
- * `finally` and a `catch` without disarming a bracket entered since.
+ * `finally` and a `catch` without ending a bracket entered since. It resolves to
+ * the task files it restored.
  */
 export declare function enterImplementationTurn(meta: ImplWidgetMeta, opts: {
     oneShot: boolean;
-}): () => void;
+    cwd: string;
+}): Promise<() => Promise<string[]>>;

package/dist/task/implementation-scope.js

@@ -1,8 +1,8 @@
 /**
- * The implementation-turn bracket: one entry arms both the status widget and the
- * runaway guard, one `leave` disarms both.
+ * The implementation-turn bracket: one entry arms the status widget and the
+ * runaway guard and takes custody of the task dir, one `leave` ends all three.
  *
- * The two modules keep their own lifecycle handlers, and they draw the turn
+ * Each module keeps its own lifecycle handlers, and the first two draw the turn
  * boundary differently on purpose: the widget hides on `agent_end` (a sub-turn is
  * over, the screen should say so), the guard survives until `agent_settled`
  * (compactions and retries fire `agent_end` INSIDE a turn — see its header). What
@@ -12,23 +12,28 @@
  */
 import { armImplWidget, disarmImplWidget } from './impl-widget.js';
 import { armImplementationGuard, disarmImplementationGuard } from './implementation-guards.js';
+import { takeTaskDirCustody } from './task-dir-custody.js';
 /**
  * `oneShot` true (fire-and-forget /task) lets each module's own settle handler
- * disarm after the single turn; false (awaited /task-auto) keeps both armed
+ * end it after the single turn; false (awaited /task-auto) keeps all three
  * across resume and steer turns until `leave` is called.
  *
  * `leave` is idempotent: a second call is a no-op, so a caller can put it in a
- * `finally` and a `catch` without disarming a bracket entered since.
+ * `finally` and a `catch` without ending a bracket entered since. It resolves to
+ * the task files it restored.
  */
-export function enterImplementationTurn(meta, opts) {
-    armImplWidget(meta, opts);
-    armImplementationGuard(opts);
+export async function enterImplementationTurn(meta, opts) {
+    const { oneShot } = opts;
+    const releaseTaskDir = await takeTaskDirCustody(opts.cwd, { oneShot });
+    armImplWidget(meta, { oneShot });
+    armImplementationGuard({ oneShot });
     let left = false;
-    return () => {
+    return async () => {
         if (left)
-            return;
+            return [];
         left = true;
         disarmImplWidget();
         disarmImplementationGuard();
+        return releaseTaskDir();
     };
 }

package/dist/task/orchestrator.d.ts

@@ -178,6 +178,7 @@ export declare class TaskRunner {
      */
     private _recordHandoff;
     private _deliverSpec;
+    private _reportRestored;
     /**
      * The spec as the implementer should receive it (Layer B). Layer A strips phantom
      * specifiers from the upstream pipeline text, but a residual affirmative can survive

package/dist/task/orchestrator.js

@@ -27,7 +27,8 @@ import { allocateTaskId, ensureTasksDir, mergeTaskSection, readSection, readTask
 import { startWidget } from './widget.js';
 import { setupImplWidget } from './impl-widget.js';
 import { enterImplementationTurn } from './implementation-scope.js';
-import { SessionUI, publishNotify, registerBridgeCommand, getBridge, notifyBoth, isRemoteOrigin } from '../remote/bridge.js';
+import { taskDirRestoredNotice } from './task-dir-custody.js';
+import { SessionUI, publishNotify, registerBridgeCommand, getBridge, notifyBoth, notifyRun, isRemoteOrigin } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
 import { appendDebugLine, gateDebugWriter } from './debug-log.js';
@@ -473,7 +474,10 @@ export class TaskRunner {
             label: this._widgetState.label
         };
         if (this._sendSpec) {
-            const leave = enterImplementationTurn(meta, { oneShot: !this._implAwaited });
+            const leave = await enterImplementationTurn(meta, {
+                oneShot: !this._implAwaited,
+                cwd: this._cwd
+            });
             let delivered = false;
             try {
                 await this._sendSpec(spec);
@@ -486,14 +490,14 @@ export class TaskRunner {
                 // missing model, or a failed auth. The next unrelated turn would
                 // inherit it, and this guard can end a turn outright.
                 if (this._implAwaited || !delivered)
-                    leave();
+                    this._reportRestored(await leave());
             }
             return;
         }
         if (!piApi) {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
-        const leave = enterImplementationTurn(meta, { oneShot: true });
+        const leave = await enterImplementationTurn(meta, { oneShot: true, cwd: this._cwd });
         // Same reason as the awaited path's `delivered` flag: this send can throw
         // SYNCHRONOUSLY — the loader gates every ExtensionAPI action behind
         // `assertActive()` — and a guard left armed over a turn that never starts
@@ -507,10 +511,17 @@ export class TaskRunner {
             piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
         }
         catch (e) {
-            leave();
+            await leave();
             throw e;
         }
     }
+    _reportRestored(names) {
+        if (names.length === 0)
+            return;
+        const notice = taskDirRestoredNotice('The implementation turn', names);
+        this._deps.logDebug?.(notice);
+        notifyRun(this._ctx, notice, 'warning');
+    }
     /**
      * The spec as the implementer should receive it (Layer B). Layer A strips phantom
      * specifiers from the upstream pipeline text, but a residual affirmative can survive

package/dist/task/task-dir-custody.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/** File name → bytes, for the held files only. */
+export type TaskDirSnapshot = ReadonlyMap<string, Buffer>;
+export declare function snapshotTaskDir(cwd: string): Promise<TaskDirSnapshot>;
+/** Rewrite every snapshotted file that changed or is gone. Never throws.
+ *  Returns the names it put back, sorted. */
+export declare function restoreTaskDir(cwd: string, snapshot: TaskDirSnapshot): Promise<string[]>;
+export declare function taskDirRestoredNotice(who: string, names: readonly string[]): string;
+/**
+ * Snapshot before the turn can start, replacing any custody still held.
+ * `oneShot` means the settle ends it; otherwise the returned release does, and
+ * it never releases a custody taken since.
+ */
+export declare function takeTaskDirCustody(cwd: string, opts: {
+    oneShot: boolean;
+}): Promise<() => Promise<string[]>>;
+export declare function releaseTaskDirCustody(): Promise<string[]>;
+/** @internal Test seam: is a turn's task dir held? */
+export declare function taskDirCustodyHeld(): boolean;
+/**
+ * pi awaits these handlers before it wakes a command waiting for idle, so a
+ * one-shot restore finishes before the next run writes anything.
+ */
+export declare function registerTaskDirCustody(pi: ExtensionAPI): void;

package/dist/task/task-dir-custody.js

@@ -0,0 +1,100 @@
+/**
+ * Custody of the task dir while a model can write to it.
+ *
+ * Every markdown file in `.pi-tasks/` is host state. A model reaches it through
+ * edit, write or bash, and pi rewrites a path before it writes (`@x`, `file://`),
+ * so a rule on the tool call sees only some of the writers. The host snapshots
+ * the files before the model runs and puts back whatever changed. MEASURED: an
+ * mx5 implementer wrote its report over TASK_AUTO_0001.md, and the run died on
+ * its front matter.
+ *
+ * Only markdown is held: pi-task's own tools write research-cache.json mid-turn.
+ * A file created in the window is kept, because a run started meanwhile
+ * allocates its own.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { notifyRun } from '../remote/bridge.js';
+import { tasksDir } from './task-io.js';
+import { TASKS_DIR_NAME } from './task-types.js';
+export async function snapshotTaskDir(cwd) {
+    const dir = tasksDir(cwd);
+    const out = new Map();
+    const entries = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith('.md'))
+            continue;
+        const bytes = await fsp.readFile(path.join(dir, e.name)).catch(() => null);
+        if (bytes)
+            out.set(e.name, bytes);
+    }
+    return out;
+}
+/** Rewrite every snapshotted file that changed or is gone. Never throws.
+ *  Returns the names it put back, sorted. */
+export async function restoreTaskDir(cwd, snapshot) {
+    const dir = tasksDir(cwd);
+    const restored = [];
+    for (const [name, bytes] of snapshot) {
+        const file = path.join(dir, name);
+        const now = await fsp.readFile(file).catch(() => null);
+        if (now?.equals(bytes))
+            continue;
+        try {
+            await fsp.mkdir(dir, { recursive: true });
+            await fsp.writeFile(file, bytes);
+            restored.push(name);
+        }
+        catch {
+            // The host's next read of this file reports what is still wrong.
+        }
+    }
+    return restored.sort();
+}
+export function taskDirRestoredNotice(who, names) {
+    const list = names.map(n => `${TASKS_DIR_NAME}/${n}`).join(', ');
+    return `${who} changed ${list}, which only pi-task writes. Restored.`;
+}
+/** The implementation turn's custody. One slot: one task runs at a time. */
+let held = null;
+async function release(custody) {
+    if (held !== custody)
+        return [];
+    held = null;
+    return restoreTaskDir(custody.cwd, custody.snapshot);
+}
+/**
+ * Snapshot before the turn can start, replacing any custody still held.
+ * `oneShot` means the settle ends it; otherwise the returned release does, and
+ * it never releases a custody taken since.
+ */
+export async function takeTaskDirCustody(cwd, opts) {
+    const custody = { cwd, snapshot: await snapshotTaskDir(cwd), oneShot: opts.oneShot };
+    held = custody;
+    return () => release(custody);
+}
+export function releaseTaskDirCustody() {
+    return held ? release(held) : Promise.resolve([]);
+}
+/** @internal Test seam: is a turn's task dir held? */
+export function taskDirCustodyHeld() {
+    return held !== null;
+}
+/**
+ * pi awaits these handlers before it wakes a command waiting for idle, so a
+ * one-shot restore finishes before the next run writes anything.
+ */
+export function registerTaskDirCustody(pi) {
+    pi.on('agent_settled', async (_event, ctx) => {
+        if (!held?.oneShot)
+            return;
+        const restored = await releaseTaskDirCustody();
+        if (restored.length === 0)
+            return;
+        notifyRun(ctx, taskDirRestoredNotice('The implementation turn', restored), 'warning');
+    });
+    // Dropped, not restored: a snapshot this old would revert the next run's writes.
+    pi.on('session_shutdown', () => {
+        held = null;
+    });
+}

package/package.json

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