@ngockhoale/ukit 3.4.21 → 3.4.23

package/template_project/.claude/commands/ukit/handoff-implement.md

@@ -172,49 +172,64 @@ second time is what blows up the orchestrator's context window and kills the run
 
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** open each task in a separate session with the code model.
 
-### 3c — Orchestrator: copy changes to main + IMMEDIATELY delete worktree
+### 3c — Orchestrator: land each task's work (task-scoped, receipt-backed)
+
+Landing uses the shared helper, never an ad-hoc cp loop. `land-worktree.mjs` snapshots
+the source worktree's FINAL content relative to the immutable `$BASE` — committed
+milestone, staged, unstaged and nonignored untracked changes, with deletions, rename
+origins and binary / executable / symlink semantics — and applies that exact delta to the
+destination. It refuses (exit 2, no mutation, no receipt) on a dirty destination, a
+target-path untracked collision, an out-of-scope change or identity drift.
 
 For each task that reported back:
 
 **PASS + EXECUTOR_MODEL present:**
 ```bash
+TASK="TASK-xxx"
 WORKTREE=".worktrees/task-xxx"
 
-# Copy modified tracked files to main working tree
-git -C "$WORKTREE" diff --name-only | while read f; do
-  mkdir -p "$(dirname "$f")"
-  cp "$WORKTREE/$f" "$f"
-done
-
-# Copy new untracked files
-git -C "$WORKTREE" ls-files --others --exclude-standard | while read f; do
-  mkdir -p "$(dirname "$f")"
-  cp "$WORKTREE/$f" "$f"
-done
-
-# Delete worktree and branch immediately
-git worktree remove "$WORKTREE" --force
-git branch -D handoff/task-xxx
+# Scope file: exact task-approved target paths (both rename endpoints). Written
+# outside the source worktree AND outside the target set.
+cat > ".worktrees/$TASK-scope.json" <<JSON
+{
+  "schemaVersion": 1,
+  "taskId": "$TASK",
+  "baseCommit": "$BASE",
+  "sourceRoot": "$(git -C "$WORKTREE" rev-parse --show-toplevel)",
+  "destinationRoot": "$(git rev-parse --show-toplevel)",
+  "sourceHead": "$(git -C "$WORKTREE" rev-parse HEAD)",
+  "destinationHead": "$(git rev-parse HEAD)",
+  "targetPaths": ["<each approved path>"]
+}
+JSON
+
+node .claude/ukit/index/land-worktree.mjs \
+  --scope ".worktrees/$TASK-scope.json" \
+  --receipt "docs/AI_HANDOFF/benchmark/$TASK-landing.json"
+# exit 0 → landed; exit 2 → refused (untouched); exit 1 → apply/receipt failure.
+# After each exit-0 landing, checkpoint-commit the landed paths (receipt stays outside the target set)
+# BEFORE landing the next task: the helper refuses a destination with tracked modifications
+# (destination-dirty), so uncommitted landed work would block every later task in the wave.
+git add -- <landed paths> && git commit -m "checkpoint: $TASK landed"
 
 # update INDEX.md: status → pending_review
 ```
 
 **FAIL:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# No landing for a FAIL report — retain the worktree and branch as recovery evidence.
 # update INDEX.md: status → blocked
 ```
 
 **EXECUTOR_MODEL missing:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# No model attestation → no landing authority. Retain the worktree and branch.
 # update INDEX.md: status → needs_executor_report
 ```
 
 **Orchestrator writes INDEX.md** — agents never touch INDEX directly.
-**Worktrees are always deleted immediately** — no exceptions.
+Worktree/branch removal is a separate, receipt-gated step (`cleanup-task-worktree.mjs`) —
+never an unconditional forced removal or branch deletion sitting next to the landing.
 
 ### 3d — Wave boundary: commit + context checkpoint
 
