@bermudi/pi-delegate 0.1.16 → 0.1.17

package/agents.ts

@@ -151,7 +151,7 @@ export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
     systemPrompt:
       "Review the current snapshot for correctness, regressions, security problems, and missing tests. Do not modify the source project. Run focused checks when useful. Report actionable findings ordered by severity, with concrete paths and locations. If there are no material findings, say so plainly; do not invent issues or merely summarize the implementation.",
     builtin: true,
-    workspace: "scratch",
+    workspace: "shared",
   },
 };
 

package/extension.ts

@@ -59,10 +59,14 @@ type ShutdownDrainResult =
 /** Bridge the promoted top-level session RPC (`sessionAction` + `sessionId`)
  * to the internal single-entry batch the runner executes. Internal only — the
  * public task schema has no `sessionAction`; validation guarantees close
- * carries a sessionId by this point. */
+ * carries a sessionId by this point. `list` never carries a sessionId: it does
+ * not target a specific session, and attaching one would make validateTasks
+ * run busy/quarantine checks that can fail the list call. */
 function bridgeSessionControlTask(params: DelegateArguments): DispatchableTask {
   return {
-    ...(params.sessionId ? { sessionId: params.sessionId } : {}),
+    ...(params.sessionAction === "close" && params.sessionId
+      ? { sessionId: params.sessionId }
+      : {}),
     sessionAction: params.sessionAction,
   };
 }
@@ -193,6 +197,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
         mode,
         taskCount,
         parentSessionFile,
+        parentCwd: ctx.cwd,
       });
 
       function failCall(): void {

package/lifecycle.ts

@@ -142,9 +142,18 @@ function scratchSetupFailureResult(
   if (signalAborted) {
     message = "Aborted";
     failureKind = "cancelled";
-  } else if (error instanceof ScratchDeadlineError) {
-    message = formatDeadlineExceededError(task.deadlineMs ?? 0);
-    failureKind = "deadline_exceeded";
+  } else {
+    if (error instanceof ScratchDeadlineError) {
+      message = formatDeadlineExceededError(task.deadlineMs ?? 0);
+      failureKind = "deadline_exceeded";
+    }
+    // Every non-aborted setup failure names its remedy in one place, so the
+    // paths (platform guard, pre-check, reflink, worktree, deadline) cannot
+    // drift. The symlink message already carries remedy text naming
+    // workspace "shared" — skip the append there to avoid saying it twice.
+    if (!message.includes('workspace "shared"')) {
+      message = `${message} — to retry without scratch containment, use workspace: "shared".`;
+    }
   }
   return {
     ...failTask(task, message, undefined, failureKind),
@@ -433,9 +442,10 @@ function recordTaskOutcome(
  *  that model, so same-model retry is pointless. Distinguished from a bare
  *  transient 429 (per-minute rate limit) by the *account-level* wording:
  *  "usage limit", "quota", "upgrade for higher limits", "exceeded your
- *  … quota", or an auth/credential failure (401/403 with word boundaries so a
- *  port like 4019 doesn't false-positive). The parent should resume with a
- *  different `model` (see `resumeFrom` + `model`). */
+ *  … quota", an auth/credential failure (401/403 with word boundaries so a
+ *  port like 4019 doesn't false-positive), or an invalidated OAuth token
+ *  ("invalid"/"invalidated" anywhere alongside "oauth token"). The parent
+ *  should resume with a different `model` (see `resumeFrom` + `model`). */
 export function isModelAttributableError(error: string | undefined): boolean {
   if (!error) return false;
   const e = error.toLowerCase();
@@ -454,6 +464,7 @@ export function isModelAttributableError(error: string | undefined): boolean {
     e.includes("authentication") ||
     e.includes("invalid api key") ||
     (e.includes("api key") && e.includes("invalid")) ||
+    (e.includes("oauth token") && e.includes("invalid")) ||
     /\b401\b/.test(e) ||
     /\b403\b/.test(e)
   );

package/package.json

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

package/schema.ts

@@ -1,8 +1,5 @@
 import { Type, type SchemaOptions } from "@sinclair/typebox";
-import {
-  VALID_THINKING_LEVELS,
-  isSessionControlAction,
-} from "./constants.ts";
+import { VALID_THINKING_LEVELS, isSessionControlAction } from "./constants.ts";
 import type { DelegateArguments } from "./types.ts";
 
 // JSON Schema string enum that keeps the literal union in `Static<>`.
@@ -247,13 +244,33 @@ function validateSessionMode(params: DelegateArguments): string | undefined {
   if (sessionAction === "close" && !params.sessionId) {
     return "sessionAction 'close' requires sessionId.";
   }
-  const foreign = Object.keys(rawParams).filter(
-    (key) => !SESSION_MODE_FIELDS.has(key),
-  );
+  // Skip only fields carrying their documented default/no-op value: a caller
+  // (or a schema validator that materialises defaults) may spell out
+  // `async: false`, `force: false`, or `tasks: []` explicitly. Other false or
+  // empty-array values remain foreign so future fields cannot bypass this mode
+  // boundary merely by sharing the same value shape.
+  const foreign = Object.keys(rawParams).filter((key) => {
+    if (SESSION_MODE_FIELDS.has(key) || rawParams[key] === undefined) {
+      return false;
+    }
+    if ((key === "async" || key === "force") && rawParams[key] === false) {
+      return false;
+    }
+    if (
+      key === "tasks" &&
+      Array.isArray(rawParams[key]) &&
+      rawParams[key].length === 0
+    ) {
+      return false;
+    }
+    return true;
+  });
   if (foreign.length) {
     return `sessionAction '${sessionAction}' cannot be combined with ${foreign
       .map((field) => `'${field}'`)
-      .join(", ")}; run it alone — a session action takes only 'sessionAction' (plus 'sessionId' for 'close').`;
+      .join(
+        ", ",
+      )}; run it alone — a session action takes only 'sessionAction' (plus 'sessionId' for 'close').`;
   }
   return undefined;
 }

package/telemetry.ts

@@ -7,7 +7,12 @@ import * as crypto from "node:crypto";
 import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import type { DatabaseSync, StatementSync } from "node:sqlite";
 import { getTelemetryConfig } from "./config.ts";
-import type { ResolvedTask, TaskProgress, TaskResult } from "./types.ts";
+import type {
+  ResolvedTask,
+  TaskProgress,
+  TaskResult,
+  WorkspaceMode,
+} from "./types.ts";
 
 export interface CallRecord {
   id: string;
@@ -22,6 +27,7 @@ export interface CallRecord {
   total_tokens: number;
   total_cost: number;
   parent_session_file: string | undefined;
+  parent_cwd: string | undefined;
 }
 
 export interface TaskRecord {
@@ -35,6 +41,7 @@ export interface TaskRecord {
   model: string | undefined;
   thinking: string | undefined;
   tools: string;
+  workspace: WorkspaceMode | undefined;
   outcome: string;
   failure_kind: string | undefined;
   duration_ms: number;
@@ -46,6 +53,7 @@ export interface TaskRecord {
   output_chars: number;
   session_file: string | undefined;
   async: number;
+  error_snippet: string | undefined;
 }
 
 export interface TelemetryRecorder {
@@ -87,13 +95,32 @@ let telemetryGeneration = 0;
 let telemetryClosed = false;
 let testingRecorder: TelemetryRecorder | undefined;
 
-const TELEMETRY_SCHEMA_VERSION = 1;
+const TELEMETRY_SCHEMA_VERSION = 3;
 const SQLITE_BUSY_TIMEOUT_MS = 5_000;
 
 function defaultDbPath(): string {
   return path.join(os.homedir(), ".pi", "agent", "delegate-usage.db");
 }
 
+/**
+ * Telemetry database path resolution: explicit config wins, then the
+ * DELEGATE_TELEMETRY_DB environment variable, then the default user path.
+ * The env var exists so test runs can redirect the default destination away
+ * from the production database without touching user config — the pi test
+ * harness builds real sessions in-process, so process.env is the extension's
+ * environment (see test-preload.ts). Config beats env on purpose: telemetry
+ * tests drive backends through explicit config dbPath values, including
+ * spawned Node children that inherit this variable.
+ */
+function resolveTelemetryDbPath(
+  config: import("./config.ts").TelemetryConfig,
+): string {
+  if (config.dbPath) return config.dbPath;
+  const fromEnv = process.env.DELEGATE_TELEMETRY_DB;
+  if (fromEnv) return fromEnv;
+  return defaultDbPath();
+}
+
 function findPackageJson(startFile: string): string | undefined {
   const candidates = [
     path.join(path.dirname(startFile), "package.json"),
@@ -175,6 +202,7 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
       ["total_tokens", "INTEGER"],
       ["total_cost", "REAL"],
       ["parent_session_file", "TEXT"],
+      ["parent_cwd", "TEXT"],
     ],
     createSql: `
       CREATE TABLE IF NOT EXISTS calls(
@@ -189,7 +217,8 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
         status TEXT,
         total_tokens INTEGER,
         total_cost REAL,
-        parent_session_file TEXT
+        parent_session_file TEXT,
+        parent_cwd TEXT
       );
     `,
   },
@@ -206,6 +235,7 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
       ["model", "TEXT"],
       ["thinking", "TEXT"],
       ["tools", "TEXT"],
+      ["workspace", "TEXT"],
       ["outcome", "TEXT"],
       ["failure_kind", "TEXT"],
       ["duration_ms", "INTEGER"],
@@ -217,6 +247,7 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
       ["output_chars", "INTEGER"],
       ["session_file", "TEXT"],
       ["async", "INTEGER"],
+      ["error_snippet", "TEXT"],
     ],
     createSql: `
       CREATE TABLE IF NOT EXISTS tasks(
@@ -230,6 +261,7 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
         model TEXT,
         thinking TEXT,
         tools TEXT,
+        workspace TEXT,
         outcome TEXT,
         failure_kind TEXT,
         duration_ms INTEGER,
@@ -240,7 +272,8 @@ const TELEMETRY_TABLES: readonly TelemetryTable[] = [
         prompt_chars INTEGER,
         output_chars INTEGER,
         session_file TEXT,
-        async INTEGER
+        async INTEGER,
+        error_snippet TEXT
       );
     `,
   },
@@ -312,6 +345,26 @@ function initSchema(db: DatabaseSync): void {
       }
     }
 
+    // Backfill legacy rows that predate the workspace column. New rows store
+    // 'shared' explicitly, but ALTER TABLE leaves existing rows as NULL. Without
+    // this, GROUP BY workspace splits NULL vs 'shared' for the same semantics.
+    // Reviewer defaulted to scratch when these rows were recorded, so preserve
+    // that heuristic for historical rows; everything else was shared by
+    // default. This is idempotent and runs inside the same transaction as the schema changes so a crash before COMMIT
+    // retries cleanly.
+    try {
+      db.exec(
+        "UPDATE tasks SET workspace='scratch' WHERE workspace IS NULL AND agent='reviewer'",
+      );
+      db.exec("UPDATE tasks SET workspace='shared' WHERE workspace IS NULL");
+    } catch {
+      // tasks may not exist on first run (fresh DB) or workspace column may
+      // have just been created via CREATE TABLE — UPDATE affecting 0 rows is fine.
+      // Any real error will surface on the next write and disable telemetry
+      // via the existing fail-open path, so swallowing here preserves the
+      // repair-loop's best-effort nature.
+    }
+
     // Set the marker only after every table/column operation succeeded.
     db.exec(`PRAGMA user_version = ${TELEMETRY_SCHEMA_VERSION}`);
     db.exec("COMMIT");
@@ -346,15 +399,16 @@ class SqliteTelemetryBackend implements TelemetryBackend {
     this.insertCall = db.prepare(
       `INSERT OR REPLACE INTO calls(
         id, ts, version, pi_version, mode, parent_model, task_count,
-        wall_ms, status, total_tokens, total_cost, parent_session_file
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        wall_ms, status, total_tokens, total_cost, parent_session_file,
+        parent_cwd
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
     this.insertTask = db.prepare(
       `INSERT OR REPLACE INTO tasks(
         id, call_id, ts, version, pi_version, idx, agent, model, thinking,
-        tools, outcome, failure_kind, duration_ms, tokens, cost, tool_uses,
-        retries, prompt_chars, output_chars, session_file, async
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        tools, workspace, outcome, failure_kind, duration_ms, tokens, cost, tool_uses,
+        retries, prompt_chars, output_chars, session_file, async, error_snippet
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
   }
 
@@ -373,6 +427,7 @@ class SqliteTelemetryBackend implements TelemetryBackend {
         record.total_tokens,
         record.total_cost,
         record.parent_session_file ?? null,
+        record.parent_cwd ?? null,
       );
     } catch (error) {
       this.onFailure("recordCall", error);
@@ -392,6 +447,7 @@ class SqliteTelemetryBackend implements TelemetryBackend {
         record.model ?? null,
         record.thinking ?? null,
         record.tools,
+        record.workspace ?? null,
         record.outcome,
         record.failure_kind ?? null,
         record.duration_ms,
@@ -403,6 +459,7 @@ class SqliteTelemetryBackend implements TelemetryBackend {
         record.output_chars,
         record.session_file ?? null,
         record.async,
+        record.error_snippet ?? null,
       );
     } catch (error) {
       this.onFailure("recordTask", error);
@@ -453,7 +510,7 @@ function backendIdentity(
   config: import("./config.ts").TelemetryConfig,
 ): string | undefined {
   if (config.enabled === false) return undefined;
-  return config.dbPath ?? defaultDbPath();
+  return resolveTelemetryDbPath(config);
 }
 
 function disableActiveBackend(
@@ -495,7 +552,7 @@ function openSqliteBackend(
   if (config.enabled === false || telemetryClosed) return undefined;
   if (!DatabaseSyncCtor) return undefined;
 
-  const dbPath = config.dbPath ?? defaultDbPath();
+  const dbPath = resolveTelemetryDbPath(config);
   let db: DatabaseSync | undefined;
   try {
     fs.mkdirSync(path.dirname(dbPath), { recursive: true });
@@ -587,6 +644,8 @@ export interface CallSpanInput {
   mode: string;
   taskCount: number;
   parentSessionFile?: string;
+  /** Parent working directory at dispatch — one dispatch, one cwd. */
+  parentCwd?: string;
 }
 
 export interface CallSpanFinish {
@@ -637,6 +696,7 @@ class CallSpanImpl implements CallSpan {
       total_tokens: 0,
       total_cost: 0,
       parent_session_file: this.input.parentSessionFile,
+      parent_cwd: this.input.parentCwd,
     };
   }
 
@@ -700,6 +760,19 @@ function outcomeFromResult(result: TaskResult): string {
   return "success";
 }
 
+/** Error text only — never prompt or output content — whitespace-collapsed
+ * and capped, so failure classification becomes a query instead of
+ * duration-based guessing. */
+const ERROR_SNIPPET_MAX_CHARS = 200;
+
+function errorSnippetOf(result: TaskResult): string | undefined {
+  if (!result.error) return undefined;
+  const collapsed = result.error.replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0) return undefined;
+  if (collapsed.length <= ERROR_SNIPPET_MAX_CHARS) return collapsed;
+  return `${collapsed.slice(0, ERROR_SNIPPET_MAX_CHARS - 1)}…`;
+}
+
 export function recordTask(input: TaskSpanInput): string | undefined {
   const b = input.telemetryConfig
     ? getBackendForConfig(
@@ -723,6 +796,7 @@ export function recordTask(input: TaskSpanInput): string | undefined {
     model: task.model?.id,
     thinking: task.thinking,
     tools: JSON.stringify(task.tools),
+    workspace: task.workspace ?? "shared",
     outcome: outcomeFromResult(result),
     failure_kind: result.failureKind,
     duration_ms: result.durationMs,
@@ -734,6 +808,7 @@ export function recordTask(input: TaskSpanInput): string | undefined {
     output_chars: result.output?.length ?? 0,
     session_file: result.sessionFile,
     async: async ? 1 : 0,
+    error_snippet: errorSnippetOf(result),
   };
   b.recordTask(record);
   return record.id;

package/test-preload.ts

@@ -0,0 +1,26 @@
+/**
+ * Test-run telemetry isolation.
+ *
+ * The pi test harness builds real sessions in-process, so this process's
+ * environment IS the extension's environment. telemetry.ts resolves the
+ * database path as config.dbPath > DELEGATE_TELEMETRY_DB > default; setting
+ * the env var here redirects every test that runs on the default path to a
+ * throwaway directory instead of the production ~/.pi/agent/delegate-usage.db.
+ * Tests that set an explicit config dbPath are unaffected (config wins).
+ *
+ * Loaded once per `bun test` invocation via bunfig.toml [test] preload.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), "delegate-telemetry-test-"));
+process.env.DELEGATE_TELEMETRY_DB = path.join(dir, "usage.db");
+
+process.on("exit", () => {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup; a leftover temp dir is harmless.
+  }
+});

package/workspace.ts

@@ -57,6 +57,7 @@ class CommandError extends Error {
   constructor(
     message: string,
     readonly stderr: string,
+    readonly file: string,
     options: ErrorOptions,
   ) {
     super(message, options);
@@ -85,6 +86,7 @@ function runFile(
             new CommandError(
               detail ? `${file}: ${detail}` : `${file}: ${error.message}`,
               detail,
+              file,
               { cause: error },
             ),
           );
@@ -193,10 +195,16 @@ async function replaceSymlink(linkPath: string, target: string): Promise<void> {
   }
 }
 
-/** Validate the completed copy before any subagent receives its path. */
-async function validateCopiedTree(
+/** Validate a scratch candidate tree — the source before copying (read-only
+ * fast-fail) or the completed copy before any subagent receives its path
+ * (authority, with the symlink-retarget side effect). One rule, two timings:
+ * the blockers are identical, so the pre-check cannot drift from the copy
+ * check, and the copy check remains authoritative for trees that change
+ * mid-copy. */
+async function validateScratchTree(
   root: string,
   sourceRoot: string,
+  retargetLinks: boolean,
   signal: AbortSignal,
   parentSignal: AbortSignal | undefined,
 ): Promise<void> {
@@ -234,7 +242,8 @@ async function validateCopiedTree(
       // `cp --archive` copies link text verbatim, so an absolute in-project
       // link (bun/pnpm-style local package installs) still resolves to the
       // real tree from inside the copy. Retarget it at its copied counterpart
-      // instead of failing: the link keeps working and stays disposable.
+      // instead of failing: the link keeps working and stays disposable. The
+      // pre-check runs the same rule read-only against the source.
       const relinked = relinkTargetIntoCopy(
         candidate,
         target,
@@ -242,6 +251,7 @@ async function validateCopiedTree(
         sourceRoot,
       );
       if (relinked !== undefined) {
+        if (!retargetLinks) continue;
         try {
           await replaceSymlink(candidate, relinked);
         } catch (error) {
@@ -262,6 +272,58 @@ async function validateCopiedTree(
   }
 }
 
+/** Reject Git metadata that redirects the worktree or git dirs outside `root`
+ * (core.worktree, commondir pointers, gitdir redirects). Runs against the
+ * source before copying and against the copy afterwards — a source that is
+ * self-consistent can still copy into a copy that points back at the source. */
+async function assertGitMetadataContained(
+  root: string,
+  signal: AbortSignal,
+): Promise<void> {
+  const hasGitDir = await fs.promises
+    .stat(path.join(root, ".git"))
+    .then((stat) => stat.isDirectory(), () => false);
+  if (!hasGitDir) return;
+  const effectiveWorktree = path.resolve(
+    (
+      await runFile("git", ["rev-parse", "--show-toplevel"], {
+        cwd: root,
+        signal,
+        timeout: 5000,
+      })
+    ).trim(),
+  );
+  const effectiveGitDir = path.resolve(
+    root,
+    (
+      await runFile("git", ["rev-parse", "--absolute-git-dir"], {
+        cwd: root,
+        signal,
+        timeout: 5000,
+      })
+    ).trim(),
+  );
+  const effectiveCommonDir = path.resolve(
+    effectiveGitDir,
+    (
+      await runFile("git", ["rev-parse", "--git-common-dir"], {
+        cwd: root,
+        signal,
+        timeout: 5000,
+      })
+    ).trim(),
+  );
+  if (
+    effectiveWorktree !== root ||
+    !isWithin(root, effectiveGitDir) ||
+    !isWithin(root, effectiveCommonDir)
+  ) {
+    throw new ScratchSetupError(
+      "Scratch workspace Git configuration redirects its worktree or metadata outside the copied project.",
+    );
+  }
+}
+
 function isWithin(root: string, candidate: string): boolean {
   const relative = path.relative(root, candidate);
   return (
@@ -739,6 +801,20 @@ export async function createScratchWorkspace(
       );
     }
 
+    // Fast-fail on blockers that are knowable before anything is created:
+    // the same rule the copy validation enforces, run read-only against the
+    // source. A rejection here costs milliseconds instead of a doomed
+    // reflink copy, and no lease/container is left behind. The post-copy
+    // validation below stays the authority — the tree can change mid-copy.
+    await validateScratchTree(
+      sourceRoot,
+      sourceRoot,
+      false,
+      controller.signal,
+      signal,
+    );
+    await assertGitMetadataContained(sourceRoot, controller.signal);
+
     containerDir = path.join(path.dirname(sourceRoot), SCRATCH_CONTAINER_NAME);
     const uid = process.getuid?.();
     await ensureScratchContainer(containerDir, uid);
@@ -777,57 +853,14 @@ export async function createScratchWorkspace(
     // GNU cp --archive applies the source root's mode to the destination.
     // Restore the private boundary after it has finished copying metadata.
     await fs.promises.chmod(scratchRoot, 0o700);
-    await validateCopiedTree(
+    await validateScratchTree(
       scratchRoot,
       sourceRoot,
+      true,
       controller.signal,
       signal,
     );
-    if (
-      await fs.promises.stat(path.join(scratchRoot, ".git")).then(
-        (stat) => stat.isDirectory(),
-        () => false,
-      )
-    ) {
-      const effectiveWorktree = path.resolve(
-        (
-          await runFile("git", ["rev-parse", "--show-toplevel"], {
-            cwd: scratchRoot,
-            signal: controller.signal,
-            timeout: 5000,
-          })
-        ).trim(),
-      );
-      const effectiveGitDir = path.resolve(
-        scratchRoot,
-        (
-          await runFile("git", ["rev-parse", "--absolute-git-dir"], {
-            cwd: scratchRoot,
-            signal: controller.signal,
-            timeout: 5000,
-          })
-        ).trim(),
-      );
-      const effectiveCommonDir = path.resolve(
-        effectiveGitDir,
-        (
-          await runFile("git", ["rev-parse", "--git-common-dir"], {
-            cwd: scratchRoot,
-            signal: controller.signal,
-            timeout: 5000,
-          })
-        ).trim(),
-      );
-      if (
-        effectiveWorktree !== scratchRoot ||
-        !isWithin(scratchRoot, effectiveGitDir) ||
-        !isWithin(scratchRoot, effectiveCommonDir)
-      ) {
-        throw new ScratchSetupError(
-          "Scratch workspace Git configuration redirects its worktree or metadata outside the copied project.",
-        );
-      }
-    }
+    await assertGitMetadataContained(scratchRoot, controller.signal);
     throwIfSetupCancelled(controller.signal, signal);
     // Keep the copied project writable, but make its private parent immutable
     // to ordinary task commands. `mv "$PWD" …` then cannot unlink the project
@@ -865,8 +898,17 @@ export async function createScratchWorkspace(
       );
     }
     if (error instanceof ScratchSetupError) throw error;
+    // Surface the failed command's own stderr: the generic message's
+    // reflink guidance is a guess, and the real cp failure (or a btrfs
+    // project failing for an unrelated reason) is only visible in stderr.
+    let commandDetail = "";
+    if (error instanceof CommandError) {
+      const line = error.stderr.split("\n", 1)[0]?.trim();
+      if (line) commandDetail = ` ${error.file} failed: ${line}`;
+    }
     throw new Error(
-      "Could not create a CoW scratch workspace. The project and scratch directory must be on a reflink-capable filesystem (for example Btrfs).",
+      "Could not create a CoW scratch workspace. The project and scratch directory must be on a reflink-capable filesystem (for example Btrfs)." +
+        commandDetail,
       { cause: error },
     );
   } finally {