chainlesschain 0.162.162 → 0.162.164

package/src/lib/turn-binding-store.js

@@ -0,0 +1,119 @@
+/**
+ * Persist the explicit turn→checkpoint binding table ([[turn-binding.js]]) as a
+ * tamper-evident chained event in the session transcript — the first half of the
+ * P1 gap "把绑定作为新链式事件落 jsonl-session-store.js（继承哈希链防篡改，替代
+ * 易失的 `_checkpointMarks`）".
+ *
+ * The REPL's in-process `_checkpointMarks` array is lost the moment the session
+ * ends or the process exits, so a resumed session can't offer a coverage-aware
+ * rewind for anything from before the restart. Snapshotting the whole
+ * `TurnBindingLog` into an append-only `turn_checkpoint_binding` event makes the
+ * binding survive resume AND inherit the transcript's hash chain (tamper
+ * evidence), exactly like every other session event.
+ *
+ * All I/O is delegated to the canonical session store via `_deps` so this module
+ * stays pure-testable (inject an in-memory append/read pair — no fs, no home dir).
+ */
+
+import {
+  appendEvent as storeAppendEvent,
+  readEvents as storeReadEvents,
+} from "../harness/jsonl-session-store.js";
+import {
+  TurnBindingLog,
+  resolveRestorePlan,
+  selectTurnRange,
+  RESTORE_SCOPE,
+} from "./turn-binding.js";
+
+/** Event type carrying a full TurnBindingLog snapshot. */
+export const TURN_BINDING_EVENT = "turn_checkpoint_binding";
+
+// Injected so tests can drive persistence without touching the real sessions dir.
+export const _deps = {
+  appendEvent: storeAppendEvent,
+  readEvents: storeReadEvents,
+};
+
+/**
+ * Append the current binding table as a new chained event. Each call writes the
+ * FULL table (append-only snapshot), so the newest event is authoritative — a
+ * later `loadTurnBindingLog` never has to merge partial deltas across a chain
+ * that a compaction could have truncated.
+ *
+ * Best-effort: a persistence failure must not crash the turn it is recording, so
+ * the caller gets `false` instead of a throw.
+ *
+ * @param {string} sessionId
+ * @param {TurnBindingLog|object} log  a TurnBindingLog or its toJSON() shape
+ * @returns {boolean} true when the snapshot was written
+ */
+export function persistTurnBinding(sessionId, log) {
+  if (!sessionId || !log) return false;
+  const snapshot = log instanceof TurnBindingLog ? log.toJSON() : log;
+  if (!snapshot || !Array.isArray(snapshot.turns)) return false;
+  try {
+    _deps.appendEvent(sessionId, TURN_BINDING_EVENT, snapshot);
+    return true;
+  } catch {
+    // Persistence is advisory — never let it break the agent turn.
+    return false;
+  }
+}
+
+/**
+ * Rebuild the TurnBindingLog from the LATEST persisted snapshot in a session
+ * transcript. Returns an empty log when the session has no binding event (or on
+ * any read error) so callers can treat "never persisted" and "unreadable" alike.
+ *
+ * @param {string} sessionId
+ * @returns {TurnBindingLog}
+ */
+export function loadTurnBindingLog(sessionId) {
+  let events = [];
+  try {
+    events = _deps.readEvents(sessionId) || [];
+  } catch {
+    return new TurnBindingLog();
+  }
+  // Newest snapshot wins — scan backwards for the first well-formed one.
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i];
+    if (
+      e &&
+      e.type === TURN_BINDING_EVENT &&
+      e.data &&
+      Array.isArray(e.data.turns)
+    ) {
+      return TurnBindingLog.fromJSON(e.data);
+    }
+  }
+  return new TurnBindingLog();
+}
+
+/**
+ * Compose load + plan: resolve the honest restore plan for one turn of a
+ * PERSISTED session, so a resumed `/rewind` can show coverage warnings for a
+ * turn taken before the restart. Delegates the over-promise guards to
+ * `resolveRestorePlan` (unknown turn → a "nothing to restore" plan).
+ *
+ * @param {string} sessionId
+ * @param {string} turnId
+ * @param {string} [scope]  one of RESTORE_SCOPE
+ */
+export function resolveRestorePlanFromSession(
+  sessionId,
+  turnId,
+  scope = RESTORE_SCOPE.BOTH,
+) {
+  const log = loadTurnBindingLog(sessionId);
+  return resolveRestorePlan(log.get(turnId), scope);
+}
+
+/**
+ * Compose load + range select for "Summarize from here / up to here" over a
+ * persisted session's turns.
+ */
+export function selectTurnRangeFromSession(sessionId, range = {}) {
+  return selectTurnRange(loadTurnBindingLog(sessionId), range);
+}

