@bermudi/pi-delegate 0.1.3 → 0.1.6

package/README.md

@@ -38,6 +38,31 @@ Parent extension/MCP tools are not copied, and project instructions are rebuilt
 for the task's `cwd`. Omit `agent` when you want an ad-hoc task using delegate's
 normal inline defaults instead.
 
+### Disposable scratch workspace
+
+For review, tests, or other commands whose project changes should be thrown
+away, run a one-shot task in a CoW copy:
+
+```ts
+delegate({
+  tasks: [
+    { prompt: "Review this change and run its tests", workspace: "scratch" },
+  ],
+});
+```
+
+Delegate reflink-copies the containing Git repository beside the original, runs
+the subagent in the corresponding copied directory, then deletes the copy. It
+requires Linux with `/proc/self/fd`, GNU `cp`, and a reflink-capable filesystem
+such as Btrfs; it never falls back to an expensive full copy. Scratch mode
+cannot use `sessionId`,
+`resumeFrom`, session actions, linked Git worktrees, or project symlinks that
+point outside the copied tree.
+
+This protects the real project from ordinary relative writes. It is not a
+security sandbox: unrestricted commands and absolute paths can still reach the
+host filesystem.
+
 ### Token accounting
 
 Sync delegate calls report aggregate subagent `Usage` on the tool result, so Pi
@@ -98,7 +123,8 @@ over an installed extension.
 
 - **Delegate task** — One item in `delegate({ tasks: [...] })`. This is the
   core unit of work: a prompt plus optional overrides such as `agent`, `tools`,
-  `systemPrompt`, `thinking`, `cwd`, `context`, `sessionId`, or `resumeFrom`.
+  `systemPrompt`, `thinking`, `cwd`, `context`, `workspace`, `sessionId`, or
+  `resumeFrom`.
   `model` is also accepted but should be rare — subagents inherit the parent
   model by default.
 - **Default subagent** — The reserved built-in `agent: "default"` profile. It

package/config.ts

