cclaw-cli 7.2.0 → 7.4.0

package/dist/config.d.ts

@@ -1,6 +1,9 @@
-import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, TddCommitMode } from "./types.js";
+import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, TddCommitMode, TddIsolationMode } from "./types.js";
 export declare const TDD_COMMIT_MODES: readonly ["managed-per-slice", "agent-required", "checkpoint-only", "off"];
 export declare const DEFAULT_TDD_COMMIT_MODE: TddCommitMode;
+export declare const TDD_ISOLATION_MODES: readonly ["worktree", "in-place", "auto"];
+export declare const DEFAULT_TDD_ISOLATION_MODE: TddIsolationMode;
+export declare const DEFAULT_TDD_WORKTREE_ROOT = ".cclaw/worktrees";
 export declare const DEFAULT_TDD_TEST_PATH_PATTERNS: readonly string[];
 export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
 export declare const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS: readonly string[];
@@ -19,6 +22,8 @@ export declare class InvalidConfigError extends Error {
 export declare function configPath(projectRoot: string): string;
 export declare function createDefaultConfig(harnesses?: HarnessId[], _defaultTrack?: FlowTrack): CclawConfig;
 export declare function resolveTddCommitMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddCommitMode;
+export declare function resolveTddIsolationMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddIsolationMode;
+export declare function resolveTddWorktreeRoot(config: Pick<CclawConfig, "tdd"> | null | undefined): string;
 export declare function detectLanguageRulePacks(_projectRoot: string): Promise<LanguageRulePack[]>;
 export declare function readConfig(projectRoot: string, _options?: ReadConfigOptions): Promise<CclawConfig>;
 export interface WriteConfigOptions {

package/dist/config.js

@@ -16,6 +16,10 @@ export const TDD_COMMIT_MODES = [
 ];
 const TDD_COMMIT_MODE_SET = new Set(TDD_COMMIT_MODES);
 export const DEFAULT_TDD_COMMIT_MODE = "managed-per-slice";
+export const TDD_ISOLATION_MODES = ["worktree", "in-place", "auto"];
+const TDD_ISOLATION_MODE_SET = new Set(TDD_ISOLATION_MODES);
+export const DEFAULT_TDD_ISOLATION_MODE = "worktree";
+export const DEFAULT_TDD_WORKTREE_ROOT = `${RUNTIME_ROOT}/worktrees`;
 // Kept for runtime modules that use these defaults directly.
 export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
     "**/*.test.*",
@@ -40,7 +44,9 @@ function configFixExample() {
   - claude
   - cursor
 tdd:
-  commitMode: managed-per-slice`;
+  commitMode: managed-per-slice
+  isolationMode: worktree
+  worktreeRoot: .cclaw/worktrees`;
 }
 function configValidationError(configFilePath, reason) {
     return new InvalidConfigError(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
@@ -60,7 +66,9 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, _defaultTrack
         flowVersion: FLOW_VERSION,
         harnesses: [...new Set(harnesses)],
         tdd: {
-            commitMode: DEFAULT_TDD_COMMIT_MODE
+            commitMode: DEFAULT_TDD_COMMIT_MODE,
+            isolationMode: DEFAULT_TDD_ISOLATION_MODE,
+            worktreeRoot: DEFAULT_TDD_WORKTREE_ROOT
         }
     };
 }
@@ -71,6 +79,20 @@ export function resolveTddCommitMode(config) {
     }
     return DEFAULT_TDD_COMMIT_MODE;
 }
+export function resolveTddIsolationMode(config) {
+    const raw = config?.tdd?.isolationMode;
+    if (typeof raw === "string" && TDD_ISOLATION_MODE_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_TDD_ISOLATION_MODE;
+}
+export function resolveTddWorktreeRoot(config) {
+    const raw = config?.tdd?.worktreeRoot;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        return raw.trim();
+    }
+    return DEFAULT_TDD_WORKTREE_ROOT;
+}
 function assertOnlySupportedKeys(parsed, fullPath) {
     const unknownKeys = Object.keys(parsed).filter((key) => !ALLOWED_CONFIG_KEYS.has(key));
     if (unknownKeys.length === 0)
@@ -129,19 +151,37 @@ export async function readConfig(projectRoot, _options = {}) {
         : FLOW_VERSION;
     const parsedTdd = isRecord(parsed.tdd) ? parsed.tdd : {};
     const rawCommitMode = parsedTdd.commitMode;
+    const rawIsolationMode = parsedTdd.isolationMode;
+    const rawWorktreeRoot = parsedTdd.worktreeRoot;
     if (rawCommitMode !== undefined &&
         (typeof rawCommitMode !== "string" || !TDD_COMMIT_MODE_SET.has(rawCommitMode))) {
         throw configValidationError(fullPath, `"tdd.commitMode" must be one of: ${TDD_COMMIT_MODES.join(", ")}`);
     }
+    if (rawIsolationMode !== undefined &&
+        (typeof rawIsolationMode !== "string" || !TDD_ISOLATION_MODE_SET.has(rawIsolationMode))) {
+        throw configValidationError(fullPath, `"tdd.isolationMode" must be one of: ${TDD_ISOLATION_MODES.join(", ")}`);
+    }
+    if (rawWorktreeRoot !== undefined &&
+        (typeof rawWorktreeRoot !== "string" || rawWorktreeRoot.trim().length === 0)) {
+        throw configValidationError(fullPath, `"tdd.worktreeRoot" must be a non-empty string when provided`);
+    }
     const commitMode = typeof rawCommitMode === "string"
         ? rawCommitMode
         : DEFAULT_TDD_COMMIT_MODE;
+    const isolationMode = typeof rawIsolationMode === "string"
+        ? rawIsolationMode
+        : DEFAULT_TDD_ISOLATION_MODE;
+    const worktreeRoot = typeof rawWorktreeRoot === "string" && rawWorktreeRoot.trim().length > 0
+        ? rawWorktreeRoot.trim()
+        : DEFAULT_TDD_WORKTREE_ROOT;
     return {
         version,
         flowVersion,
         harnesses: normalizedHarnesses,
         tdd: {
-            commitMode
+            commitMode,
+            isolationMode,
+            worktreeRoot
         }
     };
 }
@@ -151,7 +191,9 @@ export async function writeConfig(projectRoot, config, _options = {}) {
         flowVersion: config.flowVersion,
         harnesses: config.harnesses,
         tdd: {
-            commitMode: resolveTddCommitMode(config)
+            commitMode: resolveTddCommitMode(config),
+            isolationMode: resolveTddIsolationMode(config),
+            worktreeRoot: resolveTddWorktreeRoot(config)
         }
     };
     await writeFileSafe(configPath(projectRoot), stringify(serialisable));

package/dist/constants.d.ts

@@ -10,7 +10,7 @@ export declare const FLOW_VERSION = "1.0.0";
 export declare const SHIP_FINALIZATION_MODES: readonly ["FINALIZE_MERGE_LOCAL", "FINALIZE_OPEN_PR", "FINALIZE_KEEP_BRANCH", "FINALIZE_DISCARD_BRANCH", "FINALIZE_NO_VCS"];
 export type ShipFinalizationMode = (typeof SHIP_FINALIZATION_MODES)[number];
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/wave-plans", ".cclaw/archive", ".cclaw/state", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/wave-plans", ".cclaw/archive", ".cclaw/worktrees", ".cclaw/state", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 /**
  * Canonical stage -> skill folder mapping.

package/dist/constants.js

@@ -61,6 +61,7 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/artifacts`,
     `${RUNTIME_ROOT}/wave-plans`,
     `${RUNTIME_ROOT}/archive`,
+    `${RUNTIME_ROOT}/worktrees`,
     `${RUNTIME_ROOT}/state`,
     `${RUNTIME_ROOT}/rules`,
     `${RUNTIME_ROOT}/agents`,

package/dist/content/core-agents.js

@@ -156,6 +156,7 @@ export function sliceBuilderProtocol() {
         "### Invariants",
         "- Produce failing RED evidence (or cite the delegated RED artifact) **before** production edits.",
         "- Stay inside the slice contract: `claimedPaths`, acceptance mapping, and forbidden-change lists from the parent.",
+        "- When `tdd.isolationMode=worktree|auto`, run the slice inside the assigned worktree path (never in the shared repo root) so filesystem isolation enforces the claimed-path fence.",
         "- When `tdd.commitMode=managed-per-slice`, do **not** hand-edit git state for slice files (no manual `git add/commit` on claimed paths). Let `.cclaw/hooks/slice-commit.mjs` own per-slice commits.",
         "- After GREEN, refactor inline **or** record deferred refactor via the same `--refactor-outcome` mechanics the controller specifies.",
         "- Own the prose slice summary at `<artifacts-dir>/tdd-slices/S-<id>.md` yourself.",
@@ -164,6 +165,11 @@ export function sliceBuilderProtocol() {
         "- Honor every `delegation-record`/`delegation-record.mjs` row shape the controller requests so artifact linters keep passing.",
         "- The umbrella `slice-completed` row ties RED/GREEN/REFACTOR/DOC timestamps to your builder span.",
         "",
+        "### Streaming output contract",
+        "- Emit one JSON line to stdout per completed phase: `{\"event\":\"phase-completed\",\"stage\":\"tdd\",\"sliceId\":\"S-<n>\",\"phase\":\"<red|green|refactor|refactor-deferred|doc>\",\"spanId\":\"<span>\",\"runId\":\"<run>\",\"ts\":\"<iso>\"}`.",
+        "- For `phase=green` with inline/deferred refactor folding, include `refactorOutcome.mode` in the same JSON line so live controllers can close the slice without waiting for file sync.",
+        "- If streaming is unavailable in your harness/runtime, keep writing canonical `delegation-record` rows; controller-side live mode will fall back to file-based events.",
+        "",
         "**Role boundary:** do not widen scope, do not self-approve ship-level review, and do not recurse into other agents unless the parent explicitly directs it."
     ].join("\n");
 }

package/dist/content/hooks.js

@@ -614,6 +614,10 @@ function buildRow(args, status, runId, now, options) {
     riskTierRaw === "low" || riskTierRaw === "medium" || riskTierRaw === "high"
       ? riskTierRaw
       : undefined;
+  const worktreePath =
+    typeof args["worktree-path"] === "string" && args["worktree-path"].trim().length > 0
+      ? args["worktree-path"].trim()
+      : undefined;
   return {
     stage: args.stage,
     agent: args.agent,
@@ -637,6 +641,7 @@ function buildRow(args, status, runId, now, options) {
     schemaVersion: LEDGER_SCHEMA_VERSION,
     allowParallel: args["allow-parallel"] === true ? true : undefined,
     claimedPaths: claimedPaths.length > 0 ? claimedPaths : undefined,
+    worktreePath,
     sliceId,
     phase,
     refactorOutcome,
@@ -1251,6 +1256,24 @@ async function runSliceCommitIfNeeded(root, row, runId) {
     "--span-id=" + spanId,
     "--run-id=" + runId
   ];
+  let explicitWorktreePath =
+    typeof row.worktreePath === "string" && row.worktreePath.trim().length > 0
+      ? row.worktreePath.trim()
+      : "";
+  if (explicitWorktreePath.length === 0) {
+    const priorLedger = await readDelegationLedgerEntries(root);
+    const priorSpanPath = priorLedger
+      .filter((entry) => entry && entry.spanId === spanId && entry.runId === runId)
+      .map((entry) =>
+        entry && typeof entry.worktreePath === "string" ? entry.worktreePath.trim() : "")
+      .find((value) => value.length > 0);
+    if (priorSpanPath) {
+      explicitWorktreePath = priorSpanPath;
+    }
+  }
+  if (explicitWorktreePath.length > 0) {
+    helperArgs.push("--worktree-path=" + explicitWorktreePath);
+  }
   if (typeof row.taskId === "string" && row.taskId.trim().length > 0) {
     helperArgs.push("--task-id=" + row.taskId.trim());
   }
@@ -1320,6 +1343,91 @@ async function runSliceCommitIfNeeded(root, row, runId) {
   });
 }
 
+async function runSliceWorktreePrepareIfNeeded(root, row, runId) {
+  if (
+    row.stage !== "tdd" ||
+    row.agent !== "slice-builder" ||
+    row.status !== "scheduled"
+  ) {
+    return { ok: true, skipped: true };
+  }
+  const sliceId = typeof row.sliceId === "string" ? row.sliceId.trim() : "";
+  const spanId = typeof row.spanId === "string" ? row.spanId.trim() : "";
+  if (sliceId.length === 0 || spanId.length === 0) {
+    return { ok: true, skipped: true };
+  }
+  const helperPath = path.join(root, RUNTIME_ROOT, "hooks", "slice-commit.mjs");
+  if (!(await exists(helperPath))) {
+    return { ok: true, skipped: true };
+  }
+  const helperArgs = [
+    helperPath,
+    "--json",
+    "--quiet",
+    "--prepare-worktree",
+    "--slice=" + sliceId,
+    "--span-id=" + spanId,
+    "--run-id=" + runId
+  ];
+  if (Array.isArray(row.claimedPaths) && row.claimedPaths.length > 0) {
+    helperArgs.push("--claimed-paths=" + row.claimedPaths.join(","));
+  }
+  return await new Promise((resolve) => {
+    const child = spawn(process.execPath, helperArgs, {
+      cwd: root,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => {
+      out += String(chunk ?? "");
+    });
+    child.stderr.on("data", (chunk) => {
+      err += String(chunk ?? "");
+    });
+    child.on("error", (error) => {
+      resolve({
+        ok: false,
+        errorCode: "worktree_prepare_failed",
+        details: {
+          message: error instanceof Error ? error.message : String(error)
+        }
+      });
+    });
+    child.on("close", (code) => {
+      let payload = null;
+      const trimmed = out.trim();
+      if (trimmed.length > 0) {
+        try {
+          payload = JSON.parse(trimmed);
+        } catch {
+          payload = null;
+        }
+      }
+      if (code === 0) {
+        resolve({ ok: true, payload });
+        return;
+      }
+      const payloadCode =
+        payload && typeof payload === "object" && typeof payload.errorCode === "string"
+          ? payload.errorCode
+          : "worktree_prepare_failed";
+      resolve({
+        ok: false,
+        errorCode: payloadCode,
+        details:
+          payload && typeof payload === "object"
+            ? payload
+            : {
+              stderr: err.trim(),
+              stdout: out.trim()
+            }
+      });
+    });
+  });
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const json = args.json !== undefined;
@@ -1510,6 +1618,16 @@ async function main() {
   const status = args.status;
   const priorLedger = await readDelegationLedgerEntries(root);
   const priorForSpan = priorLedger.filter((e) => e && e.spanId === args["span-id"]);
+  const inheritedWorktreePath = priorForSpan
+    .map((entry) =>
+      entry && typeof entry.worktreePath === "string" ? entry.worktreePath.trim() : "")
+    .find((value) => value.length > 0);
+  if (
+    inheritedWorktreePath &&
+    (typeof args["worktree-path"] !== "string" || args["worktree-path"].trim().length === 0)
+  ) {
+    args["worktree-path"] = inheritedWorktreePath;
+  }
   const inheritedStartTs = priorForSpan
     .map((e) => e.startTs)
     .filter((ts) => typeof ts === "string" && ts.length > 0)
@@ -1572,6 +1690,24 @@ async function main() {
       emitErrorJson("dispatch_cap", capViolation, json);
       return;
     }
+    const preparedWorktree = await runSliceWorktreePrepareIfNeeded(root, clean, runId);
+    if (!preparedWorktree.ok) {
+      emitErrorJson(
+        preparedWorktree.errorCode || "worktree_prepare_failed",
+        preparedWorktree.details || {},
+        json
+      );
+      return;
+    }
+    if (
+      preparedWorktree.payload &&
+      typeof preparedWorktree.payload === "object" &&
+      typeof preparedWorktree.payload.worktreePath === "string" &&
+      preparedWorktree.payload.worktreePath.trim().length > 0
+    ) {
+      clean.worktreePath = preparedWorktree.payload.worktreePath.trim();
+      event.worktreePath = clean.worktreePath;
+    }
   }
   const dedupViolation = enforceDispatchDedupInline(clean, priorLedger, args);
   if (dedupViolation) {
@@ -1758,7 +1894,7 @@ void main();
 `;
 }
 export function sliceCommitScript() {
-    return internalHelperScript("slice-commit", "slice-commit", "Usage: node " + RUNTIME_ROOT + "/hooks/slice-commit.mjs --slice=<S-N> --span-id=<span-id> [--task-id=<T-id>] [--title=<text>] [--run-id=<run-id>] [--claimed-paths=<path1,path2,...>] [--claimed-path=<path> ...] [--json] [--quiet]");
+    return internalHelperScript("slice-commit", "slice-commit", "Usage: node " + RUNTIME_ROOT + "/hooks/slice-commit.mjs --slice=<S-N> --span-id=<span-id> [--task-id=<T-id>] [--title=<text>] [--run-id=<run-id>] [--worktree-path=<abs-or-rel-path>] [--prepare-worktree] [--claimed-paths=<path1,path2,...>] [--claimed-path=<path> ...] [--json] [--quiet]");
 }
 export function runHookCmdScript() {
     return `: << 'CMDBLOCK'

package/dist/delegation.d.ts

@@ -142,6 +142,11 @@ export type DelegationEntry = {
      * `src/content/hooks.ts::delegationRecordScript`.
      */
     claimedPaths?: string[];
+    /**
+     * Absolute path of the isolated git worktree assigned to this span when
+     * `tdd.isolationMode=worktree|auto`.
+     */
+    worktreePath?: string;
     /**
      * TDD slice identifier, e.g. `"S-1"`. Recorded by the controller when
      * dispatching `slice-builder` so the artifact linter can auto-derive the

package/dist/install.js

@@ -190,7 +190,7 @@ const DEPRECATED_HOOK_FILES = [
     "context-monitor.sh"
 ];
 const DEPRECATED_RUNTIME_ROOT_FILES = ["learnings.jsonl", "observations.jsonl"];
-const DEPRECATED_RUNTIME_DIRS = ["evals", "worktrees", "references", "contexts"];
+const DEPRECATED_RUNTIME_DIRS = ["evals", "references", "contexts"];
 async function resolveGitHooksDir(projectRoot) {
     try {
         const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks"], {

package/dist/internal/slice-commit.js

@@ -1,9 +1,10 @@
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
-import { readConfig, resolveTddCommitMode } from "../config.js";
+import { readConfig, resolveTddCommitMode, resolveTddIsolationMode, resolveTddWorktreeRoot } from "../config.js";
 import { readDelegationLedger } from "../delegation.js";
 import { exists } from "../fs-utils.js";
+import { cleanupWorktree, commitAndMergeBack, createSliceWorktree, WorktreeMergeConflictError, WorktreeUnsupportedError } from "../worktree-manager.js";
 const execFileAsync = promisify(execFile);
 function parseCsv(raw) {
     return raw
@@ -22,7 +23,9 @@ function parseSliceCommitArgs(tokens) {
     let taskId;
     let title;
     let runId;
+    let worktreePath;
     const claimedPaths = [];
+    let prepareWorktree = false;
     let json = false;
     let quiet = false;
     for (let i = 0; i < tokens.length; i += 1) {
@@ -45,6 +48,10 @@ function parseSliceCommitArgs(tokens) {
             quiet = true;
             continue;
         }
+        if (token === "--prepare-worktree") {
+            prepareWorktree = true;
+            continue;
+        }
         if (token.startsWith("--slice=") || token === "--slice") {
             sliceId = valueFrom("--slice").trim();
             continue;
@@ -65,6 +72,13 @@ function parseSliceCommitArgs(tokens) {
             runId = valueFrom("--run-id").trim();
             continue;
         }
+        if (token.startsWith("--worktree-path=") || token === "--worktree-path") {
+            const resolved = valueFrom("--worktree-path").trim();
+            if (resolved.length > 0) {
+                worktreePath = resolved;
+            }
+            continue;
+        }
         if (token.startsWith("--claimed-paths=") || token === "--claimed-paths") {
             claimedPaths.push(...parseCsv(valueFrom("--claimed-paths")));
             continue;
@@ -89,7 +103,9 @@ function parseSliceCommitArgs(tokens) {
         taskId,
         title,
         runId,
+        worktreePath,
         claimedPaths,
+        prepareWorktree,
         json,
         quiet
     };
@@ -132,6 +148,12 @@ function parsePorcelainPaths(raw) {
     }
     return [...new Set(out)];
 }
+async function gitChangedPaths(cwd) {
+    const { stdout: statusRaw } = await execFileAsync("git", ["status", "--porcelain", "-uall"], {
+        cwd
+    });
+    return parsePorcelainPaths(statusRaw);
+}
 function matchesClaimedPath(changedPath, claimedPaths) {
     const changed = normalizePathLike(changedPath);
     return claimedPaths.some((rawClaimed) => {
@@ -171,6 +193,67 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     const config = await readConfig(projectRoot).catch(() => null);
     const commitMode = resolveTddCommitMode(config);
+    const isolationMode = resolveTddIsolationMode(config);
+    const worktreeRoot = resolveTddWorktreeRoot(config);
+    const gitPresent = await exists(path.join(projectRoot, ".git"));
+    if (args.prepareWorktree) {
+        if (!gitPresent) {
+            output(io, args, {
+                ok: true,
+                skipped: true,
+                reason: "no-git",
+                message: "slice-worktree skipped: .git is missing"
+            });
+            return 0;
+        }
+        if (isolationMode === "in-place") {
+            output(io, args, {
+                ok: true,
+                skipped: true,
+                reason: "isolation-in-place",
+                isolationMode,
+                message: "slice-worktree skipped: tdd.isolationMode=in-place"
+            });
+            return 0;
+        }
+        try {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot });
+            const prepared = await createSliceWorktree(args.sliceId, stdout.trim(), args.claimedPaths, {
+                projectRoot,
+                worktreeRoot
+            });
+            output(io, args, {
+                ok: true,
+                prepared: true,
+                sliceId: args.sliceId,
+                spanId: args.spanId,
+                worktreePath: prepared.path,
+                baseRef: prepared.ref
+            });
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof WorktreeUnsupportedError) {
+                output(io, args, {
+                    ok: true,
+                    skipped: true,
+                    reason: "worktree-unavailable",
+                    degradedCommitMode: "agent-required",
+                    message: error.message
+                });
+                return 0;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "worktree_prepare_failed",
+                details: {
+                    message: error instanceof Error ? error.message : String(error)
+                },
+                message: `worktree_prepare_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
     if (commitMode !== "managed-per-slice") {
         output(io, args, {
             ok: true,
@@ -181,7 +264,6 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         });
         return 0;
     }
-    const gitPresent = await exists(path.join(projectRoot, ".git"));
     if (!gitPresent) {
         output(io, args, {
             ok: true,
@@ -206,11 +288,64 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         }, "stderr");
         return 2;
     }
-    const { stdout: statusRaw } = await execFileAsync("git", ["status", "--porcelain", "-uall"], {
-        cwd: projectRoot
-    });
-    const changedPaths = parsePorcelainPaths(statusRaw);
+    let managedWorktreePath = null;
+    let activeCwd = projectRoot;
+    let degradedToInPlace = false;
+    const requestedWorktreePath = typeof args.worktreePath === "string" && args.worktreePath.trim().length > 0
+        ? path.resolve(projectRoot, args.worktreePath.trim())
+        : null;
+    if (requestedWorktreePath && await exists(requestedWorktreePath)) {
+        managedWorktreePath = requestedWorktreePath;
+        activeCwd = requestedWorktreePath;
+    }
+    else if (isolationMode !== "in-place") {
+        try {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot });
+            const prepared = await createSliceWorktree(args.sliceId, stdout.trim(), claimedPaths, {
+                projectRoot,
+                worktreeRoot
+            });
+            managedWorktreePath = prepared.path;
+            activeCwd = prepared.path;
+        }
+        catch (error) {
+            if (error instanceof WorktreeUnsupportedError) {
+                output(io, args, {
+                    ok: true,
+                    skipped: true,
+                    reason: "worktree-unavailable",
+                    degradedCommitMode: "agent-required",
+                    message: error.message
+                });
+                return 0;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "worktree_prepare_failed",
+                details: {
+                    message: error instanceof Error ? error.message : String(error)
+                },
+                message: `worktree_prepare_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
+    const cleanupManagedWorktree = async () => {
+        if (!managedWorktreePath)
+            return;
+        await cleanupWorktree(managedWorktreePath, { projectRoot }).catch(() => undefined);
+    };
+    let changedPaths = await gitChangedPaths(activeCwd);
+    if (changedPaths.length === 0 && managedWorktreePath && activeCwd !== projectRoot) {
+        const rootChangedPaths = await gitChangedPaths(projectRoot);
+        if (rootChangedPaths.length > 0) {
+            activeCwd = projectRoot;
+            changedPaths = rootChangedPaths;
+            degradedToInPlace = true;
+        }
+    }
     if (changedPaths.length === 0) {
+        await cleanupManagedWorktree();
         output(io, args, {
             ok: true,
             skipped: true,
@@ -236,6 +371,7 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     const changedInClaim = changedPaths.filter((p) => matchesClaimedPath(p, claimedPaths));
     if (changedInClaim.length === 0) {
+        await cleanupManagedWorktree();
         output(io, args, {
             ok: true,
             skipped: true,
@@ -246,7 +382,7 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     }
     try {
         await execFileAsync("git", ["add", "--", ...claimedPaths], {
-            cwd: projectRoot
+            cwd: activeCwd
         });
         const taskPart = args.taskId && args.taskId.length > 0 ? args.taskId : "task";
         const titlePart = args.title && args.title.length > 0 ? args.title : "slice update";
@@ -257,12 +393,13 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
             "phase-cycle: red->green->refactor->doc"
         ].join("\n");
         await execFileAsync("git", ["commit", "-m", header, "-m", body], {
-            cwd: projectRoot
+            cwd: activeCwd
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (/nothing to commit/iu.test(message)) {
+            await cleanupManagedWorktree();
             output(io, args, {
                 ok: true,
                 skipped: true,
@@ -280,9 +417,39 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         return 1;
     }
     const { stdout: shaStdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
-        cwd: projectRoot
+        cwd: activeCwd
     });
-    const commitSha = shaStdout.trim();
+    let commitSha = shaStdout.trim();
+    if (managedWorktreePath && activeCwd !== projectRoot) {
+        try {
+            const merged = await commitAndMergeBack(activeCwd, `merge ${args.sliceId}`, { projectRoot });
+            commitSha = merged.commitSha;
+        }
+        catch (error) {
+            if (error instanceof WorktreeMergeConflictError) {
+                output(io, args, {
+                    ok: false,
+                    errorCode: "worktree_merge_conflict",
+                    details: {
+                        sliceId: args.sliceId,
+                        spanId: args.spanId,
+                        worktreePath: activeCwd,
+                        message: error.message
+                    },
+                    message: error.message
+                }, "stderr");
+                return 2;
+            }
+            output(io, args, {
+                ok: false,
+                errorCode: "slice_commit_failed",
+                details: { message: error instanceof Error ? error.message : String(error) },
+                message: `slice_commit_failed: ${error instanceof Error ? error.message : String(error)}`
+            }, "stderr");
+            return 1;
+        }
+    }
+    await cleanupManagedWorktree();
     output(io, args, {
         ok: true,
         commitSha,
@@ -290,6 +457,8 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         spanId: args.spanId,
         claimedPaths,
         changedPaths: changedInClaim,
+        worktreePath: managedWorktreePath ?? undefined,
+        degradedToInPlace: degradedToInPlace || undefined,
         message: `slice commit created for ${args.sliceId}: ${commitSha}`
     });
     return 0;

package/dist/internal/wave-status.d.ts

@@ -32,6 +32,17 @@ export interface RunWaveStatusOptions {
      * `<projectRoot>/.cclaw/artifacts`.
      */
     artifactsDir?: string;
+    /**
+     * Event ingestion mode:
+     * - auto: prefer live stream file; fallback to delegation-events.jsonl.
+     * - live: force live stream first; fallback to delegation-events.jsonl with warning.
+     * - file: skip stream file and use delegation-events.jsonl only.
+     */
+    streamMode?: "auto" | "live" | "file";
+    /**
+     * Optional absolute stream path override (tests).
+     */
+    streamPath?: string;
 }
 /**
  * Deterministic helper for the TDD controller. Reads the managed

package/dist/internal/wave-status.js

@@ -3,16 +3,21 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
 import { readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { readFlowState } from "../runs.js";
+import { DEFAULT_SLICE_STREAM_REL_PATH, readEventStreamFile } from "../streaming/event-stream.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./plan-split-waves.js";
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 function parseArgs(tokens) {
-    const args = { format: "json" };
+    const args = { format: "json", streamMode: "auto" };
     for (const token of tokens) {
         if (token === "--json")
             args.format = "json";
         else if (token === "--human" || token === "--text")
             args.format = "human";
+        else if (token === "--live")
+            args.streamMode = "live";
+        else if (token === "--file-only")
+            args.streamMode = "file";
         else if (token.startsWith("--format=")) {
             const raw = token.slice("--format=".length).trim();
             if (raw === "json" || raw === "human")
@@ -20,6 +25,13 @@ function parseArgs(tokens) {
             else
                 throw new Error(`Unknown wave-status --format value: ${raw}`);
         }
+        else if (token.startsWith("--stream-mode=")) {
+            const raw = token.slice("--stream-mode=".length).trim();
+            if (raw === "auto" || raw === "live" || raw === "file")
+                args.streamMode = raw;
+            else
+                throw new Error(`Unknown wave-status --stream-mode value: ${raw}`);
+        }
         else {
             throw new Error(`Unknown wave-status flag: ${token}`);
         }
@@ -228,34 +240,72 @@ export async function runWaveStatus(projectRoot, options = {}) {
             }
         }
     }
-    // Also consult the JSONL events in case the ledger projection lags.
-    try {
-        const { events } = await readDelegationEvents(projectRoot);
-        for (const ev of events) {
-            if (ev.event !== "completed")
-                continue;
-            if (ev.runId !== activeRunId)
-                continue;
-            if (ev.stage !== "tdd")
-                continue;
-            if (typeof ev.sliceId !== "string")
-                continue;
-            if (typeof ev.phase !== "string")
-                continue;
-            if (TERMINAL_PHASES.has(ev.phase)) {
-                closedSlices.add(ev.sliceId);
-                continue;
-            }
-            if (ev.phase === "green" && ev.refactorOutcome) {
-                const mode = ev.refactorOutcome.mode;
-                if (mode === "inline" || mode === "deferred") {
+    const warnings = [];
+    const streamMode = options.streamMode ?? "auto";
+    const streamPath = options.streamPath ?? path.join(projectRoot, DEFAULT_SLICE_STREAM_REL_PATH);
+    let shouldReadJsonlFallback = streamMode === "file";
+    // Prefer live stream events when requested/available.
+    if (streamMode !== "file") {
+        const streamResult = await readEventStreamFile(streamPath);
+        if (streamResult.droppedLines > 0) {
+            warnings.push(`wave_stream_dropped_lines: ${streamResult.droppedLines}`);
+        }
+        if (streamResult.events.length > 0) {
+            for (const ev of streamResult.events) {
+                if (ev.runId && ev.runId !== activeRunId)
+                    continue;
+                if (ev.stage && ev.stage !== "tdd")
+                    continue;
+                if (TERMINAL_PHASES.has(ev.phase)) {
                     closedSlices.add(ev.sliceId);
+                    continue;
+                }
+                if (ev.phase === "green" && ev.refactorOutcome) {
+                    const mode = ev.refactorOutcome.mode;
+                    if (mode === "inline" || mode === "deferred") {
+                        closedSlices.add(ev.sliceId);
+                    }
                 }
             }
+            shouldReadJsonlFallback = false;
+        }
+        else {
+            shouldReadJsonlFallback = true;
+            if (streamMode === "auto" || streamMode === "live") {
+                warnings.push("wave_status_live_fallback_to_file: no parseable stream events");
+            }
         }
     }
-    catch {
-        // best-effort; ledger already covers the canonical case.
+    // Fallback to JSONL events when live stream is absent or disabled.
+    if (shouldReadJsonlFallback) {
+        try {
+            const { events } = await readDelegationEvents(projectRoot);
+            for (const ev of events) {
+                if (ev.event !== "completed")
+                    continue;
+                if (ev.runId !== activeRunId)
+                    continue;
+                if (ev.stage !== "tdd")
+                    continue;
+                if (typeof ev.sliceId !== "string")
+                    continue;
+                if (typeof ev.phase !== "string")
+                    continue;
+                if (TERMINAL_PHASES.has(ev.phase)) {
+                    closedSlices.add(ev.sliceId);
+                    continue;
+                }
+                if (ev.phase === "green" && ev.refactorOutcome) {
+                    const mode = ev.refactorOutcome.mode;
+                    if (mode === "inline" || mode === "deferred") {
+                        closedSlices.add(ev.sliceId);
+                    }
+                }
+            }
+        }
+        catch {
+            // best-effort; ledger already covers the canonical case.
+        }
     }
     const waves = merged.map((wave) => {
         const members = wave.members.map((m) => m.sliceId);
@@ -272,7 +322,6 @@ export async function runWaveStatus(projectRoot, options = {}) {
         };
     });
     const firstOpenWave = waves.find((w) => w.status === "open" || w.status === "partial") ?? null;
-    const warnings = [];
     if (merged.length === 0 && planRaw.length === 0) {
         warnings.push("wave_plan_missing: 05-plan.md not found or empty under <artifacts-dir>.");
     }
@@ -349,7 +398,7 @@ export async function runWaveStatusCommand(projectRoot, argv, io) {
         io.stderr.write(`cclaw internal wave-status: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
-    const report = await runWaveStatus(projectRoot);
+    const report = await runWaveStatus(projectRoot, { streamMode: parsed.streamMode });
     if (parsed.format === "json") {
         io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
     }

package/dist/runtime/run-hook.mjs

@@ -40,6 +40,7 @@ var REQUIRED_DIRS = [
   `${RUNTIME_ROOT}/artifacts`,
   `${RUNTIME_ROOT}/wave-plans`,
   `${RUNTIME_ROOT}/archive`,
+  `${RUNTIME_ROOT}/worktrees`,
   `${RUNTIME_ROOT}/state`,
   `${RUNTIME_ROOT}/rules`,
   `${RUNTIME_ROOT}/agents`,

package/dist/streaming/event-stream.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_SLICE_STREAM_REL_PATH = ".cclaw/state/slice-builder-stream.jsonl";
+export interface SliceBuilderPhaseEvent {
+    event: "phase-completed";
+    runId?: string;
+    stage?: string;
+    sliceId: string;
+    phase: string;
+    spanId?: string;
+    refactorOutcome?: {
+        mode?: string;
+    };
+}
+export interface EventStreamParseResult {
+    events: SliceBuilderPhaseEvent[];
+    droppedLines: number;
+}
+/**
+ * Incremental JSONL parser with bounded in-memory buffer. If chunks arrive
+ * faster than the consumer drains complete lines, we trim the oldest partial
+ * payload once maxBufferBytes is exceeded instead of letting memory grow
+ * unbounded.
+ */
+export declare class EventStreamLineBuffer {
+    private readonly maxBufferBytes;
+    private buffer;
+    constructor(maxBufferBytes?: number);
+    push(chunk: string | Buffer): EventStreamParseResult;
+    flush(): EventStreamParseResult;
+}
+export declare function parseEventStreamText(raw: string): EventStreamParseResult;
+export declare function readEventStreamFile(absPath: string): Promise<EventStreamParseResult>;

package/dist/streaming/event-stream.js

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+export const DEFAULT_SLICE_STREAM_REL_PATH = ".cclaw/state/slice-builder-stream.jsonl";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function parseEventLine(rawLine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawLine);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed.event !== "phase-completed")
+        return null;
+    const sliceId = asString(parsed.sliceId);
+    const phase = asString(parsed.phase);
+    if (!sliceId || !phase)
+        return null;
+    const stage = asString(parsed.stage);
+    const runId = asString(parsed.runId);
+    const spanId = asString(parsed.spanId);
+    const refactorOutcome = isRecord(parsed.refactorOutcome)
+        ? { mode: asString(parsed.refactorOutcome.mode) }
+        : undefined;
+    return {
+        event: "phase-completed",
+        ...(runId ? { runId } : {}),
+        ...(stage ? { stage } : {}),
+        sliceId,
+        phase,
+        ...(spanId ? { spanId } : {}),
+        ...(refactorOutcome ? { refactorOutcome } : {})
+    };
+}
+/**
+ * Incremental JSONL parser with bounded in-memory buffer. If chunks arrive
+ * faster than the consumer drains complete lines, we trim the oldest partial
+ * payload once maxBufferBytes is exceeded instead of letting memory grow
+ * unbounded.
+ */
+export class EventStreamLineBuffer {
+    maxBufferBytes;
+    buffer = "";
+    constructor(maxBufferBytes = 256 * 1024) {
+        this.maxBufferBytes = maxBufferBytes;
+    }
+    push(chunk) {
+        this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let droppedLines = 0;
+        if (this.buffer.length > this.maxBufferBytes) {
+            const overflowStart = this.buffer.length - this.maxBufferBytes;
+            const nextBreak = this.buffer.indexOf("\n", overflowStart);
+            if (nextBreak >= 0) {
+                this.buffer = this.buffer.slice(nextBreak + 1);
+            }
+            else {
+                this.buffer = "";
+            }
+            droppedLines += 1;
+        }
+        const events = [];
+        let newlineIdx = this.buffer.indexOf("\n");
+        while (newlineIdx >= 0) {
+            const line = this.buffer.slice(0, newlineIdx).trim();
+            this.buffer = this.buffer.slice(newlineIdx + 1);
+            if (line.length > 0) {
+                const parsed = parseEventLine(line);
+                if (parsed)
+                    events.push(parsed);
+                else
+                    droppedLines += 1;
+            }
+            newlineIdx = this.buffer.indexOf("\n");
+        }
+        return { events, droppedLines };
+    }
+    flush() {
+        if (this.buffer.trim().length === 0) {
+            this.buffer = "";
+            return { events: [], droppedLines: 0 };
+        }
+        const parsed = parseEventLine(this.buffer.trim());
+        this.buffer = "";
+        if (parsed) {
+            return { events: [parsed], droppedLines: 0 };
+        }
+        return { events: [], droppedLines: 1 };
+    }
+}
+export function parseEventStreamText(raw) {
+    const buffer = new EventStreamLineBuffer();
+    const pushed = buffer.push(raw);
+    const flushed = buffer.flush();
+    return {
+        events: [...pushed.events, ...flushed.events],
+        droppedLines: pushed.droppedLines + flushed.droppedLines
+    };
+}
+export async function readEventStreamFile(absPath) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(absPath, "utf8");
+    }
+    catch {
+        return { events: [], droppedLines: 0 };
+    }
+    return parseEventStreamText(raw);
+}