package/src/lib/unattended-action-policy.js

@@ -0,0 +1,182 @@
+/**
+ * Unattended-action policy — the fail-closed guard behind P1-8's
+ * "默认禁止无人值守发布、合并或修改共享基础设施" of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md.
+ *
+ * A scheduled or event-driven session runs with NO human watching, and P1-8 is
+ * explicit that external trigger content is untrusted by default. [[cost-budget.js]]
+ * already caps USD spend and [[schedule-planner.js]] decides WHEN a task fires,
+ * but nothing decides WHAT a fired task may irreversibly do. Publishing a
+ * package, merging a PR, deploying, or mutating shared infrastructure while
+ * unattended is exactly the class of action that must never happen ambiently.
+ *
+ * This module is that pure decision. Given an action's risk class and the run's
+ * context (attended? trigger trusted? explicitly allowlisted? within budget?) it
+ * returns allow/deny with a named reason. Everything defaults to DENY: an
+ * unrecognized action on an unattended run is refused, not assumed safe.
+ *
+ * PURE: no fs / clock / RNG / process.
+ */
+
+/** Canonical action classes, ordered low → high consequence. */
+export const ACTION_CLASS = Object.freeze({
+  READ: "read",
+  LOCAL_WRITE: "local_write", // edit files in the worktree
+  COMMIT: "commit", // local commit (reversible, not shared)
+  PUSH: "push", // push a branch to a remote
+  PUBLISH: "publish", // npm publish / release — irreversible & public
+  MERGE: "merge", // merge a PR into a shared branch
+  DEPLOY: "deploy", // deploy / roll out
+  INFRA_MUTATION: "infra_mutation", // modify shared infrastructure
+  EXTERNAL_MESSAGE: "external_message", // send mail / chat / webhook outward
+});
+
+const ACTION_ALIASES = new Map([
+  ["read", ACTION_CLASS.READ],
+  ["local_write", ACTION_CLASS.LOCAL_WRITE],
+  ["write", ACTION_CLASS.LOCAL_WRITE],
+  ["edit", ACTION_CLASS.LOCAL_WRITE],
+  ["commit", ACTION_CLASS.COMMIT],
+  ["push", ACTION_CLASS.PUSH],
+  ["publish", ACTION_CLASS.PUBLISH],
+  ["release", ACTION_CLASS.PUBLISH],
+  ["merge", ACTION_CLASS.MERGE],
+  ["deploy", ACTION_CLASS.DEPLOY],
+  ["rollout", ACTION_CLASS.DEPLOY],
+  ["infra_mutation", ACTION_CLASS.INFRA_MUTATION],
+  ["infra", ACTION_CLASS.INFRA_MUTATION],
+  ["external_message", ACTION_CLASS.EXTERNAL_MESSAGE],
+  ["message", ACTION_CLASS.EXTERNAL_MESSAGE],
+  ["notify", ACTION_CLASS.EXTERNAL_MESSAGE],
+]);
+
+/** Actions that are safe to run unattended (local, reversible, not shared). */
+const LOW_RISK = new Set([
+  ACTION_CLASS.READ,
+  ACTION_CLASS.LOCAL_WRITE,
+  ACTION_CLASS.COMMIT,
+]);
+
+/**
+ * Actions that touch a shared / public / irreversible surface and therefore
+ * require attendance (or an explicit allowlist entry) when unattended.
+ */
+const HIGH_RISK = new Set([
+  ACTION_CLASS.PUBLISH,
+  ACTION_CLASS.MERGE,
+  ACTION_CLASS.DEPLOY,
+  ACTION_CLASS.INFRA_MUTATION,
+  ACTION_CLASS.EXTERNAL_MESSAGE,
+]);
+
+/** Normalize an action label to a canonical class, or null when unrecognized. */
+export function normalizeActionClass(value) {
+  if (typeof value !== "string") return null;
+  return ACTION_ALIASES.get(value.trim().toLowerCase()) || null;
+}
+
+/**
+ * Agent tools whose effect maps to a high-risk action class that can be cleanly
+ * blocked at the tool layer. `git push` / npm-publish-via-shell are deliberately
+ * NOT here — they ride the `git` / `run_shell` tools (which also do read-only
+ * work) and stay governed by the shell policy, not a blanket tool removal.
+ */
+export const TOOL_ACTION_CLASS = Object.freeze({
+  publish_artifact: ACTION_CLASS.PUBLISH,
+  notify: ACTION_CLASS.EXTERNAL_MESSAGE,
+});
+
+/**
+ * The agent tools an UNATTENDED run must be denied — the enforcement projection
+ * of `evaluateUnattendedAction` onto the tool layer (P1-8). A scheduled
+ * `cc agent` run passes the result as `--disallowed-tools`, so the model can
+ * never even call a denied high-risk tool. An attended run — or one whose class
+ * is on the allowlist — yields no restriction. PURE; result is sorted so the
+ * spawned argv is stable.
+ *
+ * @param {{attended?:boolean, allowlist?:string[], trigger?:object, budgetExhausted?:boolean}} p
+ * @returns {string[]} tool names to disallow
+ */
+export function unattendedDisallowedTools(p = {}) {
+  const out = [];
+  for (const [tool, actionClass] of Object.entries(TOOL_ACTION_CLASS)) {
+    const verdict = evaluateUnattendedAction({
+      actionClass,
+      attended: p.attended === true,
+      allowlist: p.allowlist,
+      trigger: p.trigger,
+      budgetExhausted: p.budgetExhausted,
+    });
+    if (!verdict.allow) out.push(tool);
+  }
+  return out.sort();
+}
+
+/** Coarse risk tier for an action: "low" | "high" | "conditional" | "unknown". */
+export function classifyActionRisk(actionClass) {
+  const a = normalizeActionClass(actionClass);
+  if (a == null) return "unknown";
+  if (LOW_RISK.has(a)) return "low";
+  if (HIGH_RISK.has(a)) return "high";
+  return "conditional"; // push — depends on branch protection
+}
+
+/**
+ * Decide whether a fired task may perform one action. Fail-closed.
+ *
+ * @param {object} params
+ * @param {string}  params.actionClass         action label (normalized)
+ * @param {boolean} params.attended            a human is watching this run
+ * @param {object}  [params.trigger]           {trusted?:boolean} — event source trust
+ * @param {string[]} [params.allowlist]        action classes pre-approved for unattended
+ * @param {boolean} [params.protectedBranch]   the push/merge targets a protected branch
+ * @param {boolean} [params.budgetExhausted]   the run's budget is spent
+ * @returns {{allow:boolean, reason:string}}
+ */
+export function evaluateUnattendedAction(params = {}) {
+  const action = normalizeActionClass(params.actionClass);
+
+  // A hard budget cap blocks everything, attended or not.
+  if (params.budgetExhausted === true) {
+    return { allow: false, reason: "budget-exhausted" };
+  }
+
+  // Unrecognized action: a human may vet it, but an unattended run must not.
+  if (action == null) {
+    return params.attended === true
+      ? { allow: true, reason: "attended" }
+      : { allow: false, reason: "unknown-action-unattended" };
+  }
+
+  // A watching human can authorize anything within budget.
+  if (params.attended === true) return { allow: true, reason: "attended" };
+
+  // ── Unattended from here on ──
+  const allowlist = new Set(
+    (Array.isArray(params.allowlist) ? params.allowlist : [])
+      .map((a) => normalizeActionClass(a))
+      .filter(Boolean),
+  );
+
+  // A push to a PROTECTED branch is effectively a merge into shared state.
+  const effective =
+    action === ACTION_CLASS.PUSH && params.protectedBranch === true
+      ? ACTION_CLASS.MERGE
+      : action;
+
+  if (LOW_RISK.has(effective)) return { allow: true, reason: "low-risk" };
+
+  // A plain push to an unprotected branch is allowed unattended.
+  if (effective === ACTION_CLASS.PUSH)
+    return { allow: true, reason: "push-unprotected" };
+
+  // High-risk unattended: external trigger content is untrusted by default, and
+  // even a trusted trigger must be on the explicit allowlist.
+  if (params.trigger && params.trigger.trusted === false) {
+    return { allow: false, reason: "untrusted-trigger" };
+  }
+  if (!allowlist.has(effective)) {
+    return { allow: false, reason: "requires-attendance" };
+  }
+  return { allow: true, reason: "allowlisted" };
+}