@@ -131,7 +131,7 @@ function normalizeProviderExtensions(
 // `providerExtensions` replaces a provider's entries (it does not append); an
 // empty array is ignored so the default persists.
 const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> = {
-  "openai-codex": ["npm:@ogulcancelik/pi-codex-compaction"],
+  "openai-codex": ["git:github.com/bermudi/manaflow-pi-codex"],
 };
 
 function resolveProviderExtensions(

package/delegate.ts

@@ -3,6 +3,7 @@ export { default } from "./extension.ts";
 export type {
   AgentConfig,
   SessionAction,
+  WorkspaceMode,
   TicketAction,
   DelegateAction,
   DelegateArguments,
@@ -77,6 +78,8 @@ export {
   isCrossLeafTicket,
 } from "./leaf.ts";
 export { runAgentSession } from "./runner.ts";
+export { createScratchWorkspace } from "./workspace.ts";
+export type { ScratchWorkspace } from "./workspace.ts";
 export {
   activeTicketSummary,
   buildStatusText,

package/format.ts

@@ -7,6 +7,7 @@ import type {
   TaskProgress,
   TaskResult,
   ToolActivity,
+  WorkspaceMode,
 } from "./types.ts";
 
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -517,7 +518,10 @@ export function relativeTouchedSummary(
  *  in the same repository do not fabricate false conflicts from shared
  *  repository-wide git snapshots. */
 export function findTouchedOverlaps(
-  results: readonly { attributedFiles?: string[] }[],
+  results: readonly {
+    attributedFiles?: string[];
+    workspace?: WorkspaceMode;
+  }[],
 ): string[] {
   const counts = new Map<string, number>();
   for (const r of results) {

package/host-compat.ts

@@ -23,6 +23,7 @@ const REQUIRED_EXPORTS: ExportCheck[] = [
   { name: "SettingsManager", requiredMember: "create" },
   { name: "SessionManager", requiredMember: "create" },
   { name: "SessionManager", requiredMember: "open" },
+  { name: "SessionManager", requiredMember: "inMemory" },
   { name: "DefaultResourceLoader" },
   { name: "DefaultPackageManager" },
   { name: "createAgentSession" },

package/lifecycle.ts

@@ -28,6 +28,7 @@ import { getWholeTaskMaxRetries, getWholeTaskBaseDelayMs } from "./config.ts";
 import { addUsage, emptyUsage } from "./usage.ts";
 import { scheduleDeadline } from "./timer.ts";
 import { recordTask } from "./telemetry.ts";
+import { createScratchWorkspace, ScratchDeadlineError } from "./workspace.ts";
 
 /** Internal seam for lifecycle-level tests without replacing session ownership. */
 type RunAgentSession = typeof runAgentSession;
@@ -181,6 +182,11 @@ function updateProgressFromResult(p: TaskProgress, r: TaskResult): void {
   p.failureKind = r.failureKind;
 }
 
+const taskRetryCounts = new WeakMap<TaskResult, number>();
+/** The SQLite task id is part of the logical task, not the transient result
+ * object. Scratch wrapping clones results, so keep this alongside retry data. */
+const taskTelemetryIds = new WeakMap<TaskResult, string>();
+
 /** Apply a TaskResult to progress and notify the env (sync fires onUpdate).
  *  Used at every return point in runResolvedTask — mirrors the old fire() pattern
  *  that the duplicated sync/async bodies used after every early-return. */
@@ -192,8 +198,9 @@ function finishTask(
   retries = 0,
 ): TaskResult {
   updateProgressFromResult(p, r);
+  taskRetryCounts.set(r, retries);
   if (env.telemetryCallId) {
-    recordTask({
+    const id = recordTask({
       callId: env.telemetryCallId,
       generation: env.telemetryGeneration,
       async: env.async ?? false,
@@ -203,6 +210,7 @@ function finishTask(
       result: r,
       retries,
     });
+    if (id) taskTelemetryIds.set(r, id);
   }
   env.onStatusChange?.();
   return r;
@@ -494,15 +502,24 @@ async function acquireAgentSession(
   }
 
   // ── Fresh session (no resume) ────────────────────────────────────────────
-  const fresh = createSubagentSessionManager(
-    env.parentSessionManager,
-    task.cwd,
-  );
-  if (!fresh) {
-    return { error: failTask(task, "Internal: could not create session file") };
+  if (task.workspace === "scratch") {
+    // A discarded filesystem must not advertise a resumable conversation: a
+    // later resume would run against the source cwd and silently lose scratch
+    // isolation. Keep scratch transcripts in memory only.
+    sessionManager = SessionManager.inMemory(task.cwd);
+  } else {
+    const fresh = createSubagentSessionManager(
+      env.parentSessionManager,
+      task.cwd,
+    );
+    if (!fresh) {
+      return {
+        error: failTask(task, "Internal: could not create session file"),
+      };
+    }
+    sessionManager = fresh.manager;
+    sessionFile = fresh.file;
   }
-  sessionManager = fresh.manager;
-  sessionFile = fresh.file;
 
   const session = await buildDelegateSession(
     task,
@@ -564,6 +581,166 @@ async function runResolvedTaskUnlocked(
   task: ResolvedTask,
   p: TaskProgress,
   taskIndex: number,
+): Promise<TaskResult> {
+  if (task.workspace !== "scratch") {
+    return runResolvedTaskCore(env, task, p, taskIndex);
+  }
+  if (task.sessionId || task.resumeFrom || task.sessionAction) {
+    return finishTask(
+      env,
+      p,
+      failTask(
+        task,
+        "workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.",
+      ),
+      task,
+    );
+  }
+
+  const startedAt = Date.now();
+  const deadlineAt =
+    task.deadlineMs && task.deadlineMs > 0
+      ? startedAt + task.deadlineMs
+      : undefined;
+  let workspace: Awaited<ReturnType<typeof createScratchWorkspace>>;
+  try {
+    workspace = await createScratchWorkspace(task.cwd, env.signal, deadlineAt);
+  } catch (error) {
+    const setupError = error instanceof Error ? error.message : String(error);
+    const deadlineExceeded =
+      !env.signal?.aborted && error instanceof ScratchDeadlineError;
+    return finishTask(
+      env,
+      p,
+      {
+        ...failTask(
+          task,
+          env.signal?.aborted
+            ? "Aborted"
+            : deadlineExceeded
+              ? formatDeadlineExceededError(task.deadlineMs ?? 0)
+              : setupError,
+        ),
+        failureKind: deadlineExceeded ? "deadline_exceeded" : undefined,
+        durationMs: Date.now() - startedAt,
+      },
+      task,
+    );
+  }
+
+  const executionTask: ResolvedTask = {
+    ...task,
+    cwd: workspace.cwd,
+  };
+  let result: TaskResult | undefined;
+  let cleanupError: string | undefined;
+  let needsCorrection = false;
+  let telemetryTaskId: string | undefined;
+  let retries = 0;
+  try {
+    const preMappingResult = await runResolvedTaskCore(
+      env,
+      executionTask,
+      p,
+      taskIndex,
+      {
+        taskStartedAt: startedAt,
+        deadlineAt,
+      },
+    );
+    result = preMappingResult;
+    // Capture metadata before scratch wrapping creates a new result object.
+    // Both values belong to the logical task and must survive that clone.
+    telemetryTaskId = taskTelemetryIds.get(result);
+    retries = taskRetryCounts.get(result) ?? 0;
+    result = {
+      ...result,
+      workspace: "scratch",
+      sessionFile: undefined,
+      touchedFiles: await Promise.all(
+        result.touchedFiles.map((file) => workspace.resolveReportedPath(file)),
+      ),
+      // Writes inside scratch are discarded and cannot conflict. Explicit
+      // writes outside scratch (for example an absolute host path) persist and
+      // must remain attributable for overlap warnings. Resolve those paths
+      // physically so aliases to the same host file compare equally.
+      attributedFiles: (
+        await Promise.all(
+          (result.attributedFiles ?? []).map((file) =>
+            workspace.resolveAttributedPath(file),
+          ),
+        )
+      ).filter((file): file is string => file !== undefined),
+    };
+  } catch (error) {
+    result = {
+      ...failTask(task, error instanceof Error ? error.message : String(error)),
+      ...(result
+        ? {
+            tokens: result.tokens,
+            usage: result.usage,
+          }
+        : {}),
+      workspace: "scratch",
+      durationMs: Date.now() - startedAt,
+    };
+    // runResolvedTaskCore may already have recorded/notified a successful
+    // result before path mapping failed. Correct those observable outcomes.
+    needsCorrection = true;
+  } finally {
+    try {
+      await workspace.cleanup();
+    } catch (error) {
+      cleanupError = `Scratch workspace cleanup failed: ${error instanceof Error ? error.message : String(error)}`;
+      console.error("[delegate] scratch workspace cleanup failed", error);
+    }
+  }
+
+  if (!result) {
+    result = {
+      ...failTask(task, "Scratch task failed before producing a result."),
+      workspace: "scratch",
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  if (cleanupError || needsCorrection) {
+    result = {
+      ...result,
+      error: cleanupError
+        ? result.error
+          ? `${result.error}\n${cleanupError}`
+          : cleanupError
+        : result.error,
+      durationMs: Math.max(result.durationMs, Date.now() - startedAt),
+    };
+    updateProgressFromResult(p, result);
+    if (env.telemetryCallId) {
+      // runResolvedTaskCore already recorded the pre-cleanup result. Telemetry
+      // rows are upserts, so replace it with the actual returned outcome while
+      // preserving the retry count captured by finishTask.
+      recordTask({
+        id: telemetryTaskId,
+        callId: env.telemetryCallId,
+        generation: env.telemetryGeneration,
+        async: env.async ?? false,
+        taskIndex: p.index,
+        task,
+        progress: p,
+        result,
+        retries,
+      });
+    }
+    env.onStatusChange?.();
+  }
+  return result;
+}
+
+async function runResolvedTaskCore(
+  env: TaskRunEnv,
+  task: ResolvedTask,
+  p: TaskProgress,
+  taskIndex: number,
+  timing?: { taskStartedAt: number; deadlineAt: number | undefined },
 ): Promise<TaskResult> {
   try {
     // ── Aborted before we started? ───────────────────────────────────
@@ -629,11 +806,12 @@ async function runResolvedTaskUnlocked(
     let hasBashExecution = false;
     let cumulativeTokens = 0;
     let cumulativeToolUses = 0;
-    const taskStartedAt = Date.now();
+    const taskStartedAt = timing?.taskStartedAt ?? Date.now();
     const deadlineAt =
-      task.deadlineMs && task.deadlineMs > 0
+      timing?.deadlineAt ??
+      (task.deadlineMs && task.deadlineMs > 0
         ? taskStartedAt + task.deadlineMs
-        : undefined;
+        : undefined);
     let accumulatedUsage = emptyUsage();
 
     const onAttemptProgress = (u: AgentProgressUpdate): void => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/schema.ts

@@ -103,6 +103,13 @@ export const delegateTaskSchema = Type.Object({
         "Wall-clock budget (ms) from run start after queueing. Cooperative abort; side effects remain. Omit disables.",
     }),
   ),
+  workspace: Type.Optional(
+    StringEnum(["shared", "scratch"], {
+      description:
+        "scratch=disposable CoW project copy; relative edits are discarded. Not security isolation. Default=shared.",
+      default: "shared",
+    }),
+  ),
 });
 
 // Single source of truth for registration and generated help. The exported
@@ -146,7 +153,7 @@ export const delegateArgumentsSchema = Type.Object({
     Type.Array(delegateTaskSchema, {
       minItems: 0,
       description:
-        "Tasks share the real filesystem and run concurrently; separate dependent/shared-file work. []=full manual.",
+        "Tasks run concurrently; shared workspaces share files. scratch uses a disposable CoW copy. []=full manual.",
     }),
   ),
 });
@@ -167,6 +174,7 @@ const TASK_FIELD_NAMES = [
   "sessionAction",
   "resumeFrom",
   "deadlineMs",
+  "workspace",
 ] as const;
 
 /** Every field a task entry may carry. Anything else is a model mistake —
@@ -317,6 +325,12 @@ export function validateDelegateOperation(
     if (typeof rawTask.deadlineMs === "number" && !(rawTask.deadlineMs > 0)) {
       return `task ${index + 1}: deadlineMs must be a positive number of milliseconds.`;
     }
+    if (
+      task.workspace === "scratch" &&
+      (task.sessionId || task.resumeFrom || sessionAction !== undefined)
+    ) {
+      return `task ${index + 1}: workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.`;
+    }
     if (sessionAction === "close") {
       if (!task.sessionId) {
         return `task ${index + 1}: sessionAction 'close' requires sessionId.`;

package/task-resolution.ts

@@ -208,6 +208,11 @@ export function resolveTasks(
     );
     let tools: string[] = [];
     const warnings: string[] = [];
+    if (t.workspace === "scratch") {
+      warnings.push(
+        "Scratch workspace: relative file changes run in a disposable CoW copy and are discarded.",
+      );
+    }
 
     // Prompt is required for fresh tasks. ResumeFrom provides context already.
     if (
@@ -418,6 +423,7 @@ export function resolveTasks(
       ...t,
       id: t.id,
       cwd,
+      workspace: t.workspace ?? "shared",
       systemPrompt,
       model: model!,
       tools,

package/telemetry.ts

@@ -604,6 +604,8 @@ export function recordCall(record: CallRecord, generation?: number): void {
 }
 
 export interface TaskSpanInput {
+  /** Stable identity for correction writes of the same logical task row. */
+  id?: string;
   callId: string;
   /** Runtime generation captured by the dispatch that owns this task. */
   generation?: number;
@@ -622,13 +624,15 @@ function outcomeFromResult(result: TaskResult): string {
   return "success";
 }
 
-export function recordTask(input: TaskSpanInput): void {
+export function recordTask(input: TaskSpanInput): string | undefined {
   const b = getBackend(input.generation);
-  if (!b) return;
+  if (!b) return undefined;
 
   const { callId, async, taskIndex, task, progress, result, retries } = input;
   const record: TaskRecord = {
-    id: crypto.randomUUID(),
+    // Correction writes must reuse the provisional row's primary key. A fresh
+    // UUID here would make INSERT OR REPLACE append a second task row.
+    id: input.id ?? crypto.randomUUID(),
     call_id: callId,
     ts: Date.now(),
     version: getDelegateVersion(),
@@ -651,6 +655,7 @@ export function recordTask(input: TaskSpanInput): void {
     async: async ? 1 : 0,
   };
   b.recordTask(record);
+  return record.id;
 }
 
 /** Prevent this runtime's late workers from writing after a bounded shutdown

package/types.ts

@@ -43,6 +43,8 @@ export type TicketAction = NonNullable<
 >;
 /** Per-task session action: "prompt" | "close" | "list". */
 export type SessionAction = NonNullable<CanonicalTaskDef["sessionAction"]>;
+/** Filesystem mode: shared source tree or an ephemeral CoW scratch copy. */
+export type WorkspaceMode = NonNullable<CanonicalTaskDef["workspace"]>;
 
 export type TaskDef = CanonicalTaskDef & {
   /** @deprecated Use `sessionAction` instead. Runtime normalization still accepts this alias. */
@@ -123,6 +125,7 @@ export interface ResolvedTask {
   thinking: ThinkingLevel;
   systemPrompt: string;
   cwd: string;
+  workspace?: WorkspaceMode;
   context?: "fresh" | "with-parent-transcript";
   sessionId?: string;
   sessionAction?: SessionAction;
@@ -211,6 +214,8 @@ export interface TaskResult {
    *  stay 0 because `getSessionStats()` exposes only the aggregate cost — and
    *  Pi sums `cost.total` for nested usage anyway. */
   usage: Usage;
+  /** Scratch results are excluded from shared-file conflict detection and never resumable. */
+  workspace?: WorkspaceMode;
   sessionFile?: string;
   /** All files the subagent is known to have touched, including bash mutations
    *  captured via git diff and other tasks' concurrent git changes. This is a