@@ -246,12 +261,18 @@ Then create the next wave's worktrees from `$BASE` and repeat 3a–3c.
 All waves complete. Verify:
 
 ```bash
-git worktree list          # must show only main worktree
-git branch | grep handoff  # must be empty
+git worktree list          # every remaining .worktrees/* entry must be named in the retained-reason report
+git branch | grep handoff  # every handoff/* branch must be named in the retained-reason report
 git log --oneline -n 10    # one commit per wave
 git status                 # clean, or only trailing edits from the last wave
 ```
 
+Every remaining `.worktrees/*` entry and every `handoff/*` branch must be named in a
+**retained-reason report**: receipt missing, not approved, FAIL, missing model, dirty vs
+snapshot, unmerged history. Unexplained leftovers fail the gate; nothing is removed by force.
+An eligible task is retired only through the shared, receipt-gated helper
+(`node .claude/ukit/index/cleanup-task-worktree.mjs --receipt <json> --approval <json> --apply`).
+
 All changes are committed as **one commit per wave on `$BASE`**, nothing pushed. No branches
 or worktrees remain. Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 

package/template_project/.claude/hooks/handoff-resume.sh

@@ -196,11 +196,21 @@ async function emitOrdinaryResume(payload, source) {
   // The session's CURRENT handoff intent — structured transcript evidence, the
   // same shared module the Stop gate uses. A session whose latest request is
   // planning (`/ukit:handoff-create`) must never be pushed into implementing a
-  // stale RUN.md, compact or not. `known` false (no transcript path, unreadable,
-  // module absent) keeps the existing resume behaviour.
+  // stale RUN.md, compact or not. `intent` is null when the read was unknown (no
+  // transcript path, unreadable, module absent), which the planning-cursor branch
+  // below treats the same as create — a NONTERMINAL `Command: handoff-create`
+  // cursor is the planner's file, so an unknown read resolves toward planning.
   const { intent } = await readHandoffIntent(
     typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
   );
+  // A NONTERMINAL planning cursor is the one RUN.md the resume lane treats as
+  // planning rather than implementation (TASK-C97-006, FR-M2-003): its `Command`
+  // says a planner owns the file, so any latest intent that is NOT positively
+  // implementation (create, known-null, unknown) gets the planning note. Every
+  // other command — actual fullstack/implement/review — keeps the unchanged
+  // contract, and an unknown intent there still resolves toward the conservative
+  // resume, so a lost read never strands a real run.
+  const planningCursor = field('Command').trim().toLowerCase() === 'handoff-create';
 
   // A brand-new session (startup / clear) did not start this run and may be about
   // something else entirely (e.g. planning). Tell it the run exists, but do NOT
@@ -216,17 +226,32 @@ async function emitOrdinaryResume(payload, source) {
     process.exit(0);
   }
 
-  // Planning intent outranks a live cursor: the user asked this session to plan,
-  // so report the paused run and let the planning continue. This is the one place
-  // an automatic resume must yield — /ukit:handoff-create is planning-only by
-  // contract, and /ukit:handoff-fullstack remains the explicit way to resume.
-  if (intent === 'create') {
+  // Planning outranks a live cursor: the user asked this session to plan (or the
+  // cursor itself is the planner's `handoff-create` RUN.md with no positive
+  // implementation intent), so report the paused run and let the planning
+  // continue. This is the one place an automatic resume must yield —
+  // /ukit:handoff-create is planning-only by contract, and /ukit:handoff-fullstack
+  // remains the explicit way to resume.
+  if (intent === 'create' || (planningCursor && intent !== 'fullstack')) {
+    // The reason is stated honestly either way — the session's own request is
+    // planning (create), or the cursor itself is the planner's `handoff-create`
+    // RUN.md with no positive implementation intent. Neither fabricates ownership.
+    const why = intent === 'create'
+      ? [
+        "but this session's current request",
+        'is planning (/ukit:handoff-create). Stop gate and resume will not force the run here —',
+        'finish the planning first. To resume implementation explicitly, run /ukit:handoff-fullstack;',
+        'to discard the run, /ukit:handoff-clear.',
+      ]
+      : [
+        `and its cursor is planning-only (Command: ${field('Command')}). Neither the Stop gate nor this`,
+        'resume will force implementation here. To resume implementation explicitly, run',
+        '/ukit:handoff-fullstack; to discard the run, /ukit:handoff-clear.',
+      ];
     process.stdout.write([
       'UKit note: docs/AI_HANDOFF/RUN.md has an unfinished handoff-fullstack run '
-        + `(Phase: ${phase}; Next: ${next || 'not recorded'}), but this session's current request`,
-      'is planning (/ukit:handoff-create). Stop gate and resume will not force the run here —',
-      'finish the planning first. To resume implementation explicitly, run /ukit:handoff-fullstack;',
-      'to discard the run, /ukit:handoff-clear.',
+        + `(Phase: ${phase}; Next: ${next || 'not recorded'}),`,
+      ...why,
     ].join('\n') + '\n');
     process.exit(0);
   }

package/template_project/.claude/hooks/protect-files.sh

@@ -102,7 +102,15 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-BASENAME=$(basename "$FILE_PATH")
+# TASK-C97-008 (FR-M3-002): match backslash / Windows-shaped spellings the same
+# as forward-slash ones. Normalize separators for LEXICAL basename/component
+# matching ONLY — no filesystem resolution, no path writes, and no native
+# Windows claim. `${var//pat/rep}` is a bash builtin, so this holds with or
+# without jq. The original path stays in the stderr diagnostic; stdout keeps the
+# generic reason and never exposes it.
+MATCH_PATH="${FILE_PATH//\\//}"
+
+BASENAME=$(basename "$MATCH_PATH")
 
 # Allow .env.example explicitly
 if [[ "$BASENAME" == ".env.example" ]]; then
@@ -112,7 +120,7 @@ fi
 # Match exact sensitive filenames and directory components, never arbitrary substrings:
 # `.env.d.ts` and `app.envrc` are source files, not secrets. The old `*".env"*`
 # check blocked both, which could appear as a mysterious stopped edit.
-PATH_SLASHED="/${FILE_PATH#/}"
+PATH_SLASHED="/${MATCH_PATH#/}"
 PROTECTED_MATCH=""
 case "$BASENAME" in
   .env|.env.local|.env.production|package-lock.json|yarn.lock)

package/template_project/.claude/hooks/vision-router.sh

@@ -326,6 +326,13 @@ async function readTextSafe(filePath) {
   const pendingMarkers = Array.isArray(extractorJson?.pendingMarkers)
     ? extractorJson.pendingMarkers
     : [];
+  // Additive (SPEC FR-M5-001 §7/§8): a currently-named input whose marker already
+  // existed is NOT newly armed, so it must not drive the NEW hint. It is still a
+  // KNOWN local ref, so it must not fall through to the unresolved-path advisory
+  // either. Absent (older extractor) degrades to [], i.e. today's behavior.
+  const alreadyPending = Array.isArray(extractorJson?.alreadyPending)
+    ? extractorJson.alreadyPending
+    : [];
   const analyzed = Array.isArray(extractorJson?.alreadyAnalyzed) ? extractorJson.alreadyAnalyzed : [];
   const sessionId = typeof extractorJson?.sessionId === 'string' && extractorJson.sessionId
     ? extractorJson.sessionId
@@ -334,9 +341,12 @@ async function readTextSafe(filePath) {
   const armedRefs = new Set(
     pendingMarkers.filter((m) => typeof m?.ref === 'string').map((m) => m.ref)
   );
+  const pendingRefs = new Set(
+    alreadyPending.filter((m) => typeof m?.ref === 'string').map((m) => m.ref)
+  );
   const analyzedRefs = new Set(analyzed.filter((a) => typeof a?.ref === 'string').map((a) => a.ref));
   const unresolvedLocal = localMatches.filter(
-    (m) => !armedRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
+    (m) => !armedRefs.has(m.trim()) && !pendingRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
   );
   const cases = [];
   if (pendingMarkers.some((m) => !m?.source)) cases.push('pasted image');

package/template_project/.claude/ukit/index/cleanup-task-worktree.mjs

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+/**
+ * cleanup-task-worktree.mjs — receipt-gated, recoverable task cleanup
+ * (C97 TASK-C97-010 · MODULE04-SPEC FR-M4-003/003a · §7–§14).
+ *
+ * The shipped handoff samples removed task worktrees with
+ * `git worktree remove <wt> --force` plus `git branch -D "handoff/<name>"`, so a
+ * FAIL, an unreported task or a missing-model task lost its recovery evidence,
+ * and the final gate kept a global "only main worktree must remain" assertion
+ * that force-deleted anything left over. This helper replaces that with one
+ * narrow, fail-closed contract:
+ *
+ *   node .claude/ukit/index/cleanup-task-worktree.mjs \
+ *     --receipt <json-path> --approval <json-path> [--apply]
+ *
+ * Dry-run is the default and mutates nothing. `--apply` removes EXACTLY the one
+ * worktree named by a verified C97-009 landing receipt whose result has been
+ * independently Approved, and only when the source still matches the receipt
+ * snapshot, is Git-clean, unlocked and carries no active run. The worktree is
+ * removed WITHOUT `--force`; the branch is deleted only with safe `-d` when
+ * ancestry is provable, otherwise it is retained and reported. Unrelated,
+ * dirty, active, locked, stale or unapproved state is retained with a named
+ * reason — never destroyed.
+ *
+ * Authority (SPEC §7): the receipt is an attestation backed by a sha256, and
+ * the approval is a plain file; the receipt and approval paths must lie OUTSIDE
+ * the source worktree and outside the receipt's changed set, so an executor
+ * cannot self-author authority inside its own tree. The receipt is never reused
+ * for a different root or task.
+ *
+ * CLI: --help exits 0. stdout is one JSON object:
+ *   { status: "retained" | "eligible" | "removed", taskId, reason, branchRetained }
+ * exit 0 dry-run / retained / removed; exit 2 invalid input or authority;
+ * exit 1 a Git runtime failure (a removal failure retains the branch). A
+ * retained result is never a successful removal.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.UKIT_CLEANUP_GIT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 20000;
+})();
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+const USAGE = `cleanup-task-worktree.mjs — receipt-gated recoverable task cleanup
+
+Usage:
+  node cleanup-task-worktree.mjs --receipt <json-path> --approval <json-path> [--apply]
+  node cleanup-task-worktree.mjs --help
+
+Dry-run is the default (mutates nothing). --apply removes EXACTLY the one
+worktree named by a verified C97-009 landing receipt whose result is Approved,
+never with --force; an unmerged branch is retained. exit 0 dry-run/retained/
+removed; exit 2 invalid input/authority; exit 1 Git runtime failure.`;
+
+// --- bounded git -------------------------------------------------------------
+
+function git(root, args) {
+  return spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: MAX_BUFFER,
+  });
+}
+
+// --- exit contract -----------------------------------------------------------
+
+function emit(status, taskId, reason, branchRetained) {
+  process.stdout.write(`${JSON.stringify({
+    status,
+    taskId: taskId ?? null,
+    reason,
+    branchRetained,
+  })}\n`);
+}
+
+// Invalid input or authority: the task is retained (never removed) and the
+// process exits 2. A bounded diagnostic never includes file contents.
+function refuse(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`cleanup-task-worktree: ${reason}: ${diagnostic}\n`);
+  emit('retained', taskId, reason, true);
+  process.exit(2);
+}
+
+// A named recovery state (not invalid authority): retained, exit 0.
+function retain(taskId, reason) {
+  emit('retained', taskId, reason, true);
+  process.exit(0);
+}
+
+function runtimeError(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`cleanup-task-worktree: ${reason}: ${diagnostic}\n`);
+  emit('retained', taskId, reason, true);
+  process.exit(1);
+}
+
+// --- args --------------------------------------------------------------------
+
+const argv = process.argv.slice(2);
+let receiptPath = null;
+let approvalPath = null;
+let apply = false;
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i];
+  if (a === '--help' || a === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    process.exit(0);
+  } else if (a === '--apply') {
+    apply = true;
+  } else if (a === '--receipt') {
+    receiptPath = argv[++i];
+    if (receiptPath === undefined) { process.stderr.write('cleanup-task-worktree: missing value for --receipt\n'); process.exit(2); }
+  } else if (a === '--approval') {
+    approvalPath = argv[++i];
+    if (approvalPath === undefined) { process.stderr.write('cleanup-task-worktree: missing value for --approval\n'); process.exit(2); }
+  } else {
+    process.stderr.write(`cleanup-task-worktree: unknown argument: ${a}\n${USAGE}\n`);
+    process.exit(2);
+  }
+}
+if (!receiptPath || !approvalPath) {
+  process.stderr.write(`cleanup-task-worktree: --receipt and --approval are both required\n${USAGE}\n`);
+  process.exit(2);
+}
+
+// --- path helpers ------------------------------------------------------------
+
+const realPath = (p) => {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+};
+// Resolve symlinks in the longest existing ancestor, then append the remaining
+// segments (macOS /var → /private/var makes a naive resolve a different string).
+function resolveReal(p) {
+  const abs = path.resolve(p);
+  const root = path.parse(abs).root;
+  const parts = abs.slice(root.length).split(path.sep).filter(Boolean);
+  let cur = root;
+  let i = 0;
+  for (; i < parts.length; i += 1) {
+    const next = path.join(cur, parts[i]);
+    if (fs.existsSync(next)) cur = next; else break;
+  }
+  return path.join(realPath(cur), ...parts.slice(i));
+}
+const isInsideOrEqual = (child, parent) => {
+  const c = resolveReal(child);
+  const p = realPath(parent);
+  return c === p || c.startsWith(p + path.sep);
+};
+
+const sha256File = (p) => crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+
+// --- schema ------------------------------------------------------------------
+
+const RECEIPT_KEYS = [
+  'schemaVersion', 'taskId', 'baseCommit', 'sourceRoot', 'destinationRoot',
+  'sourceBranch', 'sourceHead', 'destinationHeadBefore', 'sourceSnapshotTree',
+  'resultTree', 'patchSha256', 'scopeSha256', 'changedPaths', 'createdAt', 'status',
+];
+const APPROVAL_KEYS = [
+  'schemaVersion', 'taskId', 'receiptSha256', 'verdict', 'executorModel',
+  'reviewerModel', 'reviewedResultTree',
+];
+const TASK_TOKEN = /^TASK-C97-\d{3}$/;
+const OID = /^[0-9a-f]{40}$/;
+
+function readJson(p, taskId, label) {
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch {
+    refuse(taskId, 'invalid-authority', `${label} file unreadable`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    refuse(taskId, 'invalid-authority', `${label} is not valid JSON`);
+  }
+}
+
+function validateReceipt(receipt) {
+  const taskId = receipt && typeof receipt === 'object' ? receipt.taskId : null;
+  if (receipt === null || typeof receipt !== 'object' || Array.isArray(receipt)) {
+    refuse(null, 'invalid-authority', 'receipt must be a JSON object');
+  }
+  for (const key of Object.keys(receipt)) {
+    if (!RECEIPT_KEYS.includes(key)) refuse(taskId, 'invalid-authority', `unknown receipt key: ${key}`);
+  }
+  if (receipt.schemaVersion !== 1) refuse(taskId, 'invalid-authority', 'receipt schemaVersion must be 1');
+  if (typeof receipt.taskId !== 'string' || !TASK_TOKEN.test(receipt.taskId)) {
+    refuse(taskId, 'invalid-authority', 'receipt taskId must be an exact TASK-C97-NNN token');
+  }
+  if (receipt.status !== 'landed') refuse(taskId, 'invalid-authority', 'receipt status must be "landed"');
+  for (const k of ['baseCommit', 'sourceRoot', 'destinationRoot', 'sourceHead', 'sourceSnapshotTree', 'resultTree', 'patchSha256', 'scopeSha256']) {
+    if (typeof receipt[k] !== 'string' || receipt[k].length === 0) {
+      refuse(taskId, 'invalid-authority', `receipt ${k} must be a nonempty string`);
+    }
+  }
+  for (const k of ['sourceSnapshotTree', 'resultTree']) {
+    if (!OID.test(receipt[k])) refuse(taskId, 'invalid-authority', `receipt ${k} must be a full tree OID`);
+  }
+  if (receipt.sourceBranch !== null && typeof receipt.sourceBranch !== 'string') {
+    refuse(taskId, 'invalid-authority', 'receipt sourceBranch must be a string or null');
+  }
+  if (!Array.isArray(receipt.changedPaths)) {
+    refuse(taskId, 'invalid-authority', 'receipt changedPaths must be an array');
+  }
+  for (const p of receipt.changedPaths) {
+    if (typeof p !== 'string' || p.length === 0) refuse(taskId, 'invalid-authority', 'receipt changedPaths entries must be nonempty strings');
+  }
+  return receipt.taskId;
+}
+
+function validateApproval(approval, receipt, receiptSha, taskId) {
+  if (approval === null || typeof approval !== 'object' || Array.isArray(approval)) {
+    refuse(taskId, 'invalid-authority', 'approval must be a JSON object');
+  }
+  for (const key of Object.keys(approval)) {
+    if (!APPROVAL_KEYS.includes(key)) refuse(taskId, 'invalid-authority', `unknown approval key: ${key}`);
+  }
+  if (approval.schemaVersion !== 1) refuse(taskId, 'invalid-authority', 'approval schemaVersion must be 1');
+  if (approval.taskId !== taskId) refuse(taskId, 'invalid-authority', 'approval taskId does not match the receipt');
+  if (approval.receiptSha256 !== receiptSha) refuse(taskId, 'invalid-authority', 'approval receiptSha256 does not match the receipt');
+  if (approval.verdict !== 'Approved') refuse(taskId, 'invalid-authority', 'approval verdict must be "Approved"');
+  if (typeof approval.executorModel !== 'string' || approval.executorModel.length === 0) {
+    refuse(taskId, 'invalid-authority', 'approval executorModel must be a nonempty string');
+  }
+  if (typeof approval.reviewerModel !== 'string' || approval.reviewerModel.length === 0) {
+    refuse(taskId, 'invalid-authority', 'approval reviewerModel must be a nonempty string');
+  }
+  if (approval.reviewerModel === approval.executorModel) {
+    refuse(taskId, 'invalid-authority', 'approval reviewerModel must differ from executorModel');
+  }
+  if (approval.reviewedResultTree !== receipt.resultTree) {
+    refuse(taskId, 'invalid-authority', 'approval reviewedResultTree does not match the receipt resultTree');
+  }
+}
+
+// --- state helpers -----------------------------------------------------------
+
+function registeredWorktrees(root) {
+  const res = git(root, ['worktree', 'list', '--porcelain']);
+  if (res.status !== 0) runtimeError(null, 'git-failure', 'worktree list failed');
+  const out = [];
+  let cur = null;
+  for (const line of res.stdout.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) out.push(cur);
+      cur = { path: line.slice('worktree '.length), branch: null, locked: false };
+    } else if (cur) {
+      if (line.startsWith('branch ')) cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+      else if (line.startsWith('locked')) cur.locked = true;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+function hasActiveRun(root) {
+  try {
+    const runsDir = path.join(root, '.ukit', 'storage', 'runs');
+    if (fs.statSync(runsDir).isDirectory() && fs.readdirSync(runsDir).some((f) => f.endsWith('.json'))) {
+      return true;
+    }
+  } catch { /* absent */ }
+  try {
+    const raw = fs.readFileSync(path.join(root, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const m = raw.match(/^Phase:\s*(\S+)/m);
+    if (m && m[1] !== 'done' && m[1] !== 'blocked') return true;
+  } catch { /* no cursor */ }
+  return false;
+}
+
+// Snapshot a worktree's FINAL content via an isolated temp index (never the
+// repository's real index) — the same definition the landing helper used.
+function worktreeTree(root) {
+  const idx = path.join(os.tmpdir(), `ukit-cleanup-${process.pid}-${crypto.randomBytes(6).toString('hex')}.index`);
+  try {
+    const env = { ...process.env, GIT_INDEX_FILE: idx };
+    for (const args of [['read-tree', 'HEAD'], ['add', '-A']]) {
+      const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL', env, maxBuffer: MAX_BUFFER });
+      if (r.status !== 0) runtimeError(null, 'git-failure', r.stderr?.split('\n')[0] ?? 'snapshot failed');
+    }
+    const t = spawnSync('git', ['-C', root, 'write-tree'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL', env, maxBuffer: MAX_BUFFER });
+    if (t.status !== 0) runtimeError(null, 'git-failure', t.stderr?.split('\n')[0] ?? 'write-tree failed');
+    return t.stdout.trim();
+  } finally {
+    try { fs.rmSync(idx, { force: true }); } catch { /* absent */ }
+  }
+}
+
+// mode+object of `path` in `treeish` (null when the path is absent — a deletion).
+function treeEntry(root, treeish, p) {
+  const r = git(root, ['ls-tree', '-z', treeish, '--', p]);
+  if (r.status !== 0 || !r.stdout) return null;
+  const row = r.stdout.split('\0').find((x) => x.length > 0);
+  if (!row) return null;
+  const [meta] = row.split('\t');
+  const [mode, , object] = meta.split(' ');
+  return `${mode}:${object}`;
+}
+
+// --- main --------------------------------------------------------------------
+
+function main() {
+  const receipt = readJson(receiptPath, null, 'receipt');
+  const taskId = validateReceipt(receipt);
+  const receiptSha = sha256File(receiptPath);
+  const approval = readJson(approvalPath, taskId, 'approval');
+  validateApproval(approval, receipt, receiptSha, taskId);
+
+  // Authority locations (SPEC §7): outside the source worktree and outside the
+  // receipt's changed set. An executor must not self-author authority in its own
+  // tree or in a path the landing already touched.
+  const sourceRoot = realPath(receipt.sourceRoot);
+  // The receipt changedPaths are DESTINATION-relative (they name what the landing
+  // wrote into the destination). Resolve the containment against BOTH roots: an
+  // authority file sitting at a changed path inside the destination worktree is
+  // just as unsafe as one inside the source worktree, and resolving only against
+  // sourceRoot would silently miss it (review F1).
+  const dstRootForAuthority = realPath(receipt.destinationRoot);
+  // A path is inside `base` only when its base-relative form is not a PARENT
+  // escape. The boundary is the exact `..` segment (or a `../` prefix) — NOT any
+  // `..`-prefixed name, because `..hidden.txt` is a legal repo-relative filename
+  // and a naive `startsWith('..')` would treat it as outside the root and let an
+  // authority file at that changed path bypass the containment check (review F2).
+  // An absolute result (`path.relative` on different drives) is also outside.
+  const containedIn = (base, abs) => {
+    const rel = path.relative(base, abs).split(path.sep).join('/');
+    if (!rel || path.isAbsolute(rel) || rel === '..' || rel.startsWith('../')) return null;
+    return rel;
+  };
+  for (const [label, p] of [['receipt', receiptPath], ['approval', approvalPath]]) {
+    if (isInsideOrEqual(p, sourceRoot)) {
+      refuse(taskId, 'invalid-authority', `${label} path is inside the source worktree`);
+    }
+    const abs = resolveReal(p);
+    for (const base of [sourceRoot, dstRootForAuthority]) {
+      const rel = containedIn(base, abs);
+      if (!rel) continue;
+      for (const changed of receipt.changedPaths) {
+        if (rel === changed || rel.startsWith(`${changed}/`)) {
+          refuse(taskId, 'invalid-authority', `${label} path is inside the receipt changed set`);
+        }
+      }
+    }
+  }
+
+  if (!fs.existsSync(sourceRoot)) retain(taskId, 'source-missing');
+  const destinationRoot = realPath(receipt.destinationRoot);
+  if (!fs.existsSync(destinationRoot)) runtimeError(taskId, 'git-failure', 'destination root is not present');
+
+  // The source must be a registered, unlocked worktree of the same common repo.
+  const worktrees = registeredWorktrees(destinationRoot);
+  const entry = worktrees.find((w) => realPath(w.path) === sourceRoot);
+  if (!entry) refuse(taskId, 'invalid-authority', 'source root is not a registered worktree');
+  if (entry.locked) retain(taskId, 'locked');
+
+  // The task must not carry an in-flight run.
+  if (hasActiveRun(sourceRoot)) retain(taskId, 'active');
+
+  // Revalidate the exact source identity and content against the receipt.
+  const headRes = git(sourceRoot, ['rev-parse', 'HEAD']);
+  if (headRes.status !== 0) retain(taskId, 'source-head-unreadable');
+  if (headRes.stdout.trim() !== receipt.sourceHead) retain(taskId, 'source-head-changed');
+  const branchRes = git(sourceRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const branch = branchRes.status === 0 ? branchRes.stdout.trim() : null;
+  if ((receipt.sourceBranch ?? null) !== branch) retain(taskId, 'source-branch-changed');
+
+  // "Dirty" = the source tree differs from the receipt snapshot (tracked, staged
+  // or nonignored untracked content). A snapshot-identical tree is Git-clean and
+  // `git worktree remove` succeeds without --force.
+  if (worktreeTree(sourceRoot) !== receipt.sourceSnapshotTree) retain(taskId, 'dirty-vs-snapshot');
+
+  // Destination path-scoped verification: for every receipt changedPath, the
+  // blob (or absence, for a deletion) in the destination HEAD must equal the
+  // receipt resultTree — the checkpoint commit may move HEAD, so no blind
+  // whole-tree equality.
+  for (const p of receipt.changedPaths) {
+    const expected = treeEntry(destinationRoot, receipt.resultTree, p);
+    const actual = treeEntry(destinationRoot, 'HEAD', p);
+    if (expected !== actual) retain(taskId, 'destination-path-changed');
+  }
+
+  if (!apply) {
+    emit('eligible', taskId, 'eligible', true);
+    process.exit(0);
+  }
+
+  // Remove the registered worktree WITHOUT --force. A refusal or failure (dirty
+  // by Git's own definition, locked, etc.) is a runtime failure that keeps the
+  // worktree and branch — never escalated to --force.
+  const rm = git(destinationRoot, ['worktree', 'remove', sourceRoot]);
+  if (rm.status !== 0) {
+    runtimeError(taskId, 'remove-failed', (rm.stderr || '').split('\n')[0] || 'git worktree remove failed');
+  }
+  if (fs.existsSync(sourceRoot)) {
+    runtimeError(taskId, 'remove-failed', 'worktree still present after removal');
+  }
+
+  // Delete the branch only with safe `-d` when ancestry is provable; an
+  // unmerged milestone branch is retained as recovery evidence (never -D).
+  let branchRetained = true;
+  if (branch) {
+    const del = git(destinationRoot, ['branch', '-d', branch]);
+    branchRetained = del.status !== 0;
+  }
+  emit('removed', taskId, branchRetained ? 'removed-branch-retained' : 'removed', branchRetained);
+  process.exit(0);
+}
+
+main();