package/src/lib/worktree-cleanup-safety.js

@@ -0,0 +1,138 @@
+/**
+ * Worktree cleanup-safety gate — the fail-closed pre-removal check from P1-5
+ * (统一后台 Agent / Worktree 工作台) of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md:
+ *
+ *   "清理前检查未提交修改、未追踪文件、未 Push Commit 和关联 PR。"
+ *
+ * [[agent-worktree.js]] `finishAgentWorktree()` already refuses to remove a
+ * worktree with uncommitted changes or new commits, but it collapses "dirty"
+ * into one flag and does NOT distinguish untracked files, does NOT know whether
+ * commits were pushed, and has no notion of a linked PR — so a background agent
+ * that committed + pushed but left an OPEN PR, or left brand-new untracked
+ * scratch files, could still be reaped by a broader sweep.
+ *
+ * This module is the PURE decision behind any worktree reaper: given a plain
+ * state descriptor (whatever the caller gathered from `git status --porcelain`,
+ * `git rev-list @{u}..HEAD`, the PR store, …) it returns whether the worktree is
+ * safe to remove, and — like [[pr-automation-policy.js]] — it EXHAUSTIVELY
+ * collects every blocker so the caller can show the user all of them at once.
+ *
+ * Everything defaults to KEEP: an unreadable or under-described worktree is
+ * never removed, because we must never destroy work we cannot verify is safe to
+ * lose (the same invariant `finishAgentWorktree` guards with its try/catch).
+ */
+
+/** Named blockers — one per reason a worktree must be kept, not reaped. */
+export const CLEANUP_BLOCKER = Object.freeze({
+  UNVERIFIABLE: "unverifiable", // git state could not be read → fail-closed keep
+  UNCOMMITTED: "uncommitted-changes", // tracked files modified but not committed
+  UNTRACKED: "untracked-files", // new files git isn't tracking yet
+  UNPUSHED: "unpushed-commits", // commits beyond base not on any remote
+  LINKED_PR: "linked-pr", // an open PR references this branch
+});
+
+const BLOCKER_REASON = Object.freeze({
+  [CLEANUP_BLOCKER.UNVERIFIABLE]:
+    "git state could not be read — refusing to remove work that cannot be verified safe to lose",
+  [CLEANUP_BLOCKER.UNCOMMITTED]: "tracked files have uncommitted modifications",
+  [CLEANUP_BLOCKER.UNTRACKED]: "untracked files would be lost on removal",
+  [CLEANUP_BLOCKER.UNPUSHED]:
+    "commits beyond the base are not pushed to any remote",
+  [CLEANUP_BLOCKER.LINKED_PR]:
+    "an open pull request still references this branch",
+});
+
+function toCount(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+function prList(v) {
+  if (!Array.isArray(v)) return [];
+  return v.filter((p) => p != null);
+}
+
+/**
+ * Decide whether commits on this worktree are unpushed. A caller that already
+ * computed push-state passes an explicit `unpushed` boolean, which wins. Else it
+ * is derived: a worktree whose HEAD equals its base has no new commits;
+ * otherwise, with a known upstream, unpushed iff `aheadCount > 0`; WITHOUT a
+ * known upstream, any divergence from base is treated as unpushed (there is
+ * nowhere it could have been pushed to) — the fail-closed reading.
+ */
+function commitsAreUnpushed(state) {
+  if (state.unpushed === true) return true;
+  if (state.unpushed === false) return false;
+  const { baseSha, headSha, hasUpstream, aheadCount } = state;
+  const hasNewCommits =
+    headSha != null && baseSha != null && String(headSha) !== String(baseSha);
+  if (!hasNewCommits) {
+    // Base/head unknown but the caller told us we're ahead → still unpushed.
+    return toCount(aheadCount) > 0;
+  }
+  if (hasUpstream === true) return toCount(aheadCount) > 0;
+  return true; // new commits + no upstream → nowhere pushed
+}
+
+/**
+ * Evaluate a worktree's cleanup safety. EXHAUSTIVE + fail-closed.
+ *
+ * @param {object} state
+ * @param {boolean} [state.readable]      false / omitted when git status could not be read
+ * @param {boolean} [state.uncommitted]   tracked modifications present
+ * @param {boolean} [state.untracked]     untracked files present
+ * @param {string}  [state.baseSha]       worktree base commit
+ * @param {string}  [state.headSha]       worktree HEAD commit
+ * @param {boolean} [state.hasUpstream]   branch has a configured upstream
+ * @param {number}  [state.aheadCount]    commits ahead of upstream
+ * @param {boolean} [state.unpushed]      explicit push-state (wins over derivation)
+ * @param {Array}   [state.linkedPrs]     open PRs referencing this branch
+ * @returns {{safeToRemove:boolean, blockers:string[], reasons:object}}
+ */
+export function evaluateWorktreeCleanup(state = {}) {
+  const blockers = [];
+
+  // Unverifiable state is the hard fail-closed gate: if we could not read the
+  // worktree, we cannot prove anything else, so keep and report only this.
+  if (state.readable === false) {
+    blockers.push(CLEANUP_BLOCKER.UNVERIFIABLE);
+    return finalize(blockers);
+  }
+
+  if (state.uncommitted === true) blockers.push(CLEANUP_BLOCKER.UNCOMMITTED);
+  if (state.untracked === true) blockers.push(CLEANUP_BLOCKER.UNTRACKED);
+  if (commitsAreUnpushed(state)) blockers.push(CLEANUP_BLOCKER.UNPUSHED);
+  if (prList(state.linkedPrs).length > 0)
+    blockers.push(CLEANUP_BLOCKER.LINKED_PR);
+
+  return finalize(blockers);
+}
+
+function finalize(blockers) {
+  const reasons = {};
+  for (const b of blockers) reasons[b] = BLOCKER_REASON[b];
+  return {
+    safeToRemove: blockers.length === 0,
+    blockers,
+    reasons,
+  };
+}
+
+/**
+ * A human-readable one-line summary of a cleanup decision — never echoes file
+ * contents or PR bodies, only counts and named blockers.
+ */
+export function summarizeWorktreeCleanup(state = {}) {
+  const { safeToRemove, blockers } = evaluateWorktreeCleanup(state);
+  if (safeToRemove)
+    return "safe to remove — no uncommitted, untracked, unpushed or PR-linked work";
+  const parts = blockers.map((b) => {
+    if (b === CLEANUP_BLOCKER.LINKED_PR) {
+      const n = prList(state.linkedPrs).length;
+      return `${n} open PR${n === 1 ? "" : "s"}`;
+    }
+    return b;
+  });
+  return `keep — ${parts.join(", ")}`;
+}

package/src/lib/worktree-isolator.js

@@ -5,9 +5,17 @@ export {
   pruneWorktrees,
   isolateTask,
   cleanupAgentWorktrees,
+  assessAgentWorktreeCleanup,
   diffWorktree,
   previewWorktreeMerge,
   applyWorktreeAutomationCandidate,
   mergeWorktree,
   worktreeLog,
 } from "../harness/worktree-isolator.js";
+
+export {
+  normalizeSparsePaths,
+  planSymlinkDirectories,
+  isContainedPath,
+  isSafeRelPath,
+} from "./worktree-sparse.js";

package/src/lib/worktree-sparse.js

@@ -0,0 +1,131 @@
+/**
+ * Worktree sparse-checkout + dependency-symlink planning (pure core).
+ *
+ * P1 "large monorepo" pillar: only check out the packages a task needs
+ * (`worktree.sparsePaths`) and reuse explicitly-approved dependency
+ * directories from the main checkout via junction/symlink
+ * (`worktree.symlinkDirectories`), with junction/symlink escape defense.
+ *
+ * Pure + deterministic: no fs, no git, no clock. The isolator does the
+ * actual sparse-checkout and link creation from the plans produced here.
+ */
+
+import { resolve, join } from "node:path";
+
+/**
+ * Safe repo-relative path predicate — mirrors the reject rules of
+ * `git-integration.assertSafeGitPath` but as a boolean, so callers can
+ * filter/normalize instead of throwing. Rejects absolute paths, `..`
+ * traversal, flag injection, empty strings, and shell metacharacters.
+ */
+export function isSafeRelPath(p) {
+  if (typeof p !== "string") return false;
+  const s = p.trim();
+  if (s.length === 0) return false;
+  return (
+    /^[A-Za-z0-9._/+@=, -]+$/.test(s) && // safe chars only
+    !s.startsWith("-") && // no flag injection
+    !s.startsWith("/") && // no absolute (posix)
+    !/^[A-Za-z]:/.test(s) && // no absolute (windows drive)
+    !s.includes("..") // no traversal
+  );
+}
+
+/**
+ * Normalize a raw relative path to git's forward-slash form. Converts
+ * backslash separators (Windows-style `packages\cli`) and trims trailing
+ * slashes, but keeps any LEADING slash so absolute paths are still rejected
+ * by the safety check (never silently reinterpreted as repo-relative).
+ */
+function toGitRel(p) {
+  return String(p).trim().replace(/\\/g, "/").replace(/\/+$/, "");
+}
+
+/**
+ * Normalize a raw path (backslash → slash, trim slashes) THEN validate — so
+ * Windows-style config (`packages\cli`) is accepted, not silently dropped.
+ * Returns the safe git-relative form, or null when unsafe/empty.
+ */
+function safeGitRel(raw) {
+  if (typeof raw !== "string") return null;
+  const rel = toGitRel(raw);
+  if (rel.length === 0) return null;
+  return isSafeRelPath(rel) ? rel : null;
+}
+
+/**
+ * Validate + normalize sparse-checkout include paths.
+ *
+ * @param {string[]|string|null|undefined} paths
+ * @returns {string[]|null} sorted, de-duped, forward-slash repo-relative
+ *   directories, or null when nothing valid is requested (caller keeps a
+ *   full checkout — byte-identical to the no-sparse path).
+ */
+export function normalizeSparsePaths(paths) {
+  if (paths == null) return null;
+  const list = Array.isArray(paths) ? paths : [paths];
+  const seen = new Set();
+  for (const raw of list) {
+    const rel = safeGitRel(raw);
+    if (rel) seen.add(rel);
+  }
+  if (seen.size === 0) return null;
+  return [...seen].sort();
+}
+
+/** True when `child` resolves to `parent` itself or a descendant of it. */
+export function isContainedPath(child, parent) {
+  const p = resolve(parent);
+  const c = resolve(child);
+  if (c === p) return true;
+  // Append a separator so `/repo-evil` is not treated as inside `/repo`.
+  const sep = p.endsWith("/") || p.endsWith("\\") ? "" : "/";
+  const cNorm = c.replace(/\\/g, "/");
+  const pNorm = (p + sep).replace(/\\/g, "/");
+  return cNorm.startsWith(pNorm);
+}
+
+/**
+ * Plan dependency-directory links from the main checkout into a worktree.
+ *
+ * Each entry must be an explicitly-approved, safe repo-relative directory
+ * (e.g. `node_modules`, `packages/cli/node_modules`). The plan asserts both
+ * lexical safety (no `..`, no absolute, no flag) AND resolved containment:
+ * the source stays inside `repoDir` and the destination stays inside
+ * `worktreePath`. This defeats junction/symlink escape where a crafted name
+ * would place the link (or its target) outside the intended roots.
+ *
+ * @throws {Error} on any unsafe/escaping entry — fail-closed, never a
+ *   silent skip, so a bad config cannot quietly link outside the sandbox.
+ * @returns {{name:string, source:string, dest:string}[]}
+ */
+export function planSymlinkDirectories(dirs, { repoDir, worktreePath } = {}) {
+  if (dirs == null) return [];
+  if (!repoDir || !worktreePath) {
+    throw new Error("planSymlinkDirectories requires repoDir and worktreePath");
+  }
+  const list = Array.isArray(dirs) ? dirs : [dirs];
+  const plan = [];
+  const seen = new Set();
+  for (const raw of list) {
+    const rel = safeGitRel(raw);
+    if (!rel) {
+      throw new Error(`Unsafe symlink directory: ${JSON.stringify(raw)}`);
+    }
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+
+    const source = resolve(join(repoDir, rel));
+    const dest = resolve(join(worktreePath, rel));
+    if (!isContainedPath(source, repoDir)) {
+      throw new Error(`Symlink source escapes repo: ${JSON.stringify(raw)}`);
+    }
+    if (!isContainedPath(dest, worktreePath)) {
+      throw new Error(
+        `Symlink target escapes worktree: ${JSON.stringify(raw)}`,
+      );
+    }
+    plan.push({ name: rel, source, dest });
+  }
+  return plan;
+}