dsh-plugin-worktrees 0.1.0

package/lib/worktree-service.js

@@ -0,0 +1,673 @@
+/**
+ * WorktreeService — worktree-mode CRUD (DESIGN §5.2-§5.5, §5.8).
+ *
+ * Owns the create / list / status / cleanup lifecycle of task worktrees on
+ * top of two injected collaborators:
+ *  - `git`   : a GitPort (lib/git-port.js) — the ONLY git entry point;
+ *  - `store` : a StateStore (lib/state-store.js) — the ONLY persistence.
+ *
+ * Ported semantics from task-weaver
+ * `packages/workspaces/src/workspace-service.ts`:
+ *  - createWorktree flow (L244-360): validate name → duplicate check →
+ *    resolve base → create worktree → persist record;
+ *  - the mutable-HEAD prohibition (L268-284 "saved Run base ... is
+ *    required; current HEAD fallback is forbidden") — the stored
+ *    `baseCommit` is ALWAYS the concrete oid resolved by
+ *    `git.resolveRef`, never a symbolic ref;
+ *  - the physical path layout (L650-661) — re-expressed through
+ *    lib/naming.js `worktreePath` (`<root>/<repoKey>/<session>/<slug>`).
+ *
+ * Error shape: every failure throws `Error('<code> — <detail>')` where code
+ * is the DESIGN §5.3/§5.8 error family (`invalid_task_slug`,
+ * `invalid_integration_branch`, `branch_exists`, `max_worktrees_reached`,
+ * `invalid_base_ref`, `worktree_creation_failed`, `worktree_not_found`,
+ * `cleanup_protected`).
+ * The tool layer (T07) prefixes the tool name; the codes stay machine
+ * matchable. Git stderr embedded into a detail is truncated to 600 chars.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import {
+  integrationBranch as defaultIntegrationBranch,
+  repoIdFromRoot,
+  sanitizeBranch,
+  sessionShortOf,
+  taskBranch,
+  worktreePath,
+} from './naming.js'
+import { ACTIVE_JOB_STATES } from './state-store.js'
+
+/** Truncation bound for git stderr / error details in thrown messages. */
+const DETAIL_MAX = 600
+
+/**
+ * Worktree record states that end the record's lifecycle (DESIGN §5.2.2).
+ * A NEW record with the same branch may be created once the old record is
+ * terminal; terminal records also stop counting against maxWorktrees.
+ */
+const TERMINAL_WORKTREE_STATES = new Set(['merged', 'abandoned', 'vanished'])
+
+/**
+ * States counted against `config.maxWorktrees` (DESIGN §6.1: the limit is a
+ * GLOBAL count across repos). `conflicted` worktrees are retained scenes,
+ * not occupied isolation slots, so they do not count.
+ */
+const COUNTED_WORKTREE_STATES = new Set(['active', 'merging'])
+
+/** Fail loud with a machine-matchable code prefix. */
+function fail(code, detail) {
+  throw new Error(`${code} — ${detail}`)
+}
+
+/** Clamp a detail string to DETAIL_MAX chars with an explicit marker. */
+function clampDetail(text, max = DETAIL_MAX) {
+  const value = String(text ?? '')
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}…[truncated ${value.length - max} chars]`
+}
+
+/** realpath() that yields null instead of throwing (missing paths probe). */
+function realPathBestEffort(target) {
+  try {
+    return realpathSync(target)
+  } catch {
+    return null
+  }
+}
+
+/** Fresh worktree record id: `wt_` + 8 hex chars (crypto.randomBytes). */
+function newWorktreeId() {
+  return `wt_${randomBytes(4).toString('hex')}`
+}
+
+/**
+ * Create a WorktreeService.
+ *
+ * @param {{
+ *   git: import('./git-port.js').NodeGitPort,
+ *   store: ReturnType<import('./state-store.js').createStateStore>,
+ *   config: { worktreeRoot: string, maxWorktrees?: number, defaultBaseRef?: string },
+ * }} deps
+ *   `git` and `store` are injected (tests / future host seams); `config`
+ *   carries the RESOLVED final values — defaults are applied here only as
+ *   defensive fallbacks (DESIGN §9 defaults: maxWorktrees 16,
+ *   defaultBaseRef 'HEAD').
+ * @returns {{
+ *   create: (params: {
+ *     task: string, repoRoot: string, repoKey?: string,
+ *     baseRef?: string, integrationBranch?: string,
+ *     note?: string, sessionId: string,
+ *     origin?: 'tool'|'dag', correlationId?: string,
+ *   }) => Promise<import('./state-store.js').WorktreeRecord>,
+ *   list: (params?: { repoRoot?: string }) => Promise<{
+ *     worktrees: Array<Record<string, unknown>>,
+ *     queueSummary: { activeJobs: Array<Record<string, unknown>>, queuedCount: number },
+ *   }>,
+ *   status: (idOrPath: string) => Promise<Record<string, unknown>>,
+ *   cleanup: (params: {
+ *     idOrPath: string, force?: boolean, acknowledge?: boolean, keepBranch?: boolean,
+ *   }) => Promise<{ id: string, removedWorktree: boolean, removedBranch: boolean, note?: string }>,
+ *   findActiveByTask: (repoRoot: string, task: string) => Promise<import('./state-store.js').WorktreeRecord|null>,
+ * }}
+ */
+export function createWorktreeService({ git, store, config } = {}) {
+  if (!git || typeof git.createWorktree !== 'function') {
+    throw new Error('worktree-service: a GitPort must be injected (missing createWorktree)')
+  }
+  if (!store || typeof store.upsertWorktree !== 'function') {
+    throw new Error('worktree-service: a StateStore must be injected (missing upsertWorktree)')
+  }
+  if (!config || typeof config.worktreeRoot !== 'string' || config.worktreeRoot.length === 0) {
+    throw new Error('worktree-service: config.worktreeRoot (resolved) is required')
+  }
+  const maxWorktrees =
+    Number.isFinite(config.maxWorktrees) && config.maxWorktrees > 0
+      ? Math.floor(config.maxWorktrees)
+      : 16
+  const defaultBaseRef =
+    typeof config.defaultBaseRef === 'string' && config.defaultBaseRef.length > 0
+      ? config.defaultBaseRef
+      : 'HEAD'
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  /** Find a record by exact id OR exact stored path (DESIGN §5.5/§5.8 lookups). */
+  function findRecord(idOrPath) {
+    if (typeof idOrPath !== 'string' || idOrPath === '') return undefined
+    const byId = store.worktrees[idOrPath]
+    if (byId !== undefined) return byId
+    return Object.values(store.worktrees).find((record) => record.path === idOrPath)
+  }
+
+  /**
+   * Live worktree paths for one repo root, as a Set (git reports realpaths).
+   * `null` = the probe itself failed (repo gone / git error) — callers must
+   * NOT interpret a probe failure as orphaning.
+   */
+  async function livePathsFor(repoRoot) {
+    try {
+      const entries = await git.listWorktrees(repoRoot)
+      return new Set(entries.map((entry) => entry.path))
+    } catch {
+      return null
+    }
+  }
+
+  /** True when a stored path matches the live set (raw OR realpath form). */
+  function pathInLiveSet(storedPath, liveSet) {
+    if (liveSet.has(storedPath)) return true
+    const real = realPathBestEffort(storedPath)
+    return real !== null && liveSet.has(real)
+  }
+
+  /**
+   * A record is LIVE when its directory exists on disk AND git still lists
+   * it as a worktree. Anything else is vanished/orphaned (crash or manual
+   * removal) — cleanup prunes the record without touching git.
+   */
+  async function recordIsLive(record) {
+    if (!existsSync(record.path)) return false
+    const liveSet = await livePathsFor(record.repoRoot)
+    if (liveSet === null) return true // probe failed — trust the disk
+    return pathInLiveSet(record.path, liveSet)
+  }
+
+  /**
+   * Minimal queue summary projection for list() (DESIGN §5.4 queue_summary).
+   * T08 (MergeQueue) owns the real semantics; this projection reads the
+   * same store, so it stays correct by construction.
+   */
+  function queueSummary() {
+    const jobs = Object.values(store.jobs)
+    const activeJobs = jobs
+      .filter((job) => ACTIVE_JOB_STATES.has(job.state))
+      .map((job) => ({
+        jobId: job.id,
+        repoRoot: store.repos[job.repoKey]?.root ?? null,
+        integrationBranch: job.integrationBranch,
+        state: job.state,
+      }))
+    const queuedCount = jobs.filter((job) => job.state === 'queued').length
+    return { activeJobs, queuedCount }
+  }
+
+  /**
+   * Advisory slug suggestion for a branch_exists collision: `<slug>-2`,
+   * `<slug>-3`, … skipping branches already recorded (non-terminal) for
+   * this repo, falling back to a random suffix.
+   */
+  function suggestSlug(baseSlug, sessionShort, takenBranches) {
+    for (let n = 2; n <= 32; n += 1) {
+      const candidate = `${baseSlug}-${n}`
+      if (!takenBranches.has(taskBranch(sessionShort, candidate))) return candidate
+    }
+    return `${baseSlug}-${randomBytes(2).toString('hex')}`
+  }
+
+  // -------------------------------------------------------------------------
+  // create (DESIGN §5.3)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create a task worktree: validate the slug → duplicate check →
+   * maxWorktrees gate → resolve base to a CONCRETE oid → `git worktree
+   * add` → persist the record + register the repo.
+   *
+   * `repoKey` may be omitted by engine callers (the DAG seam): it is then
+   * derived from the canonical repoRoot via `repoIdFromRoot` — identical to
+   * what the repo gate computes, so tool- and engine-created records share
+   * one key. `origin` ('tool'|'dag') and `correlationId` are PERSISTED on
+   * the record (DESIGN §10 seam; the DAG reuse-ownership gate reads the
+   * record's correlationId).
+   */
+  async function create(params = {}) {
+    const { task, repoRoot, baseRef, note, sessionId } = params
+    const explicitIntegration = params.integrationBranch
+    if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+      throw new Error(
+        'worktree-service: create requires repoRoot (resolve it via repo-gate first)',
+      )
+    }
+    // Engine callers (the DAG seam) may omit repoKey; derive it the same
+    // way the repo gate does so both entry points agree on one key.
+    const repoKey =
+      typeof params.repoKey === 'string' && params.repoKey.length > 0
+        ? params.repoKey
+        : repoIdFromRoot(realpathSync(repoRoot))
+    // Normalise the PERSISTED repoRoot to its realpath — the canonical form
+    // the tool path already stores (it routes through repo-gate, which
+    // canonicalises). A symlinked/`..` engine caller would otherwise store a
+    // RAW root whose exact-string comparison fails against the canonical
+    // findActiveByTask argument — the repoRoot asymmetry (audit finding).
+    // realpath failure falls back to the raw value, preserving the old
+    // "store verbatim" behaviour.
+    const canonicalRoot = realPathBestEffort(repoRoot) ?? repoRoot
+
+    // 1. Slug: empty or alnum-free sanitisation is unusable as a branch token.
+    //    `sanitizeBranch` maps illegal chars to `_`, so an all-illegal task
+    //    yields a pure `_` slug — meaningless and indistinguishable between
+    //    different tasks; reject it alongside the empty case.
+    const slug = sanitizeBranch(task)
+    if (slug.length === 0 || !/[a-zA-Z0-9]/.test(slug)) {
+      fail(
+        'invalid_task_slug',
+        `task ${JSON.stringify(task)} sanitizes to an unusable branch token ${JSON.stringify(slug)}; ` +
+          'the task slug needs at least one [a-zA-Z0-9_.-] character',
+      )
+    }
+    const sessionShort = sessionShortOf(sessionId) // TypeError on bad input = caller contract
+    const branch = taskBranch(sessionShort, task)
+
+    // 2. git-level name validation. validateBranch returns a boolean (the
+    //    port seam does not surface stderr), so the message names the
+    //    offending branch instead of quoting git output.
+    if (!(await git.validateBranch(repoRoot, branch))) {
+      fail(
+        'invalid_task_slug',
+        `branch name "${branch}" (from task ${JSON.stringify(task)}) is rejected by ` +
+          'git check-ref-format --branch (e.g. "..", leading "-", trailing ".lock", or a lockfile-colliding name)',
+      )
+    }
+
+    // 2b. An EXPLICIT integration branch gets the SAME check-ref-format
+    //     vetting (audit P1-B): the value flows unvalidated into
+    //     `git branch <name> <startPoint>` (ensureBranch) and `mergeNoFf`
+    //     at first merge — a flag-shaped name (`-m`, `--force`) lands in
+    //     flag position there. Only the explicit form is checked: the
+    //     derived default (`dsh-wt/integration/<sessionShort>`) is
+    //     constructed from a sanitized session segment and needs no probe.
+    if (
+      typeof explicitIntegration === 'string'
+      && explicitIntegration.length > 0
+      && !(await git.validateBranch(repoRoot, explicitIntegration))
+    ) {
+      fail(
+        'invalid_integration_branch',
+        `integration branch name "${explicitIntegration}" is rejected by ` +
+          'git check-ref-format --branch (legal branch names: no leading "-" or "-", no "..", ' +
+          'no ASCII control characters or spaces, no trailing ".lock", no "@{"/"@"-only, ' +
+          'no ref-component starting with "."; slashes are allowed, e.g. "dsh-wt/integration/x")',
+      )
+    }
+
+    // 3. Duplicate check — store side (non-terminal record, same repo) and
+    //    git side (the branch already resolves).
+    const takenBranches = new Set(
+      Object.values(store.worktrees)
+        .filter((record) => record.repoKey === repoKey && !TERMINAL_WORKTREE_STATES.has(record.state))
+        .map((record) => record.branch),
+    )
+    const storeDuplicate = takenBranches.has(branch)
+    let gitHasBranch = false
+    try {
+      await git.resolveRef(repoRoot, branch)
+      gitHasBranch = true
+    } catch {
+      // Branch does not resolve — the normal, expected case.
+    }
+    if (storeDuplicate || gitHasBranch) {
+      const suggestion = suggestSlug(slug, sessionShort, new Set([...takenBranches, branch]))
+      fail(
+        'branch_exists',
+        `branch ${branch} already exists for repo ${repoKey}` +
+          `${storeDuplicate ? ' (active worktree record)' : ' (in git)'}` +
+          `; try task slug "${suggestion}" instead`,
+      )
+    }
+
+    // 4. maxWorktrees — global count of active/merging records (DESIGN §6.1).
+    const activeCount = Object.values(store.worktrees).filter((record) =>
+      COUNTED_WORKTREE_STATES.has(record.state),
+    ).length
+    if (activeCount >= maxWorktrees) {
+      fail(
+        'max_worktrees_reached',
+        `${activeCount} active/merging worktrees already recorded (limit ${maxWorktrees}); ` +
+          'run worktree_cleanup on finished worktrees first (merged records need no force; ' +
+          'unmerged ones require BOTH force:true AND acknowledge:true)',
+      )
+    }
+
+    // 5. Base — ALWAYS resolved to a concrete oid before it reaches the
+    //    record. Mutable-HEAD fallback is forbidden (task-weaver L268-284):
+    //    a symbolic base would silently drift when the repo HEAD moves.
+    //    `resolveRef` returns the peeled commit oid, which satisfies the
+    //    invariant by construction.
+    const effectiveBaseRef = baseRef ?? defaultBaseRef
+    let baseOid
+    try {
+      baseOid = await git.resolveRef(repoRoot, effectiveBaseRef)
+    } catch (error) {
+      fail(
+        'invalid_base_ref',
+        `cannot resolve base ref "${effectiveBaseRef}" in ${repoRoot}: ${clampDetail(error.message)}`,
+      )
+    }
+
+    const integration =
+      typeof explicitIntegration === 'string' && explicitIntegration.length > 0
+        ? explicitIntegration
+        : defaultIntegrationBranch(sessionShort)
+
+    // 6. Physical layout `<worktreeRoot>/<repoKey>/<sessionShort>/<slug>`
+    //    (naming.worktreePath). The PARENT is pre-created; git requires the
+    //    leaf to not exist and creates it itself (source L633-635).
+    const wtPath = worktreePath(config.worktreeRoot, repoKey, sessionShort, slug)
+    mkdirSync(path.dirname(wtPath), { recursive: true })
+    try {
+      await git.createWorktree(repoRoot, wtPath, branch, baseOid)
+    } catch (error) {
+      fail(
+        'worktree_creation_failed',
+        `git worktree add for branch ${branch} at ${wtPath} failed: ${clampDetail(error.message)}`,
+      )
+    }
+
+    // 7. Persist. The repos registration is the crash-reconcile enumeration
+    //    source (§5.2.2); StateStore has no upsertRepos, so the live map is
+    //    written directly — persist() re-sanitizes a deep copy on flush.
+    //    origin/correlationId (DESIGN §10 seam): 'tool' by default, 'dag'
+    //    when the engine seam created it; correlationId is the DAG
+    //    attempt id (the reuse-ownership gate's evidence).
+    const now = Date.now()
+    const origin = params.origin === 'dag' ? 'dag' : 'tool'
+    const { correlationId } = params
+    const record = store.upsertWorktree({
+      id: newWorktreeId(),
+      repoKey,
+      repoRoot: canonicalRoot,
+      branch,
+      path: wtPath,
+      baseCommit: baseOid,
+      integrationBranch: integration,
+      sessionId,
+      task,
+      state: 'active',
+      ...(note !== undefined ? { note } : {}),
+      origin,
+      ...(correlationId !== undefined && correlationId !== null ? { correlationId } : {}),
+      createdAt: now,
+      updatedAt: now,
+    })
+    store.repos[repoKey] = { root: canonicalRoot, lastSeenAt: Date.now() }
+    store.persist()
+    return record
+  }
+
+  // -------------------------------------------------------------------------
+  // list (DESIGN §5.4)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List worktree records (optionally filtered by exact repoRoot), each
+   * reconciled against `git worktree list`: a record whose path is absent
+   * from the live listing gets `orphaned: true` (state kept verbatim).
+   */
+  async function list(params = {}) {
+    const { repoRoot } = params ?? {}
+    const records = Object.values(store.worktrees).filter((record) =>
+      repoRoot === undefined ? true : record.repoRoot === repoRoot,
+    )
+    const liveByRoot = new Map()
+    const out = []
+    for (const record of records) {
+      let liveSet = liveByRoot.get(record.repoRoot)
+      if (liveSet === undefined) {
+        liveSet = await livePathsFor(record.repoRoot)
+        liveByRoot.set(record.repoRoot, liveSet)
+      }
+      const orphaned = liveSet !== null && !pathInLiveSet(record.path, liveSet)
+      out.push(orphaned ? { ...record, orphaned: true } : { ...record })
+    }
+    return { worktrees: out, queueSummary: queueSummary() }
+  }
+
+  // -------------------------------------------------------------------------
+  // status (DESIGN §5.5)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Live status of one worktree (by id or exact path): HEAD, dirty flag,
+   * porcelain changes, and whether HEAD moved past baseCommit.
+   */
+  async function status(idOrPath) {
+    const record = findRecord(idOrPath)
+    if (record === undefined) {
+      fail('worktree_not_found', `no worktree record matches id or path "${idOrPath}"`)
+    }
+
+    // Best-effort probes: a worktree that vanished (dir deleted, disk gone)
+    // returns the record with `vanished: true` instead of failing.
+    if (!existsSync(record.path)) {
+      return { ...record, vanished: true }
+    }
+    let changes
+    let head
+    try {
+      const entries = await git.status(record.path)
+      changes = entries.map((entry) => ({ path: entry.path, status: entry.status }))
+      head = (await git.resolveHead(record.path)).commit
+    } catch {
+      return { ...record, vanished: true }
+    }
+
+    // DESIGN §5.5 specifies `ahead_of_base: n` (commit count via
+    // rev-list --count). The GitPort face has no rev-list count method, so
+    // this implementation reports the BOOLEAN projection
+    // `ahead_of_base = isAncestor(baseCommit, head) && head !== baseCommit`
+    // — deliberately NOT adding countAhead to the port (DESIGN §5.8 keeps
+    // the count "留给后置"; the tool layer can extend later).
+    let aheadOfBase = false
+    if (head && head !== record.baseCommit) {
+      try {
+        aheadOfBase = await git.isAncestor(record.repoRoot, record.baseCommit, head)
+      } catch {
+        aheadOfBase = false // probe failure is not "ahead"
+      }
+    }
+    return { ...record, head, dirty: changes.length > 0, changes, ahead_of_base: aheadOfBase }
+  }
+
+  // -------------------------------------------------------------------------
+  // findActiveByTask (DESIGN §10 seam — the DAG reuse probe)
+  // -------------------------------------------------------------------------
+
+  /**
+   * The ACTIVE worktree record for one (repoRoot, task slug), or null.
+   *
+   * Consumer contract (dsh-dag-orchestrator lib/worktrees-seam.js /
+   * executor.js resolveWorktreeCwd): the dispatch-time reuse probe consults
+   * this BEFORE creating — a same-slug active record means a re-dispatched
+   * task resumes in its existing worktree instead of stacking a second
+   * one. The returned record carries its `correlationId` (the create-time
+   * DAG attempt id): the DAG's OWNERSHIP gate reuses the path only when
+   * that id belongs to the dispatching task's own attempt history — this
+   * side just reports the facts.
+   *
+   * Lookup key: the RAW task string recorded at create time (records store
+   * the pre-sanitisation slug verbatim).
+   *
+   * @param {string} repoRoot canonical repo root (compared to record.repoRoot)
+   * @param {string} task task slug as passed to create()
+   * @returns {Promise<import('./state-store.js').WorktreeRecord|null>}
+   */
+  async function findActiveByTask(repoRoot, task) {
+    if (typeof repoRoot !== 'string' || typeof task !== 'string') return null
+    for (const record of Object.values(store.worktrees)) {
+      if (record.repoRoot !== repoRoot) continue
+      if (record.task !== task) continue
+      if (record.state !== 'active') continue
+      return record
+    }
+    return null
+  }
+
+  // -------------------------------------------------------------------------
+  // cleanup (DESIGN §5.8)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Remove one worktree (+ its branch unless keepBranch) after the
+   * unmerged-work protection gate, or prune a vanished record.
+   */
+  async function cleanup(params = {}) {
+    const { idOrPath, force = false, acknowledge = false, keepBranch = false } = params ?? {}
+    const record = findRecord(idOrPath)
+    if (record === undefined) {
+      fail('worktree_not_found', `no worktree record matches id or path "${idOrPath}"`)
+    }
+
+    // Vanished/orphaned record: the worktree directory is already gone, so
+    // there is nothing to protect (no working state) and nothing to remove.
+    // Prune the record ONLY — no git side effects, branch left untouched
+    // (deleting branches of vanished worktrees is an explicit operator
+    // decision, not cleanup's default).
+    if (!(await recordIsLive(record))) {
+      delete store.worktrees[record.id]
+      store.persist()
+      return {
+        id: record.id,
+        removedWorktree: false,
+        removedBranch: false,
+        note: 'record pruned; path already absent from git worktree list',
+      }
+    }
+
+    // Protection (safety red line 4): a non-merged record whose branch is
+    // NOT integrated into its integration branch may only be removed with
+    // the DOUBLE confirmation force && acknowledge (two independent
+    // booleans — a single force:true never passes).
+    //
+    // Two evidence arms decide "unmerged":
+    //  - integration branch RESOLVES → the classic probe: sourceHead must
+    //    be an ancestor of the integration head;
+    //  - integration branch does NOT resolve (never bootstrapped — the
+    //    pre-first-merge window, audit P1-C) → the worktree's own head is
+    //    compared against the recorded baseCommit: any commit past base is
+    //    work that exists nowhere else, so it is unmerged BY DEFINITION
+    //    and the same double-confirmation gate fires.
+    // A worktree whose branch is gone AND whose head sits at base (or
+    // cannot move past base) has no unmerged work — clearable bare.
+    if (record.state !== 'merged' && !(force && acknowledge)) {
+      let sourceHead = null
+      let integrationHead = null
+      try {
+        sourceHead = await git.resolveRef(record.repoRoot, record.branch)
+      } catch {
+        // Branch gone — the head probe below still guards the worktree dir.
+      }
+      try {
+        integrationHead = await git.resolveRef(record.repoRoot, record.integrationBranch)
+      } catch {
+        // Integration branch never bootstrapped — the P1-C arm decides.
+      }
+      if (sourceHead !== null && integrationHead !== null) {
+        let integrated
+        try {
+          integrated = await git.isAncestor(record.repoRoot, sourceHead, integrationHead)
+        } catch (error) {
+          // Cannot PROVE integration → fail closed under the same code.
+          fail(
+            'cleanup_protected',
+            `integration probe failed for worktree ${record.id}: ${clampDetail(error.message)}`,
+          )
+        }
+        if (!integrated) {
+          fail(
+            'cleanup_protected',
+            `worktree ${record.id} (task ${JSON.stringify(record.task)}) branch ${record.branch} ` +
+              `is NOT integrated: sourceHead ${sourceHead} is not an ancestor of ` +
+              `${record.integrationBranch} head ${integrationHead}; to delete unmerged work ` +
+              'pass BOTH force:true AND acknowledge:true (single force is not enough), ' +
+              'or integrate first via worktree_merge',
+          )
+        }
+      } else {
+        // P1-C arm: the integration branch does not resolve (or the task
+        // branch is gone while the worktree still holds commits). Unmerged
+        // work exists when the worktree holds EITHER commits past its
+        // recorded baseCommit OR uncommitted changes in its probe — both are
+        // work that exists nowhere else — so either triggers protection.
+        let worktreeHead = null
+        try {
+          worktreeHead = (await git.resolveHead(record.path)).commit
+        } catch {
+          // Unresolvable head (a live worktree per the probe above should
+          // always resolve) — cannot PROVE absence of work: fail closed.
+          fail(
+            'cleanup_protected',
+            `worktree ${record.id} (task ${JSON.stringify(record.task)}) head is unresolvable ` +
+              `at ${record.path}; cannot PROVE it holds no unmerged work, so bare cleanup is ` +
+              'refused — explicitly pass BOTH force:true AND acknowledge:true to delete, ' +
+              'or integrate first via worktree_merge',
+          )
+        }
+        // Uncommitted changes are unmerged work even when HEAD sits at base
+        // (README: "no commits past base AND no uncommitted work in the
+        // branch probe" is the clearable bare bar). A porcelain flake here
+        // cannot PROVE the tree is clean → fail closed (protect).
+        let dirty = true
+        try {
+          const entries = await git.status(record.path)
+          dirty = Array.isArray(entries) && entries.length > 0
+        } catch {
+          // status probe failure → keep the fail-closed default (dirty=true).
+        }
+        if (dirty) {
+          fail(
+            'cleanup_protected',
+            `worktree ${record.id} (task ${JSON.stringify(record.task)}) holds UNMERGED work: ` +
+              `integration branch ${record.integrationBranch} does not exist yet (no merge has ` +
+              'run) and the worktree probe has uncommitted changes present; ' +
+              'to delete unmerged work pass BOTH force:true AND acknowledge:true ' +
+              '(single force is not enough), or integrate first via worktree_merge',
+          )
+        }
+        // Ahead of base: committed work past base that exists nowhere else.
+        // head being a STRICT ANCESTOR of base (head behind base) is the ONLY
+        // safe case — a divergent/unrelated head holds unique commits, so it
+        // is unmerged. probe failure → assume ahead (fail closed).
+        const ahead =
+          worktreeHead !== record.baseCommit
+          && !(await git
+            .isAncestor(record.repoRoot, worktreeHead, record.baseCommit)
+            .catch(() => false)) // failure → "not a strict ancestor" → ahead
+        if (ahead) {
+          fail(
+            'cleanup_protected',
+            `worktree ${record.id} (task ${JSON.stringify(record.task)}) holds UNMERGED work: ` +
+              `integration branch ${record.integrationBranch} does not exist yet (no merge has ` +
+              `run) while the worktree head ${worktreeHead} is ahead of its base ${record.baseCommit}; ` +
+              'to delete unmerged work pass BOTH force:true AND acknowledge:true ' +
+              '(single force is not enough), or integrate first via worktree_merge',
+          )
+        }
+      }
+    }
+
+    // Remove the worktree (idempotent) and — unless keepBranch — the branch.
+    await git.removeWorktree(record.repoRoot, record.path)
+    let removedBranch = false
+    if (keepBranch !== true) {
+      try {
+        await git.deleteBranch(record.repoRoot, record.branch)
+        removedBranch = true
+      } catch (error) {
+        // `error: branch 'x' not found` = already gone (idempotent prune);
+        // any other failure (e.g. branch checked out elsewhere) surfaces.
+        if (!/not found/i.test(String(error?.message ?? ''))) throw error
+        removedBranch = false
+      }
+    }
+
+    delete store.worktrees[record.id]
+    store.persist()
+    return { id: record.id, removedWorktree: true, removedBranch }
+  }
+
+  return { create, list, status, cleanup, findActiveByTask }
+}