@quolu/lattice 0.52.3 → 0.53.0

package/src/runtime-scripted-executor.mjs

@@ -1,163 +1,163 @@
-import { selfDigest, validateExecutorPacket } from './runtime-contracts.mjs';
-
-/**
- * RC3-E 決定論的scripted executor adapter（ADR 0044 Decision 9）。
- *
- * provider非依存adapter interfaceのprimary実装。挙動はscript（TODOごとのstep列）
- * だけで決まり、wall-clock・乱数・環境に依存しない。scripted campaign（RC3-H）が
- * 既知の正解集合を持つ条件注入に使う。
- *
- * adapter interface（provider非依存契約）:
- *   dispatch({ packet })            → { executor_handle, worktree_id }
- *   observe({ executor_handle })    → { state: 'running' }
- *                                    | { state: 'unknown' }                    … timeout相当
- *                                    | { state: 'checkpoint_ready', checkpoint }
- *                                    | { state: 'terminal', receipt }
- *
- * - 同一taskの重複dispatchはtyped rejectする（Decision 9.4）。
- * - `unknown`はfailureではない。同一handleでの再observeだけが正規の回収経路で、
- *   scriptは`stall`stepでこの経路を決定論的に再現する。
- * - terminal receiptはdispatch済みpacketへ帰属し（handle・worktree・packet digest）、
- *   scriptのoverridesで帰属破壊・stale epoch等の敵対条件を注入できる。
- */
-
-const STEP_KINDS = new Set(['checkpoint', 'stall', 'hold_request', 'terminal']);
-
-function fail(reason) {
-  throw new TypeError(`scripted executor契約違反: ${reason}`);
-}
-
-function plainRecord(value) {
-  return value !== null
-    && typeof value === 'object'
-    && !Array.isArray(value)
-    && Object.getPrototypeOf(value) === Object.prototype;
-}
-
-function validateScript(script) {
-  if (!plainRecord(script)) fail('scriptがplain objectではない');
-  for (const [todoId, steps] of Object.entries(script)) {
-    if (!Array.isArray(steps) || steps.length === 0) fail(`script.${todoId}がstep配列ではない`);
-    for (const step of steps) {
-      if (!plainRecord(step) || !STEP_KINDS.has(step.kind)) {
-        fail(`script.${todoId}に未知のstepがある: ${String(step?.kind)}`);
-      }
-    }
-    if (steps.filter((step) => step.kind === 'terminal').length > 1) {
-      fail(`script.${todoId}のterminal stepは1つまで`);
-    }
-  }
-}
-
-/**
- * script駆動のexecutor adapterを作る。
- */
-export function createScriptedExecutorAdapter(options = {}) {
-  if (!plainRecord(options) || !plainRecord(options.script)) {
-    fail('createScriptedExecutorAdapter optionsが不正');
-  }
-  validateScript(options.script);
-  const script = structuredClone(options.script);
-
-  // handle → { packet, steps, cursor, terminalReported }
-  const active = new Map();
-  // 重複拒否はtodo_id単位（task_refの付け替えによる同一TODOの二重起動と、
-  // 決定論的handleの衝突・上書きを塞ぐ。review P1採用）。redispatchは
-  // RC3-Gの新context契約が新しいadapter instanceで行う。
-  const dispatchedTodoIds = new Set();
-
-  function buildReceipt(handleState, step) {
-    const { packet } = handleState;
-    const overrides = plainRecord(step.receipt_overrides) ? step.receipt_overrides : {};
-    const receipt = {
-      schema: 'lattice.executor_receipt.v1',
-      receipt_id: `${packet.todo_id}-r1`,
-      executor_handle: handleState.executorHandle,
-      worktree_id: handleState.worktreeId,
-      base_sha: packet.base_sha,
-      plan_epoch: packet.plan_epoch,
-      packet_digest: packet.packet_digest,
-      todo_id: packet.todo_id,
-      checkpoint_digest: typeof step.checkpoint_digest === 'string'
-        ? step.checkpoint_digest
-        : (handleState.lastCheckpointDigest ?? 'c'.repeat(64)),
-      observed_diff: Array.isArray(step.observed_diff)
-        ? structuredClone(step.observed_diff)
-        : packet.scope.writes.map((path) => ({ path, change: 'modified' })),
-      ...structuredClone(overrides),
-    };
-    receipt.receipt_digest = selfDigest(receipt, 'receipt_digest');
-    return receipt;
-  }
-
-  return {
-    kind: 'scripted',
-
-    async dispatch({ packet } = {}) {
-      if (!validateExecutorPacket(packet)) fail('dispatchにはexecutor_packet.v1が必要');
-      const steps = script[packet.todo_id];
-      if (steps === undefined) fail(`scriptに存在しないTODOをdispatchできない: ${packet.todo_id}`);
-      if (dispatchedTodoIds.has(packet.todo_id)) {
-        fail(`同一TODOの重複dispatchを拒否する: ${packet.todo_id}`);
-      }
-      dispatchedTodoIds.add(packet.todo_id);
-      const executorHandle = `scripted-${packet.todo_id}-h1`;
-      const worktreeId = `wt-${packet.todo_id}`;
-      active.set(executorHandle, {
-        packet: structuredClone(packet),
-        executorHandle,
-        worktreeId,
-        steps: structuredClone(steps),
-        cursor: 0,
-        terminalReported: false,
-        lastCheckpointDigest: null,
-      });
-      return { executor_handle: executorHandle, worktree_id: worktreeId };
-    },
-
-    /**
-     * epoch rebind（Decision 7.3）: content不変のままplan epochだけを更新する。
-     * 以後のterminal receiptは新epochを名乗る（packet_digestはdispatch時の
-     * ものを保持＝dispatch記録への帰属は不変）。
-     */
-    async rebind({ executor_handle: executorHandle, rebind } = {}) {
-      const handleState = active.get(executorHandle);
-      if (handleState === undefined) fail(`未知のhandleをrebindできない: ${String(executorHandle)}`);
-      if (!plainRecord(rebind) || rebind.schema !== 'lattice.epoch_rebind_packet.v1'
-        || rebind.todo_id !== handleState.packet.todo_id) {
-        fail(`rebind packetが不正: ${String(executorHandle)}`);
-      }
-      handleState.packet.plan_epoch = rebind.new_plan_epoch;
-      return { executor_handle: executorHandle, plan_epoch: rebind.new_plan_epoch };
-    },
-
-    async observe({ executor_handle: executorHandle } = {}) {
-      const handleState = active.get(executorHandle);
-      if (handleState === undefined) fail(`未知のhandleを観測できない: ${String(executorHandle)}`);
-      if (handleState.terminalReported) {
-        fail(`terminal報告済みhandleの再観測: ${executorHandle}`);
-      }
-      if (handleState.cursor >= handleState.steps.length) {
-        return { state: 'running' };
-      }
-      const step = handleState.steps[handleState.cursor];
-      handleState.cursor += 1;
-      if (step.kind === 'stall') {
-        return { state: 'unknown' };
-      }
-      if (step.kind === 'checkpoint') {
-        if (!plainRecord(step.checkpoint)) fail('checkpoint stepにcheckpoint payloadが必要');
-        if (typeof step.checkpoint.checkpoint_digest === 'string') {
-          handleState.lastCheckpointDigest = step.checkpoint.checkpoint_digest;
-        }
-        return { state: 'checkpoint_ready', checkpoint: structuredClone(step.checkpoint) };
-      }
-      if (step.kind === 'hold_request') {
-        if (!plainRecord(step.finding)) fail('hold_request stepにfinding payloadが必要');
-        return { state: 'hold_requested', finding: structuredClone(step.finding) };
-      }
-      handleState.terminalReported = true;
-      return { state: 'terminal', receipt: buildReceipt(handleState, step) };
-    },
-  };
-}
+import { selfDigest, validateExecutorPacket } from './runtime-contracts.mjs';
+
+/**
+ * RC3-E 決定論的scripted executor adapter（ADR 0044 Decision 9）。
+ *
+ * provider非依存adapter interfaceのprimary実装。挙動はscript（TODOごとのstep列）
+ * だけで決まり、wall-clock・乱数・環境に依存しない。scripted campaign（RC3-H）が
+ * 既知の正解集合を持つ条件注入に使う。
+ *
+ * adapter interface（provider非依存契約）:
+ *   dispatch({ packet })            → { executor_handle, worktree_id }
+ *   observe({ executor_handle })    → { state: 'running' }
+ *                                    | { state: 'unknown' }                    … timeout相当
+ *                                    | { state: 'checkpoint_ready', checkpoint }
+ *                                    | { state: 'terminal', receipt }
+ *
+ * - 同一taskの重複dispatchはtyped rejectする（Decision 9.4）。
+ * - `unknown`はfailureではない。同一handleでの再observeだけが正規の回収経路で、
+ *   scriptは`stall`stepでこの経路を決定論的に再現する。
+ * - terminal receiptはdispatch済みpacketへ帰属し（handle・worktree・packet digest）、
+ *   scriptのoverridesで帰属破壊・stale epoch等の敵対条件を注入できる。
+ */
+
+const STEP_KINDS = new Set(['checkpoint', 'stall', 'hold_request', 'terminal']);
+
+function fail(reason) {
+  throw new TypeError(`scripted executor契約違反: ${reason}`);
+}
+
+function plainRecord(value) {
+  return value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function validateScript(script) {
+  if (!plainRecord(script)) fail('scriptがplain objectではない');
+  for (const [todoId, steps] of Object.entries(script)) {
+    if (!Array.isArray(steps) || steps.length === 0) fail(`script.${todoId}がstep配列ではない`);
+    for (const step of steps) {
+      if (!plainRecord(step) || !STEP_KINDS.has(step.kind)) {
+        fail(`script.${todoId}に未知のstepがある: ${String(step?.kind)}`);
+      }
+    }
+    if (steps.filter((step) => step.kind === 'terminal').length > 1) {
+      fail(`script.${todoId}のterminal stepは1つまで`);
+    }
+  }
+}
+
+/**
+ * script駆動のexecutor adapterを作る。
+ */
+export function createScriptedExecutorAdapter(options = {}) {
+  if (!plainRecord(options) || !plainRecord(options.script)) {
+    fail('createScriptedExecutorAdapter optionsが不正');
+  }
+  validateScript(options.script);
+  const script = structuredClone(options.script);
+
+  // handle → { packet, steps, cursor, terminalReported }
+  const active = new Map();
+  // 重複拒否はtodo_id単位（task_refの付け替えによる同一TODOの二重起動と、
+  // 決定論的handleの衝突・上書きを塞ぐ。review P1採用）。redispatchは
+  // RC3-Gの新context契約が新しいadapter instanceで行う。
+  const dispatchedTodoIds = new Set();
+
+  function buildReceipt(handleState, step) {
+    const { packet } = handleState;
+    const overrides = plainRecord(step.receipt_overrides) ? step.receipt_overrides : {};
+    const receipt = {
+      schema: 'lattice.executor_receipt.v1',
+      receipt_id: `${packet.todo_id}-r1`,
+      executor_handle: handleState.executorHandle,
+      worktree_id: handleState.worktreeId,
+      base_sha: packet.base_sha,
+      plan_epoch: packet.plan_epoch,
+      packet_digest: packet.packet_digest,
+      todo_id: packet.todo_id,
+      checkpoint_digest: typeof step.checkpoint_digest === 'string'
+        ? step.checkpoint_digest
+        : (handleState.lastCheckpointDigest ?? 'c'.repeat(64)),
+      observed_diff: Array.isArray(step.observed_diff)
+        ? structuredClone(step.observed_diff)
+        : packet.scope.writes.map((path) => ({ path, change: 'modified' })),
+      ...structuredClone(overrides),
+    };
+    receipt.receipt_digest = selfDigest(receipt, 'receipt_digest');
+    return receipt;
+  }
+
+  return {
+    kind: 'scripted',
+
+    async dispatch({ packet } = {}) {
+      if (!validateExecutorPacket(packet)) fail('dispatchにはexecutor_packet.v1が必要');
+      const steps = script[packet.todo_id];
+      if (steps === undefined) fail(`scriptに存在しないTODOをdispatchできない: ${packet.todo_id}`);
+      if (dispatchedTodoIds.has(packet.todo_id)) {
+        fail(`同一TODOの重複dispatchを拒否する: ${packet.todo_id}`);
+      }
+      dispatchedTodoIds.add(packet.todo_id);
+      const executorHandle = `scripted-${packet.todo_id}-h1`;
+      const worktreeId = `wt-${packet.todo_id}`;
+      active.set(executorHandle, {
+        packet: structuredClone(packet),
+        executorHandle,
+        worktreeId,
+        steps: structuredClone(steps),
+        cursor: 0,
+        terminalReported: false,
+        lastCheckpointDigest: null,
+      });
+      return { executor_handle: executorHandle, worktree_id: worktreeId };
+    },
+
+    /**
+     * epoch rebind（Decision 7.3）: content不変のままplan epochだけを更新する。
+     * 以後のterminal receiptは新epochを名乗る（packet_digestはdispatch時の
+     * ものを保持＝dispatch記録への帰属は不変）。
+     */
+    async rebind({ executor_handle: executorHandle, rebind } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleをrebindできない: ${String(executorHandle)}`);
+      if (!plainRecord(rebind) || rebind.schema !== 'lattice.epoch_rebind_packet.v1'
+        || rebind.todo_id !== handleState.packet.todo_id) {
+        fail(`rebind packetが不正: ${String(executorHandle)}`);
+      }
+      handleState.packet.plan_epoch = rebind.new_plan_epoch;
+      return { executor_handle: executorHandle, plan_epoch: rebind.new_plan_epoch };
+    },
+
+    async observe({ executor_handle: executorHandle } = {}) {
+      const handleState = active.get(executorHandle);
+      if (handleState === undefined) fail(`未知のhandleを観測できない: ${String(executorHandle)}`);
+      if (handleState.terminalReported) {
+        fail(`terminal報告済みhandleの再観測: ${executorHandle}`);
+      }
+      if (handleState.cursor >= handleState.steps.length) {
+        return { state: 'running' };
+      }
+      const step = handleState.steps[handleState.cursor];
+      handleState.cursor += 1;
+      if (step.kind === 'stall') {
+        return { state: 'unknown' };
+      }
+      if (step.kind === 'checkpoint') {
+        if (!plainRecord(step.checkpoint)) fail('checkpoint stepにcheckpoint payloadが必要');
+        if (typeof step.checkpoint.checkpoint_digest === 'string') {
+          handleState.lastCheckpointDigest = step.checkpoint.checkpoint_digest;
+        }
+        return { state: 'checkpoint_ready', checkpoint: structuredClone(step.checkpoint) };
+      }
+      if (step.kind === 'hold_request') {
+        if (!plainRecord(step.finding)) fail('hold_request stepにfinding payloadが必要');
+        return { state: 'hold_requested', finding: structuredClone(step.finding) };
+      }
+      handleState.terminalReported = true;
+      return { state: 'terminal', receipt: buildReceipt(handleState, step) };
+    },
+  };
+}

package/src/runtime-scripted-worktree.mjs

@@ -1,104 +1,104 @@
-/**
- * 管理runtimeのworker worktree配置（ADR 0143 / io-sentinel st-004）。
- *
- * **なぜ配置を契約にするのか。** supervisor daemonとscripted controllerは別プロセスであり、
- * 両者が同じ木を指す必要がある。daemonは「どこを監視し、どこのdiffを撮るか」を知らなければ
- * ならず、controllerは「どこへ書くか」を知らなければならない。dispatch応答は`worktree_id`しか
- * 運ばないので、pathを応答へ足すか、配置そのものを契約にするかの二択になる。ここでは後者を採る
- * ——**daemonが監視を張れるのはdispatchの前**であり、応答を待っていては書き込みを取り逃すからである。
- *
- * これが無かった頃、全TODOのbindingは同じrepo rootを指していた。sentinelの帰属はrootだけで
- * 決まるので、共有rootでは誰が書いたかを言えず、早期警報は成立しなかった。checkpoint判定も
- * 同じ理由で帰属を決められない。**worktreeとTODOの1対1は、装置の前提であって最適化ではない。**
- */
-
-import { spawn } from 'node:child_process';
-import { mkdir, realpath, rm } from 'node:fs/promises';
-import path from 'node:path';
-
-const GIT_SHA1 = /^[0-9a-f]{40}$/u;
-
-function fail(reason) {
-  throw new TypeError(`scripted worktree契約違反: ${reason}`);
-}
-
-function run(command, args, cwd, { allowExitCodes = [0] } = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
-    const stdout = [];
-    const stderr = [];
-    child.stdout.on('data', (chunk) => stdout.push(chunk));
-    child.stderr.on('data', (chunk) => stderr.push(chunk));
-    child.once('error', reject);
-    child.once('close', (code, signal) => {
-      if (allowExitCodes.includes(code) && signal === null) {
-        resolve(Object.assign(Buffer.concat(stdout), { code }));
-      } else {
-        reject(new TypeError(
-          `${command} ${args[0]} failed (${signal ?? code}): ${Buffer.concat(stderr).toString('utf8').trim()}`,
-        ));
-      }
-    });
-  });
-}
-
-/** worktreeの名前。packet digestへ縛るので、同じpacketには必ず同じ木が対応する。 */
-export function scriptedWorktreeId(packet) {
-  const digest = packet?.packet_digest;
-  if (typeof digest !== 'string' || !/^[0-9a-f]{64}$/u.test(digest)) {
-    fail('packet_digestが不正');
-  }
-  return `scripted-wt-${digest.slice(0, 24)}`;
-}
-
-/** run store配下のworktree path。runの寿命と一致するので、後片付けもrunに閉じる。 */
-export function scriptedWorktreePath({ runDir, packet } = {}) {
-  if (typeof runDir !== 'string' || runDir.length === 0) fail('runDirが不正');
-  return path.join(runDir, 'worktrees', scriptedWorktreeId(packet), 'tree');
-}
-
-/**
- * packetのbase shaでworktreeを用意する。既に在るなら作り直さない。
- *
- * run storeはgitignore済みなので（`requireIgnoredRunStore`）、ここに木を切っても
- * canonical repoの`git status`は汚れない。
- */
-export async function ensureScriptedWorktree({ repoRoot, runDir, packet } = {}) {
-  if (typeof repoRoot !== 'string' || repoRoot.length === 0) fail('repoRootが不正');
-  if (!GIT_SHA1.test(packet?.base_sha ?? '')) fail('packet.base_shaが不正');
-  const worktreePath = scriptedWorktreePath({ runDir, packet });
-  try {
-    return await realpath(worktreePath);
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
-  }
-  await mkdir(path.dirname(worktreePath), { recursive: true, mode: 0o700 });
-  await run('git', ['worktree', 'add', '--detach', worktreePath, packet.base_sha], repoRoot);
-  return realpath(worktreePath);
-}
-
-/**
- * runが持つworktreeを全て畳む。
- *
- * 取り残すと`git worktree list`へ積み上がり、次のrunがprune前提の状態を引き継ぐ。
- * 失敗は握り潰さず、畳めなかったpathを添えて返す——呼び出し側が記録できる形にしておく。
- */
-export async function removeScriptedWorktrees({ repoRoot, runDir } = {}) {
-  if (typeof repoRoot !== 'string' || repoRoot.length === 0) fail('repoRootが不正');
-  if (typeof runDir !== 'string' || runDir.length === 0) fail('runDirが不正');
-  const root = path.join(runDir, 'worktrees');
-  const listed = await run('git', ['worktree', 'list', '--porcelain'], repoRoot);
-  const residual = [];
-  for (const line of listed.toString('utf8').split('\n')) {
-    if (!line.startsWith('worktree ')) continue;
-    const target = line.slice('worktree '.length);
-    if (target !== root && !target.startsWith(`${root}${path.sep}`)) continue;
-    try {
-      await run('git', ['worktree', 'remove', '--force', target], repoRoot);
-    } catch {
-      residual.push(target);
-    }
-  }
-  if (residual.length === 0) await rm(root, { recursive: true, force: true });
-  return { removed_root: root, residual_paths: residual };
-}
+/**
+ * 管理runtimeのworker worktree配置（ADR 0143 / io-sentinel st-004）。
+ *
+ * **なぜ配置を契約にするのか。** supervisor daemonとscripted controllerは別プロセスであり、
+ * 両者が同じ木を指す必要がある。daemonは「どこを監視し、どこのdiffを撮るか」を知らなければ
+ * ならず、controllerは「どこへ書くか」を知らなければならない。dispatch応答は`worktree_id`しか
+ * 運ばないので、pathを応答へ足すか、配置そのものを契約にするかの二択になる。ここでは後者を採る
+ * ——**daemonが監視を張れるのはdispatchの前**であり、応答を待っていては書き込みを取り逃すからである。
+ *
+ * これが無かった頃、全TODOのbindingは同じrepo rootを指していた。sentinelの帰属はrootだけで
+ * 決まるので、共有rootでは誰が書いたかを言えず、早期警報は成立しなかった。checkpoint判定も
+ * 同じ理由で帰属を決められない。**worktreeとTODOの1対1は、装置の前提であって最適化ではない。**
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdir, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const GIT_SHA1 = /^[0-9a-f]{40}$/u;
+
+function fail(reason) {
+  throw new TypeError(`scripted worktree契約違反: ${reason}`);
+}
+
+function run(command, args, cwd, { allowExitCodes = [0] } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (allowExitCodes.includes(code) && signal === null) {
+        resolve(Object.assign(Buffer.concat(stdout), { code }));
+      } else {
+        reject(new TypeError(
+          `${command} ${args[0]} failed (${signal ?? code}): ${Buffer.concat(stderr).toString('utf8').trim()}`,
+        ));
+      }
+    });
+  });
+}
+
+/** worktreeの名前。packet digestへ縛るので、同じpacketには必ず同じ木が対応する。 */
+export function scriptedWorktreeId(packet) {
+  const digest = packet?.packet_digest;
+  if (typeof digest !== 'string' || !/^[0-9a-f]{64}$/u.test(digest)) {
+    fail('packet_digestが不正');
+  }
+  return `scripted-wt-${digest.slice(0, 24)}`;
+}
+
+/** run store配下のworktree path。runの寿命と一致するので、後片付けもrunに閉じる。 */
+export function scriptedWorktreePath({ runDir, packet } = {}) {
+  if (typeof runDir !== 'string' || runDir.length === 0) fail('runDirが不正');
+  return path.join(runDir, 'worktrees', scriptedWorktreeId(packet), 'tree');
+}
+
+/**
+ * packetのbase shaでworktreeを用意する。既に在るなら作り直さない。
+ *
+ * run storeはgitignore済みなので（`requireIgnoredRunStore`）、ここに木を切っても
+ * canonical repoの`git status`は汚れない。
+ */
+export async function ensureScriptedWorktree({ repoRoot, runDir, packet } = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) fail('repoRootが不正');
+  if (!GIT_SHA1.test(packet?.base_sha ?? '')) fail('packet.base_shaが不正');
+  const worktreePath = scriptedWorktreePath({ runDir, packet });
+  try {
+    return await realpath(worktreePath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  await mkdir(path.dirname(worktreePath), { recursive: true, mode: 0o700 });
+  await run('git', ['worktree', 'add', '--detach', worktreePath, packet.base_sha], repoRoot);
+  return realpath(worktreePath);
+}
+
+/**
+ * runが持つworktreeを全て畳む。
+ *
+ * 取り残すと`git worktree list`へ積み上がり、次のrunがprune前提の状態を引き継ぐ。
+ * 失敗は握り潰さず、畳めなかったpathを添えて返す——呼び出し側が記録できる形にしておく。
+ */
+export async function removeScriptedWorktrees({ repoRoot, runDir } = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) fail('repoRootが不正');
+  if (typeof runDir !== 'string' || runDir.length === 0) fail('runDirが不正');
+  const root = path.join(runDir, 'worktrees');
+  const listed = await run('git', ['worktree', 'list', '--porcelain'], repoRoot);
+  const residual = [];
+  for (const line of listed.toString('utf8').split('\n')) {
+    if (!line.startsWith('worktree ')) continue;
+    const target = line.slice('worktree '.length);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`)) continue;
+    try {
+      await run('git', ['worktree', 'remove', '--force', target], repoRoot);
+    } catch {
+      residual.push(target);
+    }
+  }
+  if (residual.length === 0) await rm(root, { recursive: true, force: true });
+  return { removed_root: root, residual_paths: residual };
+}