@dsh-cc/cli 0.6.3 → 0.7.0

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm check:readme --write
-README.md: b3521cecfa66e117b0665e12d454b7ad5982000f
-README.zh.md: 3d47cfad50f2974b166ac85880eec3d7b1ee8039
+README.md: fb5d2db0aeb51b6089d8add10fe424b75c578f98
+README.zh.md: 2373aae659fd013f355473e19c2bd3823d71b33f

package/README.md

@@ -20,6 +20,20 @@ auto-resume — the TUI resumes the project's last session. `--resume` /
 `DSH_CC_WORKTREE`, and the TUI offers to keep or remove the worktree at
 `/quit`. Requires a git repository with at least one commit.
 
+Every launch also runs a boot-time sweep (never network I/O, 10s cap,
+fail-silent): worktrees under `.claude/worktrees/` on `worktree-*` branches
+older than `worktree.cleanupPeriodDays` (default 30, from the `worktree`
+settings section read fail-open from user → project → local settings files)
+are removed only when clean and nothing is unpushed; stale dsh-cc session
+locks are never auto-released — they surface as advisory `git worktree
+unlock <path>` lines. New worktrees branch from the base chosen by
+`worktree.baseRef` (`fresh` = cached origin/HEAD with a 24h-stale refresh
+fetch capped at 5s, `head` = literal HEAD); a reused named worktree is
+hard-reset to that base when it is clean and all its own commits are
+already merged into it. Created and reused worktrees are locked with
+`git worktree lock --reason="dsh-cc session <slug>"` for the session's
+duration.
+
 ## Resume environment contract
 
 The launcher communicates the user's session intent to the TUI plugin (via

package/README.zh.md

@@ -18,6 +18,18 @@ worktree 共享它）划分作用域，会退回默认的 auto-resume——TUI
 `DSH_CC_WORKTREE` 标记会话，TUI 会在 `/quit` 时询问保留还是删除该
 worktree。要求 git 仓库至少有一个提交。
 
+每次启动还会运行一次引导清扫（不做网络 I/O，10 秒上限，失败静默）：
+`.claude/worktrees/` 下位于 `worktree-*` 分支、超过
+`worktree.cleanupPeriodDays`（默认 30，从 user → project → local 设置文件
+中 fail-open 读取的 `worktree` 设置节取得）的 worktree，只有在干净且没有
+未推送提交时才会被移除；过期的 dsh-cc 会话锁绝不自动释放——它们只以
+`git worktree unlock <path>` 建议行出现。新 worktree 的创建基准由
+`worktree.baseRef` 决定（`fresh` = 缓存的 origin/HEAD，reflog 超过 24 小时
+时限 5 秒 fetch 刷新；`head` = 字面 HEAD）；复用的命名 worktree 在干净且
+自身提交全部已合入该基准时会被硬重置到该基准。创建与复用的 worktree 都会
+以 `git worktree lock --reason="dsh-cc session <slug>"` 加锁，会话期间
+保持锁定。
+
 ## Resume environment contract
 
 启动器通过三个变量（经由 `cordis.patch.yml` 的 `!!js` 表达式）把用户的会话

package/bin/dsh-cc.js

@@ -9,18 +9,24 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { bootstrapCommand, dshUnavailableMessage, existingWorktreeDecision, interceptResume, parseWorktreeFlag, planWorktree, PROFILE, sanitizeInheritedEnv, slugRetryDecision, spawnEnv, versionGate, worktreeAddArgv, worktreeEnv } from '../bootstrap.mjs'
+import { bootstrapCommand, devStoreRestoreDecision, dshUnavailableMessage, existingWorktreeDecision, formatVersionLabel, interceptResume, parseLocalConfig, parseWorktreeFlag, parseWorktreeRef, planWorktree, planWorktreeRef, prFetchRefs, remoteHost, PROFILE, readBuildInfo, repoRootFromCommonDir, runStoreRestore, sanitizeInheritedEnv, slugRetryDecision, spawnEnv, symlinkedPath, versionGate, worktreeAddArgv, worktreeEnv, worktreeIdentityRefusal } from '../bootstrap.mjs'
+import { readWorktreeSettings, resolveBaseRef, sweepWorktrees, SWEEP_CAP_MS, worktreeReuseReset, worktreeSettingsPaths } from '../worktree-lifecycle.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const ownVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version
 
+const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+const profileDir = join(home, 'profiles', PROFILE)
+// Dev-build stamp lives with the synced profile code (see
+// scripts/stamp-build-info.mjs); read once per launch, sub-millisecond, no
+// subprocess (W2 law). Missing/malformed -> null, fail-open to release.
+const stampPath = join(profileDir, 'node_modules', '@dsh-cc', 'dsh-cc-build.json')
+const buildInfo = readBuildInfo(stampPath)
+
 if (process.argv.includes('--version') || process.argv.includes('-V')) {
-  console.log(ownVersion)
+  console.log(formatVersionLabel(ownVersion, buildInfo))
   process.exit(0)
 }
-
-const home = process.env.DSH_HOME || join(homedir(), '.dsh')
-const profileDir = join(home, 'profiles', PROFILE)
 const add = bootstrapCommand(existsSync(join(profileDir, 'package.json')), ownVersion)
 if (add !== undefined) {
   console.error(`dsh-cc: initializing profile "${PROFILE}"…`)
@@ -47,6 +53,12 @@ if (add !== undefined) {
   }
 }
 
+// A dev-synced profile paired with a DIFFERENT launcher version converges
+// back to store bundles before the session starts (plan 2026-09-13 §3.4).
+// A fresh profile has no stamp, so this can never fire on the bootstrap path.
+const restorePlan = devStoreRestoreDecision(buildInfo, ownVersion)
+if (restorePlan !== null) runStoreRestore(profileDir, ownVersion)
+
 // A parent dsh-cc TUI process leaks DSH_CC_RESUME_SESSION / DSH_CC_AUTO_RESUME
 // / DSH_CC_CONTINUE into a child launcher's environment. Strip them up front —
 // before any flag is parsed — so the three are re-derived only from THIS
@@ -54,6 +66,36 @@ if (add !== undefined) {
 // DSH_CC_AUTO_RESUME=1 would otherwise defeat an explicit --new / --worktree.
 const env0 = sanitizeInheritedEnv({ ...process.env })
 
+// WS-4 boot-time sweep: remove long-orphaned dsh-cc worktrees and REPORT
+// stale dsh-cc session locks (locks are never auto-released — no
+// trustworthy cross-process liveness oracle). Runs on every launch whether
+// or not this launch is a --worktree session, never does network I/O, is
+// bounded by the 10s cap, and degrades to a silent no-op on any failure —
+// launch must never block on the sweep.
+try {
+  const sweepCommon = spawnSync('git', ['rev-parse', '--git-common-dir'], { encoding: 'utf8', timeout: 2000 })
+  const sweepRoot = sweepCommon.status === 0 ? repoRootFromCommonDir(process.cwd(), sweepCommon.stdout) : undefined
+  if (sweepRoot !== undefined && existsSync(sweepRoot)) {
+    const sweepSettings = readWorktreeSettings(worktreeSettingsPaths({ home, projectRoot: sweepRoot }))
+    const swept = sweepWorktrees({
+      repoRoot: sweepRoot,
+      cleanupPeriodDays: sweepSettings.cleanupPeriodDays,
+      git: (argv, opts) => spawnSync('git', argv, {
+        encoding: 'utf8',
+        ...(opts?.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+        ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+      }),
+      onAdvisory: line => console.error(line),
+      deadline: SWEEP_CAP_MS,
+    })
+    if (swept.removed.length > 0) {
+      console.error(`dsh-cc: swept ${swept.removed.length} stale worktree(s) older than ${sweepSettings.cleanupPeriodDays} days`)
+    }
+  }
+} catch {
+  // Sweep failures never block launch.
+}
+
 // `--worktree [name]` is intercepted here (never forwarded to dsh): the
 // launcher creates `<repoRoot>/.claude/worktrees/<slug>` itself and starts
 // the session inside it, marking it via DSH_CC_WORKTREE so the TUI offers
@@ -65,12 +107,31 @@ if (worktree.name !== undefined) {
   // of this block. A REUSED worktree leaves DSH_CC_RESUME_SESSION undefined,
   // so interceptResume sets DSH_CC_AUTO_RESUME=1 and the TUI resumes the
   // project's last session.
-  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' })
-  if (top.error || top.status !== 0) {
+  // WS-1 root pinning: anchor at the git common dir so a session launched
+  // from inside a linked worktree still creates a SIBLING under the main
+  // root's .claude/worktrees/, never a nested tree.
+  const common = spawnSync('git', ['rev-parse', '--git-common-dir'], { encoding: 'utf8' })
+  if (common.error || common.status !== 0) {
     console.error('dsh-cc: --worktree requires a git repository (run from inside a git working tree).')
     process.exit(1)
   }
-  const repoRoot = top.stdout.trim()
+  const repoRoot = repoRootFromCommonDir(process.cwd(), common.stdout)
+  if (repoRoot === undefined || !existsSync(repoRoot)) {
+    console.error('dsh-cc: --worktree requires a git repository (could not locate the main checkout).')
+    process.exit(1)
+  }
+  // WS-1: neutralize repository-local filter drivers — read the local config
+  // up front and refuse on unreadable config or CC-parity refusal shapes.
+  const localConfig = spawnSync('git', ['-C', repoRoot, 'config', '--local', '--list', '-z'], { encoding: 'utf8' })
+  if (localConfig.error || localConfig.status !== 0) {
+    console.error('dsh-cc: refusing to create a worktree: repository local config is unreadable.')
+    process.exit(1)
+  }
+  const configScan = parseLocalConfig(localConfig.stdout)
+  if (configScan.refusals.length > 0) {
+    console.error(`dsh-cc: refusing to create a worktree: ${configScan.refusals.join('; ')}`)
+    process.exit(1)
+  }
   // Drop stale registrations left by crashed sessions before planning paths.
   spawnSync('git', ['-C', repoRoot, 'worktree', 'prune'], { encoding: 'utf8' })
   const head = spawnSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' })
@@ -78,19 +139,109 @@ if (worktree.name !== undefined) {
     console.error('dsh-cc: could not resolve HEAD; is this a repository without commits?')
     process.exit(1)
   }
-  const named = worktree.name !== null
+  // WS-4: read the `worktree` settings subset (user → project → local,
+  // fail-open) and resolve the creation base. The refresh fetch (when the
+  // cached origin/HEAD is older than 24h) is capped at 5s and happens on
+  // the creation path only.
+  const wtSettings = readWorktreeSettings(worktreeSettingsPaths({ home, projectRoot: repoRoot }))
+  const base = await resolveBaseRef(
+    (argv, opts) => spawnSync('git', argv, {
+      encoding: 'utf8',
+      cwd: repoRoot,
+      ...(opts?.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+    }),
+    wtSettings.baseRef,
+  )
+  const baseHead = base === 'HEAD'
+    ? head.stdout.trim()
+    : (spawnSync('git', ['-C', repoRoot, 'rev-parse', base], { encoding: 'utf8' }).stdout.trim() || head.stdout.trim())
+  // WS-6 item 3: PR references (`#<n>`, GitHub PR / GitLab MR URLs) are
+  // parsed BEFORE any slug validation; the fetched head becomes the base.
+  // Pre-build limitation: no hooks run on this path (documented deviation).
+  const pr = parseWorktreeRef(worktree.name)
+  let prBase = null
+  if (pr !== undefined) {
+    let host = pr.host
+    if (host === undefined) {
+      const url = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+      host = url.status === 0 ? remoteHost(url.stdout) : undefined
+    }
+    const refs = prFetchRefs(host, pr.pr)
+    let fetched = null
+    for (const ref of refs) {
+      const f = spawnSync('git', ['-C', repoRoot, 'fetch', 'origin', ref], { encoding: 'utf8', timeout: 5000 })
+      if (!f.error && f.status === 0) { fetched = ref; break }
+    }
+    if (fetched === null) {
+      console.error(`dsh-cc: could not resolve PR ${pr.pr} from origin (tried ${refs.join(', ')}). Check the reference, the remote, and your network.`)
+      process.exit(1)
+    }
+    prBase = spawnSync('git', ['-C', repoRoot, 'rev-parse', 'FETCH_HEAD'], { encoding: 'utf8' }).stdout.trim() || null
+    if (prBase === null) {
+      console.error(`dsh-cc: fetched ${fetched} but could not resolve FETCH_HEAD.`)
+      process.exit(1)
+    }
+  }
+  const createBase = prBase ?? base
+  // WS-4: `git worktree lock --reason="dsh-cc session <slug>"` at managed
+  // session start (created OR reused). Pre-2.15 git without `worktree
+  // lock` is a tolerated no-op with a one-line warn.
+  const lockWorktreeSession = (slug, path) => {
+    const lock = spawnSync('git', ['-C', repoRoot, 'worktree', 'lock', `--reason=dsh-cc session ${slug}`, path], { encoding: 'utf8' })
+    if (lock.status !== 0) {
+      if (/unknown option|unknown switch/i.test(lock.stderr ?? '')) {
+        console.error(`dsh-cc: git worktree lock unsupported by this git version; ${path} left unlocked`)
+      } else {
+        console.error(`dsh-cc: could not lock worktree ${path}: ${(lock.stderr ?? '').trim()}`)
+      }
+    }
+  }
+  // A PR reference is user-pinned: the /quit overlay treats it as named.
+  const named = worktree.name !== null || pr !== undefined
   let plan = null
   let created = false
   for (let attempt = 1; attempt <= 5; attempt += 1) {
     let candidate
     try {
-      candidate = planWorktree(repoRoot, worktree.name)
+      candidate = pr !== undefined ? planWorktreeRef(repoRoot, pr.pr) : planWorktree(repoRoot, worktree.name)
     } catch (error) {
       console.error(`dsh-cc: ${error.message}`)
       process.exit(1)
     }
+    // WS-1 symlink refusal on the creation route (CC v2.1.212 parity).
+    const symlink = symlinkedPath([join(repoRoot, '.claude'), join(repoRoot, '.claude', 'worktrees'), candidate.worktreePath])
+    if (symlink !== null) {
+      console.error(`dsh-cc: refusing to create a worktree: a creation path is a symlink: ${symlink}`)
+      process.exit(1)
+    }
     const pathExists = existsSync(candidate.worktreePath)
     if (existingWorktreeDecision({ named, pathExists }) === 'reuse') {
+      // WS-1 adoption gate: verify the existing directory's git identity
+      // before handing it over (leave the directory in place on refusal).
+      const refusal = worktreeIdentityRefusal(candidate.worktreePath, repoRoot)
+      if (refusal !== null) {
+        console.error(`dsh-cc: ${refusal}`)
+        process.exit(1)
+      }
+      // WS-4 merged-reset rule: when the reused tree is clean, still on its
+      // worktree-* branch, and its own commits are all reachable from the
+      // resolved fresh base, hard-reset it to the base before handover;
+      // otherwise (or when any probe is unverifiable) continue at the old
+      // tip. `source: 'name'` keeps the WS-6 PR-reuse skip open.
+      const reset = worktreeReuseReset({
+        plan: candidate,
+        repoRoot,
+        freshBase: base,
+        source: pr !== undefined ? 'pr' : 'name',
+        git: (argv, opts) => spawnSync('git', argv, {
+          encoding: 'utf8',
+          ...(opts?.timeoutMs ? { timeout: opts.timeoutMs } : {}),
+          ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+        }),
+      })
+      if (reset.action === 'reset') {
+        console.error(`dsh-cc: reset reused worktree "${candidate.slug}" to ${base}`)
+      }
       plan = candidate
       created = false
       break
@@ -99,7 +250,7 @@ if (worktree.name !== undefined) {
       ? `path already exists: ${candidate.worktreePath}`
       : null
     if (failure === null) {
-      const add = spawnSync('git', ['-C', repoRoot, ...worktreeAddArgv(candidate)], { encoding: 'utf8' })
+      const add = spawnSync('git', ['-C', repoRoot, ...worktreeAddArgv(candidate, configScan.filters, createBase)], { encoding: 'utf8' })
       if (add.error || add.status !== 0) {
         failure = (add.stderr ?? (add.error ? String(add.error) : '')).trim() || 'git worktree add failed'
       }
@@ -122,7 +273,8 @@ if (worktree.name !== undefined) {
     console.error('dsh-cc: could not allocate a worktree name after several attempts; try --worktree <name>.')
     process.exit(1)
   }
-  Object.assign(env0, worktreeEnv(plan, repoRoot, head.stdout.trim()))
+  lockWorktreeSession(plan.slug, plan.worktreePath)
+  Object.assign(env0, worktreeEnv(plan, repoRoot, prBase ?? baseHead, named))
   spawnCwd = plan.worktreePath
   const verb = created ? 'created' : 'reusing'
   console.error(`dsh-cc: worktree "${plan.slug}" ${verb} at ${plan.worktreePath} (branch ${plan.branch})`)

package/bootstrap.mjs

@@ -3,7 +3,9 @@
  * decision table without spawning dsh.
  */
 
-import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 export const PROFILE = 'tui'
 export const BUNDLES = [
@@ -265,32 +267,229 @@ export function planWorktree(repoRoot, name, rand) {
   return { slug, worktreePath: worktreePathFor(repoRoot, slug), branch: worktreeBranch(slug) }
 }
 
+/**
+ * WS-6 item 3: parse a PR reference `--worktree` value — `#<n>`, a GitHub PR
+ * URL, or a GitLab MR URL. Runs BEFORE any slug validation so `#12` never
+ * reaches validateWorktreeSlug. Anything else is not a PR reference.
+ * @param {string | null | undefined} value - the parsed flag value.
+ * @returns {{ pr: number, host?: string } | undefined}
+ *   `host` is the URL's host when the value was a URL (it selects the fetch
+ *   ref shape); undefined for a bare `#<n>`.
+ */
+export function parseWorktreeRef(value) {
+  if (value === null || value === undefined) return undefined
+  let m = /^#(\d+)$/.exec(value)
+  if (m !== null) return { pr: Number(m[1]) }
+  m = /^https:\/\/([^/]+)\/.+(?:\/pull|\/-\/merge_requests|\/merge_requests)\/(\d+)\/?$/.exec(value)
+  if (m !== null) return { pr: Number(m[2]), host: m[1] }
+  return undefined
+}
+
+/**
+ * The origin fetch refs for a PR head, in try order (WS-6 item 3):
+ * `pull/<n>/head` on github.com, `merge-requests/<n>/head` on gitlab.com,
+ * first-then-second on any other (or unknown) host.
+ * @param {string | undefined} host
+ * @param {number} n
+ * @returns {string[]}
+ */
+export function prFetchRefs(host, n) {
+  if (host === 'github.com') return [`pull/${n}/head`]
+  if (host === 'gitlab.com') return [`merge-requests/${n}/head`]
+  return [`pull/${n}/head`, `merge-requests/${n}/head`]
+}
+
+/**
+ * Host of a git remote URL (`https://…`, `git@host:…`, `ssh://…`), or
+ * undefined when it has none.
+ * @param {string} url
+ * @returns {string | undefined}
+ */
+export function remoteHost(url) {
+  const m = /^(?:(?:https?|ssh):\/\/)?(?:[^/@]+@)?([^/:]+)/.exec(url.trim())
+  return m !== null ? m[1] : undefined
+}
+
+/**
+ * The fixed PR plan: slug `pr-<n>`, branch `worktree-pr-<n>`, path under the
+ * convention dir. Deliberately NOT routed through validateWorktreeSlug —
+ * the `pr-<n>` shape is generated here and always valid.
+ * @param {string} repoRoot
+ * @param {number} n
+ * @returns {{ slug: string, worktreePath: string, branch: string }}
+ */
+export function planWorktreeRef(repoRoot, n) {
+  const slug = `pr-${n}`
+  return { slug, worktreePath: join(repoRoot, '.claude', 'worktrees', slug), branch: `worktree-pr-${n}` }
+}
+
 /**
  * argv for `git worktree add -B <branch> <path> HEAD` (execFile form — no
  * shell, so no quoting concerns). `-B` resets a stale orphan branch left by
- * a removed worktree.
+ * a removed worktree. When `filterNames` is nonempty, empty-string `-c`
+ * overrides neutralize every repository-local filter driver first
+ * (mechanism verified empirically — content-marker experiment, git 2.54:
+ * overriding all `filter.<name>.*` keys + `required=false` suppresses
+ * execution; `required=false` alone does NOT). Consequence (CC parity):
+ * LFS content arrives as pointer files; `git lfs pull` restores it.
  * @param {{ worktreePath: string, branch: string }} plan
+ * @param {readonly string[]} [filterNames]
+ * @param {string} [base] - Resolved base ref/commit (WS-4 `worktree.baseRef`);
+ *   defaults to the literal `HEAD`.
  * @returns {string[]}
  */
-export function worktreeAddArgv(plan) {
-  return ['worktree', 'add', '-B', plan.branch, plan.worktreePath, 'HEAD']
+export function worktreeAddArgv(plan, filterNames = [], base = 'HEAD') {
+  const neutralize = []
+  for (const filter of filterNames) {
+    for (const key of ['command', 'smudge', 'clean', 'process']) {
+      neutralize.push('-c', `filter.${filter}.${key}=`)
+    }
+    neutralize.push('-c', `filter.${filter}.required=false`)
+  }
+  return [...neutralize, 'worktree', 'add', '-B', plan.branch, plan.worktreePath, base]
+}
+
+/**
+ * WS-1 root pinning: main repository root from `git rev-parse
+ * --git-common-dir` output run at `cwd`. Inside a linked worktree the
+ * common dir already points at the main checkout's `.git`, so creation
+ * always anchors at the main root (sibling worktrees, never nested).
+ * @param {string} cwd - Directory the git probe ran in.
+ * @param {string} output - Raw stdout of the probe.
+ * @returns {string | undefined}
+ */
+export function repoRootFromCommonDir(cwd, output) {
+  const raw = output.trim()
+  if (raw.length === 0) return undefined
+  return dirname(isAbsolute(raw) ? raw : resolve(cwd, raw))
+}
+
+/**
+ * Parse `git config --local --list -z` output (NUL-separated `key\nvalue`
+ * entries — the NUL form keeps filter names containing `=` decidable).
+ * Refuses includeIf and filter names containing `=`; collects the rest.
+ * Keep in sync with tool-git-worktree/src/harden.ts.
+ * @param {string} text
+ * @returns {{ filters: string[], refusals: string[] }}
+ */
+export function parseLocalConfig(text) {
+  const filters = new Set()
+  const refusals = []
+  for (const entry of text.split('\0')) {
+    if (entry.length === 0) continue
+    const nl = entry.indexOf('\n')
+    const rawKey = nl < 0 ? entry : entry.slice(0, nl)
+    const key = rawKey.toLowerCase()
+    if (key.startsWith('includeif.')) {
+      refusals.push(`refusing local config with includeIf: ${rawKey}`)
+      continue
+    }
+    if (!key.startsWith('filter.')) continue
+    const name = key.slice('filter.'.length, key.lastIndexOf('.'))
+    if (name.length === 0) continue
+    if (name.includes('=') || name.includes('\n')) {
+      refusals.push(`refusing filter driver with ambiguous name: filter.${name}.*`)
+      continue
+    }
+    filters.add(name)
+  }
+  return { filters: [...filters], refusals }
+}
+
+/**
+ * WS-1 symlink refusal: the first path in the list that is itself a symlink
+ * (CC v2.1.212 parity). Callers check `.claude`, `.claude/worktrees`, and
+ * the computed target path.
+ * @param {string[]} paths
+ * @returns {string | null} the offending path, or null when none is a symlink.
+ */
+export function symlinkedPath(paths) {
+  for (const path of paths) {
+    try {
+      if (lstatSync(path).isSymbolicLink()) return path
+    } catch {
+      // missing is fine
+    }
+  }
+  return null
+}
+
+/**
+ * WS-1 adoption identity check for reusing an existing directory as a
+ * worktree: its `.git` entry must be a gitdir pointer file resolving into
+ * the main checkout's `.git/worktrees/` registration. Refuses plain clones,
+ * core.worktree redirects, unreadable entries, directories that contain the
+ * main checkout, and directories with no git metadata (may hold user work).
+ * Keep in sync with tool-git-worktree/src/harden.ts.
+ * @param {string} target - Absolute path of the existing directory.
+ * @param {string} mainRoot - Main checkout repository root.
+ * @returns {string | null} the refusal reason, or null when adoptable.
+ */
+export function worktreeIdentityRefusal(target, mainRoot) {
+  const rel = relative(target, mainRoot)
+  if (rel === '' || !rel.startsWith(`..${sep}`)) {
+    return `refusing to reuse ${target}: it contains the main checkout at ${mainRoot}. Remove or rename the directory (or pick another name) and retry.`
+  }
+  const gitEntry = join(target, '.git')
+  let info
+  try {
+    info = lstatSync(gitEntry)
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') {
+      return `refusing to reuse ${target}: it holds no git worktree (no .git entry) and may contain user work. Remove or rename the directory (or pick another name) and retry.`
+    }
+    return `refusing to reuse ${target}: its .git entry is unreadable (${/** @type {NodeJS.ErrnoException} */ (error).message}). Inspect the directory manually; remove or rename it (or pick another name) and retry.`
+  }
+  if (!info.isFile()) {
+    let detail = 'it is a separate checkout (directory .git), not a linked worktree'
+    try {
+      const common = readFileSync(join(gitEntry, 'commondir'), 'utf8').trim()
+      const gitRoot = join(mainRoot, '.git')
+      const resolved = resolve(gitEntry, common)
+      if (resolved.startsWith(gitRoot + sep) || resolved === gitRoot) {
+        detail = 'its .git commondir resolves into the main checkout\'s own .git (plain-clone/core.worktree redirect shape)'
+      }
+    } catch {
+      // no commondir file — separate-checkout message stands
+    }
+    return `refusing to reuse ${target}: ${detail}. Remove or rename the directory (or pick another name) and retry.`
+  }
+  let gitdir
+  try {
+    gitdir = readFileSync(gitEntry, 'utf8').trim()
+  } catch {
+    return `refusing to reuse ${target}: its .git pointer file is unreadable. Inspect the directory manually; remove or rename it (or pick another name) and retry.`
+  }
+  if (!gitdir.startsWith('gitdir:')) {
+    return `refusing to reuse ${target}: its .git entry is a file but not a gitdir pointer. Remove or rename the directory (or pick another name) and retry.`
+  }
+  const registered = resolve(target, gitdir.slice('gitdir:'.length).trim())
+  const registrations = join(mainRoot, '.git', 'worktrees')
+  if (!registered.startsWith(registrations + sep) && registered !== registrations) {
+    return `refusing to reuse ${target}: its .git pointer resolves to ${registered}, which is not this repository's worktree registration (.git/worktrees/). It may be a clone, redirect, or foreign worktree. Remove or rename the directory (or pick another name) and retry.`
+  }
+  return null
 }
 
 /**
  * Env fragment handed to the spawned dsh process so the TUI can recognize
  * this session as launcher-managed worktree session at /quit time.
+ * `named` records whether the slug was user-chosen (WS-5's auto-remove
+ * predicate consumes it — keep in sync with the worktree-exit marker parse).
  * @param {{ worktreePath: string, branch: string }} plan
  * @param {string} repoRoot
  * @param {string} baseHead - The commit the worktree was based on.
+ * @param {boolean} named - True when the user supplied the slug.
  * @returns {Record<string, string>}
  */
-export function worktreeEnv(plan, repoRoot, baseHead) {
+export function worktreeEnv(plan, repoRoot, baseHead, named) {
   return {
     [WORKTREE_ENV]: JSON.stringify({
       repoRoot,
       worktreePath: plan.worktreePath,
       branch: plan.branch,
       baseHead,
+      named: Boolean(named),
     }),
   }
 }
@@ -430,3 +629,189 @@ export function versionGate(runVersion) {
   }
   return { ok: true }
 }
+
+// --- dev-build version stamp + store restore ---------------------------------
+
+/**
+ * Read a dev-build stamp written by scripts/stamp-build-info.mjs into the
+ * profile's @dsh-cc scope. Any problem (missing file, EACCES, malformed
+ * JSON) fails open to null — the launcher must never brick on a stamp.
+ *
+ * @param {string} stampPath
+ * @returns {Record<string, unknown> | null}
+ */
+export function readBuildInfo(stampPath) {
+  try {
+    return JSON.parse(readFileSync(stampPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Version label for `dsh-cc --version`: bare semver for release installs,
+ * `<base>-dev+<commit>[.dirty]` for a dev-synced profile. The stamp's own
+ * version wins over the launcher's — the commit describes that tree.
+ *
+ * @param {string} version launcher's own package.json version
+ * @param {Record<string, unknown> | null} info parsed stamp or null
+ * @returns {string}
+ */
+export function formatVersionLabel(version, info) {
+  if (info?.channel !== 'dev') return version
+  const base = (typeof info.version === 'string' && info.version) || version
+  const commit = (typeof info.commit === 'string' && info.commit) || 'unknown'
+  return `${base}-dev+${commit}${info.dirty === true ? '.dirty' : ''}`
+}
+
+/**
+ * Decide whether the profile's dev store copy must be restored to store
+ * bundles: only when the stamp pairs this profile with a DIFFERENT launcher
+ * version than the one now running. Unknown pairing (no launcherVersion)
+ * never destroys dev state.
+ *
+ * @param {Record<string, unknown> | null} info
+ * @param {string} ownVersion
+ * @returns {{ from: string, to: string } | null}
+ */
+export function devStoreRestoreDecision(info, ownVersion) {
+  if (info?.channel !== 'dev') return null
+  const seen = info.launcherVersion
+  if (typeof seen !== 'string' || seen.length === 0 || seen === ownVersion) return null
+  return { from: seen, to: ownVersion }
+}
+
+/**
+ * Restore a dev-synced profile to store bundles after a launcher update
+ * (plan §3.4). Set-aside + rename dance is atomic per step; any unexpected
+ * throw is rolled back best-effort and reported, never escaping to the bin.
+ *
+ * @param {string} profileDir
+ * @param {string} ownVersion
+ * @param {{ spawnSyncImpl?: typeof import('node:child_process').spawnSync, log?: (...a: unknown[]) => void, now?: () => number }} [deps]
+ * @returns {{ restored: boolean, reason?: string, from?: string, to?: string }>}
+ */
+export function runStoreRestore(profileDir, ownVersion, deps = {}) {
+  const { spawnSyncImpl = spawnSync, log = console.error, now = Date.now } = deps
+  const scope = join(profileDir, 'node_modules', '@dsh-cc')
+  const backup = `${scope}.__dev-restore-backup`
+  const lock = join(profileDir, 'node_modules', '.dsh-cc-restore.lock')
+  const stamp = join(scope, 'dsh-cc-build.json')
+  const home = dirname(dirname(profileDir))
+  const presetDir = join(home, '.agent-presets', 'cc')
+  // The bin always hands us <home>/profiles/<PROFILE>; deriving the name keeps
+  // the function honest when tests pass tmp profile dirs.
+  const profileName = basename(profileDir)
+  let locked = false
+  // Rollback cleanup may only touch `scope` once the dev state is safely in
+  // `backup` — a throw BEFORE the set-aside must leave the profile untouched.
+  let setAside = false
+
+  const tryRename = (from, to) => {
+    try {
+      renameSync(from, to)
+      return true
+    } catch (error) {
+      log(`dsh-cc: dev-store restore: rename ${from} -> ${to} failed: ${/** @type {Error} */ (error).message}`)
+      return false
+    }
+  }
+  const tryRm = (target, recursive) => {
+    try {
+      rmSync(target, { recursive, force: true })
+      return true
+    } catch (error) {
+      log(`dsh-cc: dev-store restore: failed to remove ${target}: ${/** @type {Error} */ (error).message}`)
+      return false
+    }
+  }
+
+  try {
+    // 1. Lock FIRST: exclusive create; a lock younger than ten minutes means
+    // another launch is mid-restore — skip (launch as-is; transient until the
+    // holder finishes). Stale locks are taken over. Crash recovery MUST run
+    // only with the lock held: recovering backup->scope while a live holder
+    // re-materializes would let the holder delete the stamp out of the
+    // recovered dev scope and report success — dev code booting while
+    // --version claims a release, with no retry ever firing again.
+    let handle
+    try {
+      handle = openSync(lock, 'wx')
+      locked = true
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') throw error
+      let fresh = true
+      try {
+        fresh = now() - statSync(lock).mtimeMs < 10 * 60 * 1000
+      } catch { /* lock vanished between EEXIST and stat: proceed to retry */ }
+      if (fresh) {
+        log('dsh-cc: dev-store restore already in progress, skipping')
+        return { restored: false, reason: 'locked' }
+      }
+      tryRm(lock, false)
+      try {
+        handle = openSync(lock, 'wx')
+        locked = true
+      } catch {
+        log('dsh-cc: dev-store restore already in progress, skipping')
+        return { restored: false, reason: 'locked' }
+      }
+    }
+    closeSync(handle)
+
+    // 2. Crash recovery: a previous restore died between set-aside and commit.
+    if (existsSync(backup) && !existsSync(scope)) {
+      log('dsh-cc: dev-store restore: recovering interrupted restore (backup -> scope)')
+      if (!tryRename(backup, scope)) return { restored: false, reason: 'error' }
+    }
+
+    // Read the stamp BEFORE renaming the scope away, for the notice's `from`.
+    const info = readBuildInfo(stamp)
+    const from = (typeof info?.launcherVersion === 'string' && info.launcherVersion) || 'unknown'
+
+    // 3. Set aside the whole dev scope — presence is not content (pnpm trusts
+    // name+version), so it must never stay in place during re-materialize.
+    if (!tryRename(scope, backup)) return { restored: false, reason: 'error' }
+    setAside = true
+
+    // 4. Re-materialize from the registry, same command surface as first boot.
+    const result = spawnSyncImpl('dsh', ['plugin', '--profile', profileName, 'add', ...BUNDLES.map(n => `${n}@${ownVersion}`)], {
+      stdio: 'inherit',
+      env: spawnEnv(sanitizeInheritedEnv(process.env), home),
+    })
+    const success = !result.error && result.status === 0
+
+    if (success) {
+      // 5. Commit: drop backup + stamp, then preset cleanup.
+      tryRm(backup, true)
+      tryRm(stamp, false)
+      try {
+        if (existsSync(presetDir)) {
+          const marker = JSON.parse(readFileSync(join(presetDir, '.dsh-cc-managed.json'), 'utf8'))
+          if (marker?.owner !== '@dsh-cc/tui') throw new Error('unowned preset copy')
+        }
+      } catch {
+        tryRm(presetDir, true)
+        log('dsh-cc: removed dev preset copy at .agent-presets/cc (store boot will reinstall it)')
+      }
+      log(`dsh-cc: launcher updated ${from} → ${ownVersion}; restored store bundles in profile "${profileName}" (re-run scripts/sync-local-profile.sh to resume a dev build)`)
+      return { restored: true, from, to: ownVersion }
+    }
+
+    // 6. Failure: drop pnpm's partials and put the dev state back.
+    tryRm(scope, true)
+    if (!tryRename(backup, scope)) return { restored: false, reason: 'plugin-add-failed' }
+    log(`dsh-cc: dev-store restore failed (will retry on next launch; if the new dsh-cc version was just published, npm/pnpm's minimum-release-age window may still be hiding it)`)
+    return { restored: false, reason: 'plugin-add-failed' }
+  } catch (error) {
+    log(`dsh-cc: dev-store restore failed unexpectedly: ${/** @type {Error} */ (error).message}`)
+    // Roll back ONLY if the set-aside happened: removing the scope before
+    // that point would destroy intact dev state over a transient error
+    // (e.g. EACCES creating the lock) and brick the profile.
+    if (setAside) tryRm(scope, true)
+    if (existsSync(backup) && !existsSync(scope)) tryRename(backup, scope)
+    return { restored: false, reason: 'error' }
+  } finally {
+    if (locked) tryRm(lock, false)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-cc/cli",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Optional dsh-cc shortcut: bootstraps the tui profile and runs dsh --profile tui",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin",
-    "bootstrap.mjs"
+    "bootstrap.mjs",
+    "worktree-lifecycle.mjs"
   ],
   "repository": {
     "type": "git",

package/worktree-lifecycle.mjs

@@ -0,0 +1,379 @@
+/**
+ * WS-4 lifecycle logic for the plain-JS launcher (docs/plans/
+ * 2026-09-14-cc-worktree-parity.md §6 WS-4): the fail-open `worktree`
+ * settings subset read, `worktree.baseRef` resolution, the boot-time
+ * worktree sweep, and the name-reuse merged-reset predicate. Pure over an
+ * injected `git` runner (spawnSync result shape) so tests drive every
+ * decision table without spawning git. Mirrors
+ * packages/workspace/tool-git-worktree/src/lifecycle.ts — keep in sync.
+ * @module @dsh-cc/cli/worktree-lifecycle
+ */
+
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Consumption-time defaults for the `worktree` settings section. */
+export const WORKTREE_DEFAULTS = { baseRef: 'fresh', cleanupPeriodDays: 30 }
+
+/** How stale the cached origin/HEAD may be before a refresh fetch. */
+export const FRESH_CACHE_WINDOW_MS = 24 * 60 * 60 * 1000
+
+/** Overall sweep wall-clock cap (ms). */
+export const SWEEP_CAP_MS = 10_000
+
+/** Refresh-fetch cap (ms). */
+export const FETCH_CAP_MS = 5_000
+
+/** Lock-reason prefix marking dsh-cc-owned worktree locks (sweep key). */
+export const DSH_CC_LOCK_PREFIX = 'dsh-cc '
+
+/** Convention path segment under the main root. */
+export const WORKTREES_DIR_SEGMENTS = ['.claude', 'worktrees']
+
+/** Branch prefix marking dsh-cc-owned worktree branches. */
+export const WORKTREE_BRANCH_PREFIX = 'worktree-'
+
+/**
+ * The settings files the cascade reads for user → project → local, mirrored
+ * from packages/settings/settings-cascade/src/index.ts (userSettings =
+ * `<home>/settings.json`, projectSettings = `<project>/.claude/settings.json`,
+ * localSettings = `<project>/.claude/settings.local.json`). The launcher
+ * cannot load the cascade (pre-build, dependency-free) — this is the
+ * documented subset read; flag/policy layers are ignored.
+ * @param {{ home: string, projectRoot: string }} p
+ */
+export function worktreeSettingsPaths({ home, projectRoot }) {
+  return {
+    user: join(home, 'settings.json'),
+    project: join(projectRoot, '.claude', 'settings.json'),
+    local: join(projectRoot, '.claude', 'settings.local.json'),
+  }
+}
+
+/**
+ * Merge parsed settings documents (low → high precedence) into the
+ * `worktree` section. First defined key wins; unknown shapes ignored.
+ * @param {(Record<string, unknown> | undefined)[]} docs
+ * @returns {{ baseRef: 'fresh' | 'head', cleanupPeriodDays: number }}
+ */
+export function worktreeSettingsFromDocs(docs) {
+  const section = { ...WORKTREE_DEFAULTS }
+  for (const doc of docs) {
+    const worktree = doc && typeof doc === 'object' ? doc.worktree : undefined
+    if (!worktree || typeof worktree !== 'object') continue
+    if (worktree.baseRef === 'fresh' || worktree.baseRef === 'head') section.baseRef = worktree.baseRef
+    if (typeof worktree.cleanupPeriodDays === 'number' && worktree.cleanupPeriodDays >= 0) {
+      section.cleanupPeriodDays = worktree.cleanupPeriodDays
+    }
+  }
+  return section
+}
+
+/**
+ * Fail-open file read of the three settings layers. Any unreadable or
+ * unparseable file is skipped; the defaults survive.
+ * @param {{ user: string, project: string, local: string }} paths
+ * @param {(path: string) => string} [read] - Injectable reader.
+ */
+export function readWorktreeSettings(paths, read = readFileSync) {
+  const docs = []
+  for (const path of [paths.user, paths.project, paths.local]) {
+    try {
+      docs.push(JSON.parse(read(path)))
+    } catch {
+      docs.push(undefined)
+    }
+  }
+  return worktreeSettingsFromDocs(docs)
+}
+
+/**
+ * Resolve the worktree base (WS-4 `worktree.baseRef`). `head` → literal
+ * HEAD; `fresh` → cached `origin/HEAD` symbolic ref, refreshed with one
+ * fetch when its reflog is older than 24h (or unreadable); fallback chain:
+ * cached ref → local HEAD. Any probe error degrades to the next fallback.
+ * @param {(argv: string[], opts?: { timeoutMs?: number, cwd?: string }) => { status: number | null, stdout: string } | undefined} git
+ * @param {'fresh' | 'head'} baseRef
+ * @param {{ now?: number, onFetch?: (branch: string) => void }} [opts]
+ * @returns {Promise<string>} the base to hand to `git worktree add`.
+ */
+export async function resolveBaseRef(git, baseRef, opts = {}) {
+  if (baseRef === 'head') return 'HEAD'
+  const now = opts.now ?? Date.now()
+  const symbolic = git(['symbolic-ref', 'refs/remotes/origin/HEAD'])
+  if (!symbolic || symbolic.status !== 0) return 'HEAD'
+  const ref = symbolic.stdout.trim()
+  if (ref.length === 0) return 'HEAD'
+  const defaultBranch = ref.replace(/^refs\/remotes\/[^/]+\//, '')
+  const reflog = git(['reflog', 'show', ref, '--format=%ct', '-n', '1'])
+  const ageMs = reflog && reflog.status === 0 ? now - Number.parseInt(reflog.stdout.trim(), 10) * 1000 : Number.NaN
+  if (Number.isNaN(ageMs) || ageMs > FRESH_CACHE_WINDOW_MS) {
+    opts.onFetch?.(defaultBranch)
+    git(['fetch', 'origin', defaultBranch], { timeoutMs: FETCH_CAP_MS })
+  }
+  return ref
+}
+
+// --- sweep -------------------------------------------------------------------
+
+/**
+ * One parsed `git worktree list --porcelain` entry.
+ * @typedef {{ path: string, branch: string, locked: boolean, lockReason: string }} WorktreeEntry
+ */
+
+/**
+ * Parse `git worktree list --porcelain` output. Locked entries carry the
+ * reason text (empty when `lock` has none).
+ * @param {string} text
+ * @returns {WorktreeEntry[]}
+ */
+export function parseWorktreeListPorcelain(text) {
+  const entries = []
+  let current = null
+  for (const line of text.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current) entries.push(current)
+      current = { path: line.slice('worktree '.length), branch: '', locked: false, lockReason: '' }
+    } else if (current && line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '')
+    } else if (current && line === 'locked') {
+      current.locked = true
+    } else if (current && line.startsWith('locked ')) {
+      current.locked = true
+      current.lockReason = line.slice('locked '.length)
+    }
+  }
+  if (current) entries.push(current)
+  return entries
+}
+
+/**
+ * Sweep decision for one candidate (all probes pre-run by the caller — this
+ * is the pure decision table). Removal requires ALL of: path under the
+ * convention dir, `worktree-` branch prefix, not locked, age strictly
+ * greater than the window, clean status, nothing unpushed. Locked dsh-cc
+ * worktrees older than the window become advisories (dsh-cc NEVER
+ * auto-releases locks — no trustworthy cross-process liveness oracle).
+ * @param {{
+ *   underConventionDir: boolean
+ *   ownedBranch: boolean
+ *   locked: boolean
+ *   lockReason: string
+ *   ageSeconds: number | undefined
+ *   dirty: boolean | undefined
+ *   unpushed: boolean | undefined
+ *   cleanupPeriodDays: number
+ *   nowSeconds: number
+ * }} p
+ * @returns {'keep' | 'remove' | 'advisory'}
+ */
+export function sweepDecision(p) {
+  const stale = p.ageSeconds !== undefined
+    && p.ageSeconds > p.cleanupPeriodDays * 24 * 60 * 60
+  if (p.locked) {
+    return stale && p.lockReason.startsWith(DSH_CC_LOCK_PREFIX) ? 'advisory' : 'keep'
+  }
+  if (!stale) return 'keep'
+  if (!p.underConventionDir || !p.ownedBranch) return 'keep'
+  if (p.dirty === undefined || p.dirty || p.unpushed === undefined || p.unpushed) return 'keep'
+  return 'remove'
+}
+
+/**
+ * Run the boot-time sweep for a repository. Degrades to a silent no-op on
+ * any probe failure (like the pre-existing `git worktree prune`); never
+ * touches the network; bounded by `deadline` (default {@link SWEEP_CAP_MS}).
+ * @param {{
+ *   repoRoot: string
+ *   cleanupPeriodDays: number
+ *   nowSeconds?: number
+ *   git: (argv: string[], opts?: { timeoutMs?: number, cwd?: string }) => { status: number | null, stdout: string, stderr?: string } | undefined
+ *   deadline?: number
+ *   onAdvisory?: (line: string) => void
+ * }} p
+ * @returns {{ removed: string[], advisories: string[] }}
+ */
+export function sweepWorktrees(p) {
+  const nowSeconds = p.nowSeconds ?? Math.floor(Date.now() / 1000)
+  const deadline = p.deadline ?? SWEEP_CAP_MS
+  const start = Date.now()
+  const expired = () => Date.now() - start >= deadline
+  const git = p.git
+  const noTime = () => expired()
+  const removed = []
+  const advisories = []
+  let list
+  try {
+    list = git(['worktree', 'list', '--porcelain'], { cwd: p.repoRoot })
+  } catch {
+    list = undefined
+  }
+  if (!list || list.status !== 0) return { removed, advisories }
+  if (noTime()) return { removed, advisories }
+  for (const entry of parseWorktreeListPorcelain(list.stdout)) {
+    if (expired()) break
+    const underConventionDir = entry.path.includes(WORKTREES_DIR_SEGMENTS.join('/'))
+    const ownedBranch = entry.branch.startsWith(WORKTREE_BRANCH_PREFIX)
+    let ageSeconds
+    try {
+      // PRIMARY age: last commit inside the worktree.
+      const lastCommit = git(['-C', entry.path, 'log', '-1', '--format=%ct'], { timeoutMs: 2000, cwd: p.repoRoot })
+      const parsed = lastCommit && lastCommit.status === 0
+        ? Number.parseInt(lastCommit.stdout.trim(), 10)
+        : Number.NaN
+      if (Number.isNaN(parsed)) throw new Error('unreadable')
+      ageSeconds = nowSeconds - parsed
+    } catch {
+      // FALLBACK age: directory mtime (only when the commit probe is unreadable).
+      try {
+        ageSeconds = nowSeconds - Math.floor(statSync(entry.path).mtimeMs / 1000)
+      } catch {
+        ageSeconds = undefined
+      }
+    }
+    // No age at all (both probes failed) → fail closed, skip the entry.
+    if (ageSeconds === undefined) continue
+    let dirty
+    let unpushed
+    if (!entry.locked) {
+      try {
+        const status = git(['-C', entry.path, 'status', '--porcelain'], { timeoutMs: 2000, cwd: p.repoRoot })
+        if (!status || status.status !== 0) {
+          dirty = undefined
+        } else {
+          dirty = status.stdout.split('\n').some(line => line.trim().length > 0)
+        }
+      } catch {
+        dirty = undefined
+      }
+      try {
+        const unpushedProbe = git(['-C', entry.path, 'rev-list', '@{u}..HEAD'], { timeoutMs: 2000, cwd: p.repoRoot })
+        if (!unpushedProbe || unpushedProbe.status !== 0) {
+          unpushed = undefined
+        } else {
+          unpushed = unpushedProbe.stdout.trim().length > 0
+        }
+      } catch {
+        unpushed = undefined
+      }
+    }
+    const decision = sweepDecision({
+      underConventionDir,
+      ownedBranch,
+      locked: entry.locked,
+      lockReason: entry.lockReason,
+      ageSeconds,
+      dirty,
+      unpushed,
+      cleanupPeriodDays: p.cleanupPeriodDays,
+      nowSeconds,
+    })
+    if (decision === 'advisory') {
+      const line = `dsh-cc: stale session lock (age > ${p.cleanupPeriodDays}d) on ${entry.path} — run: git worktree unlock ${entry.path}`
+      advisories.push(line)
+      p.onAdvisory?.(line)
+    } else if (decision === 'remove') {
+      const remove = git(['worktree', 'remove', '--force', entry.path], { timeoutMs: 4000, cwd: p.repoRoot })
+      if (!remove || remove.status !== 0) continue
+      git(['branch', '-D', entry.branch], { timeoutMs: 2000, cwd: p.repoRoot })
+      removed.push(entry.path)
+      p.onAdvisory?.(`dsh-cc: swept stale worktree ${entry.path} (branch ${entry.branch})`)
+    }
+  }
+  return { removed, advisories }
+}
+
+// --- name-reuse merged reset ---------------------------------------------------
+
+/**
+ * Reuse-reset predicate for the launcher's named-reuse path (WS-4, CC
+ * merged-reset rule). Pure over pre-run probes. Reset requires ALL of:
+ * clean target, still on its `worktree-` branch, and either no own commits
+ * beyond the base, OR the upstream is gone AND every own commit is
+ * reachable from the resolved fresh base. ANY unverifiable probe keeps the
+ * old tip. A `source` other than 'name' (WS-6 PR reuse) never resets.
+ * @param {{
+ *   source?: 'name' | string
+ *   clean: boolean | undefined
+ *   ownedBranch: boolean
+ *   ownCommits: number | undefined
+ *   upstreamGone: boolean | undefined
+ *   mergedIntoFreshBase: boolean | undefined
+ * }} p
+ * @returns {'reset' | 'keep-tip'}
+ */
+export function reuseResetDecision(p) {
+  if (p.source !== 'name') return 'keep-tip'
+  if (p.clean === undefined || !p.clean) return 'keep-tip'
+  if (!p.ownedBranch) return 'keep-tip'
+  if (p.ownCommits === undefined) return 'keep-tip'
+  if (p.ownCommits === 0) return 'reset'
+  if (p.upstreamGone === true && p.mergedIntoFreshBase === true) return 'reset'
+  return 'keep-tip'
+}
+
+/**
+ * Probe a reused worktree and (when the predicate holds) hard-reset it to
+ * the resolved fresh base before handover. Every probe failure degrades to
+ * keep-tip; the reset itself failing also degrades (worktree is still
+ * handed over as-is).
+ * @param {{
+ *   plan: { worktreePath: string, branch: string }
+ *   repoRoot: string
+ *   freshBase: string
+ *   source?: string
+ *   git: (argv: string[], opts?: { timeoutMs?: number, cwd?: string }) => { status: number | null, stdout: string } | undefined
+ *   onReset?: (freshBase: string) => void
+ * }} p
+ * @returns {{ action: 'reset' | 'keep-tip' }}
+ */
+export function worktreeReuseReset(p) {
+  const git = p.git
+  const probe = (argv) => {
+    try {
+      const r = git(argv, { timeoutMs: 2000, cwd: p.repoRoot })
+      return r && r.status === 0 ? r : undefined
+    } catch {
+      return undefined
+    }
+  }
+  const status = probe(['-C', p.plan.worktreePath, 'status', '--porcelain'])
+  const clean = status !== undefined ? status.stdout.trim().length === 0 : undefined
+  const headBranch = probe(['-C', p.plan.worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'])
+  const ownedBranch = headBranch !== undefined && headBranch.stdout.trim() === p.plan.branch
+    && p.plan.branch.startsWith(WORKTREE_BRANCH_PREFIX)
+  // Own commits: everything on the branch not reachable from the worktree's
+  // recorded base. The branch was created with -B from a base commit; treat
+  // the fresh base as the reference point.
+  let ownCommits
+  if (ownedBranch) {
+    const count = probe(['-C', p.plan.worktreePath, 'rev-list', '--count', `${p.freshBase}..HEAD`])
+    ownCommits = count !== undefined ? Number.parseInt(count.stdout.trim(), 10) : undefined
+    if (Number.isNaN(ownCommits)) ownCommits = undefined
+  }
+  const upstream = probe(['-C', p.plan.worktreePath, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])
+  const upstreamGone = upstream === undefined
+    ? undefined
+    : !probe(['-C', p.plan.worktreePath, 'rev-parse', '--verify', '--quiet', `${upstream.stdout.trim()}^{}`])
+  let mergedIntoFreshBase
+  if (ownCommits !== undefined && ownCommits > 0 && upstreamGone === true) {
+    const merged = probe(['-C', p.plan.worktreePath, 'merge-base', '--is-ancestor', 'HEAD', p.freshBase])
+    mergedIntoFreshBase = merged !== undefined
+  }
+  const action = reuseResetDecision({
+    source: p.source,
+    clean,
+    ownedBranch,
+    ownCommits,
+    upstreamGone,
+    mergedIntoFreshBase,
+  })
+  if (action === 'reset') {
+    const reset = probe(['-C', p.plan.worktreePath, 'reset', '--hard', p.freshBase])
+    if (reset !== undefined) {
+      p.onReset?.(p.freshBase)
+      return { action: 'reset' }
+    }
+  }
+  return { action: 'keep-tip' }
+}