package/dist/types.d.ts

@@ -162,6 +162,7 @@ export interface ReviewLoopConfig {
 }
 export type VcsMode = "git-with-remote" | "git-local-only" | "none";
 export type TddCommitMode = "managed-per-slice" | "agent-required" | "checkpoint-only" | "off";
+export type TddIsolationMode = "worktree" | "in-place" | "auto";
 export interface TddConfig {
     /**
      * Commit ownership model for closed TDD slices.
@@ -171,6 +172,17 @@ export interface TddConfig {
      * - off: skip commit-shape enforcement.
      */
     commitMode?: TddCommitMode;
+    /**
+     * Slice execution isolation model.
+     * - worktree: default; allocate one git worktree per slice span.
+     * - in-place: run in the main working tree.
+     * - auto: prefer worktree, degrade to in-place when unavailable.
+     */
+    isolationMode?: TddIsolationMode;
+    /**
+     * Repo-relative root used for managed slice worktrees.
+     */
+    worktreeRoot?: string;
 }
 export interface CclawConfig {
     version: string;

package/dist/worktree-manager.d.ts

@@ -0,0 +1,20 @@
+export interface WorktreeManagerOptions {
+    projectRoot?: string;
+    worktreeRoot?: string;
+}
+export declare class WorktreeUnsupportedError extends Error {
+    readonly code = "worktree_unavailable";
+    constructor(message: string);
+}
+export declare class WorktreeMergeConflictError extends Error {
+    readonly code = "worktree_merge_conflict";
+    constructor(message: string);
+}
+export declare function createSliceWorktree(sliceId: string, baseRef: string, _claimedPaths: string[], options?: WorktreeManagerOptions): Promise<{
+    path: string;
+    ref: string;
+}>;
+export declare function commitAndMergeBack(worktreePath: string, _message: string, options?: WorktreeManagerOptions): Promise<{
+    commitSha: string;
+}>;
+export declare function cleanupWorktree(worktreePath: string, options?: WorktreeManagerOptions): Promise<void>;

package/dist/worktree-manager.js

@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { DEFAULT_TDD_WORKTREE_ROOT } from "./config.js";
+import { exists } from "./fs-utils.js";
+const execFileAsync = promisify(execFile);
+export class WorktreeUnsupportedError extends Error {
+    code = "worktree_unavailable";
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeUnsupportedError";
+    }
+}
+export class WorktreeMergeConflictError extends Error {
+    code = "worktree_merge_conflict";
+    constructor(message) {
+        super(message);
+        this.name = "WorktreeMergeConflictError";
+    }
+}
+function sanitizeSliceId(sliceId) {
+    return sliceId.trim().replace(/[^A-Za-z0-9._-]+/gu, "-");
+}
+function resolveProjectRoot(options) {
+    return options?.projectRoot ?? process.cwd();
+}
+function resolveWorktreeRoot(projectRoot, options) {
+    const root = typeof options?.worktreeRoot === "string" && options.worktreeRoot.trim().length > 0
+        ? options.worktreeRoot.trim()
+        : DEFAULT_TDD_WORKTREE_ROOT;
+    return path.resolve(projectRoot, root);
+}
+async function resolveMainRepoRootFromWorktree(worktreePath) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: worktreePath });
+    const commonDir = stdout.trim();
+    if (commonDir.length === 0) {
+        throw new Error(`Cannot resolve git common-dir from worktree ${worktreePath}`);
+    }
+    return path.dirname(commonDir);
+}
+export async function createSliceWorktree(sliceId, baseRef, _claimedPaths, options = {}) {
+    const projectRoot = resolveProjectRoot(options);
+    const ref = baseRef.trim().length > 0 ? baseRef.trim() : "HEAD";
+    const worktreeRoot = resolveWorktreeRoot(projectRoot, options);
+    const safeSliceId = sanitizeSliceId(sliceId);
+    if (safeSliceId.length === 0) {
+        throw new WorktreeUnsupportedError("Cannot create worktree: empty slice id.");
+    }
+    const worktreePath = path.join(worktreeRoot, safeSliceId);
+    try {
+        await execFileAsync("git", ["rev-parse", "--git-dir"], { cwd: projectRoot });
+    }
+    catch {
+        throw new WorktreeUnsupportedError("Cannot create worktree: repository has no .git metadata.");
+    }
+    await fs.mkdir(worktreeRoot, { recursive: true });
+    if (await exists(worktreePath)) {
+        if (await exists(path.join(worktreePath, ".git"))) {
+            return { path: worktreePath, ref };
+        }
+        await fs.rm(worktreePath, { recursive: true, force: true });
+    }
+    try {
+        await execFileAsync("git", ["worktree", "add", "--detach", worktreePath, ref], {
+            cwd: projectRoot
+        });
+    }
+    catch (error) {
+        throw new WorktreeUnsupportedError(`Cannot create worktree for ${sliceId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { path: worktreePath, ref };
+}
+export async function commitAndMergeBack(worktreePath, _message, options = {}) {
+    const projectRoot = options.projectRoot ?? await resolveMainRepoRootFromWorktree(worktreePath);
+    try {
+        const { stdout: mainHeadStdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+            cwd: projectRoot
+        });
+        const mainHead = mainHeadStdout.trim();
+        await execFileAsync("git", ["rebase", mainHead], { cwd: worktreePath });
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: worktreePath });
+        const commitSha = stdout.trim();
+        await execFileAsync("git", ["fetch", worktreePath, "HEAD"], { cwd: projectRoot });
+        await execFileAsync("git", ["merge", "--ff-only", "FETCH_HEAD"], { cwd: projectRoot });
+        return { commitSha };
+    }
+    catch (error) {
+        throw new WorktreeMergeConflictError(`worktree_merge_conflict: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function cleanupWorktree(worktreePath, options = {}) {
+    if (!(await exists(worktreePath)))
+        return;
+    const projectRoot = options.projectRoot ?? await resolveMainRepoRootFromWorktree(worktreePath).catch(() => null);
+    if (projectRoot) {
+        try {
+            await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
+                cwd: projectRoot
+            });
+            return;
+        }
+        catch {
+            // fall through to rm fallback below
+        }
+    }
+    await fs.rm(worktreePath, { recursive: true, force: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {