dsh-plugin-worktrees 0.1.0

package/lib/merge-queue.js

@@ -0,0 +1,832 @@
+/**
+ * MergeQueue — the serial integration engine (DESIGN §6, the core module).
+ *
+ * Ported from task-weaver `packages/workspaces/src/merge-queue.ts` +
+ * `change-collector.ts` (collectGit), with the DESIGN §6.1 persistence
+ * rewrite: ServiceContext/repos/leases/transactions are replaced by an
+ * injected StateStore (single writer, atomic flush) and a per-branch
+ * in-process promise chain (the "lease"). Everything else — the one-active
+ * invariant, the conflict-retention semantics, the command state machine —
+ * is carried over line-faithfully.
+ *
+ * INVARIANTS (source merge-queue.ts L16-27, verbatim semantics):
+ *  - ONE active job per repoKey + integrationBranch (queued / applying /
+ *    conflicted). Enforced by `findActiveJob` + the chain.
+ *  - SERIAL apply — never two concurrent applies on the same integration
+ *    branch (`chains` Map tail-chaining).
+ *  - A conflicted job PRESERVES the integration worktree + source branch
+ *    (no force-delete) and HOLDS the branch until `resolve`/`retry`.
+ *  - No auto-push (the GitPort face has no push at all).
+ *
+ * Two DSH-specific mechanisms the source did not need (documented because
+ * they are the only non-mechanical additions):
+ *
+ *  1. `merge --no-ff` instead of cherry-pick (DESIGN §6.3 D7): a DSH
+ *     subagent may make 1..N commits in its worktree; a merge commit
+ *     integrates all of them losslessly while keeping one reviewable
+ *     integration commit per task. Conflict detection is identical.
+ *
+ *  2. Stale-hold release during provisioning: git refuses to check one
+ *     branch out in two worktrees ("'x' is already used by worktree at …").
+ *     task-weaver's temp-dir integration worktrees block invisibly there
+ *     (retry-after-conflict would fail provisioning); DSH keeps deterministic
+ *     paths under `<worktreeRoot>/<repoKey>/.integration/`, so provisioning
+ *     can recognise and remove a STALE hold of the same branch inside OUR
+ *     namespace when no live `conflicted` job references it. Operator
+ *     worktrees outside the namespace are never touched (the provisioning
+ *     failure surfaces as `failed` instead).
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import { integrationWorktreePath, sanitizeBranch } from './naming.js'
+import { ACTIVE_JOB_STATES } from './state-store.js'
+
+/** Truncation bound for git stderr / error details (DESIGN §4.3: 600 chars). */
+const DETAIL_MAX = 600
+
+/** Clamp a detail string to DETAIL_MAX chars with an explicit marker. */
+function clamp(text, max = DETAIL_MAX) {
+  const value = String(text ?? '')
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}…[truncated ${value.length - max} chars]`
+}
+
+/** Error message of an unknown throw (spawn errors, strings, …). */
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error ?? '')
+}
+
+/** realpath() that yields null instead of throwing (missing paths probe). */
+function realPathBestEffort(target) {
+  try {
+    return realpathSync(target)
+  } catch {
+    return null
+  }
+}
+
+/** Fresh merge-job id: `mgj_` + 8 hex chars (crypto.randomBytes). */
+function newJobId() {
+  return `mgj_${randomBytes(4).toString('hex')}`
+}
+
+/**
+ * Vet one integration-branch name with `git check-ref-format --branch`
+ * (audit P1-B): the name reaches `git branch <name> <startPoint>`
+ * (ensureBranch) and `git merge --no-ff … -- <name>` at apply time — a
+ * flag-shaped value (`-m`, `--force`) would land in flag position. Every
+ * entry point that accepts a caller-supplied integration branch (the
+ * worktree_merge override, the DAG four-key enqueue, applyOne's choke
+ * point) funnels through this one guard.
+ *
+ * @throws {MergeError} code `invalid_integration_branch`, message naming
+ *   the offending value and the legal-branch-name rules.
+ */
+export async function assertValidIntegrationBranch(git, repoRoot, integrationBranch) {
+  if (typeof integrationBranch !== 'string' || integrationBranch.length === 0) {
+    throw new MergeError(
+      'invalid_integration_branch',
+      'integration branch must be a non-empty string',
+    )
+  }
+  let valid = false
+  try {
+    valid = await git.validateBranch(repoRoot, integrationBranch)
+  } catch (error) {
+    throw new MergeError(
+      'invalid_integration_branch',
+      `cannot vet integration branch ${JSON.stringify(integrationBranch)} (${errorText(error)})`,
+    )
+  }
+  if (!valid) {
+    throw new MergeError(
+      'invalid_integration_branch',
+      `integration branch name ${JSON.stringify(integrationBranch)} 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")',
+    )
+  }
+  return true
+}
+
+/**
+ * Structured merge-queue error. The tool layer matches `code`.
+ *
+ * NOTE: `active_job_exists` is deliberately NOT one of these codes — a job
+ * holding the branch is an expected business state, represented by
+ * `applyUntilBlockedOrEmpty` returning `{ blockedBy }` (source step 1 maps
+ * it to an error only because task-weaver's callers are internal).
+ */
+export class MergeError extends Error {
+  /**
+   * @param {string} code machine-matchable code (`merge_job_not_found`,
+   *   `invalid_job_state`, `git_operation_failed`, `invalid_params`).
+   * @param {string} message human-readable detail.
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = 'MergeError'
+    this.code = code
+  }
+}
+
+/**
+ * Create a MergeQueue.
+ *
+ * @param {{
+ *   git: import('./git-port.js').NodeGitPort,
+ *   store: ReturnType<import('./state-store.js').createStateStore>,
+ *   config: {
+ *     worktreeRoot: string,
+ *     autoCollect?: boolean,
+ *     mergeTimeoutMs?: number,
+ *     retainJobHistory?: number,
+ *     onError?: (message: string) => void,
+ *   },
+ * }} deps
+ *   `git` / `store` are injected (tests + the future dag-orchestrator seam,
+ *   DESIGN §10). `config` carries RESOLVED values (defaults live in the
+ *   config layer; only `autoCollect !== false` and a `retainJobHistory`
+ *   numeric guard are applied here defensively). `mergeTimeoutMs` is the
+ *   budget for applyOne's merge call (step 7) — applied per-call via
+ *   mergeNoFf's timeoutMs override, separate from the port-level
+ *   gitTimeoutMs (default 15s) so slow big-repo merges are not killed
+ *   early.
+ *   `onError` receives swallowed background-drain failures.
+ * @returns {{
+ *   collect: (worktree: object, commitMessage?: string) => Promise<{state: 'ok'|'no_changes'|'dirty_not_collected', sourceHead: string}>,
+ *   enqueue: (params: object) => object,
+ *   drain: (repoKey: string, integrationBranch: string) => Promise<{drained?: true, blockedBy?: object}>,
+ *   applyUntilBlockedOrEmpty: (repoKey: string, integrationBranch: string) => Promise<{drained?: true, blockedBy?: object}>,
+ *   applyOne: (job: object) => Promise<{state: string, [k: string]: unknown}>,
+ *   cancel: (params: {jobId: string}) => {jobId: string, state: string},
+ *   retry: (params: {jobId: string}) => {jobId: string, state: string},
+ *   resolve: (params: {jobId: string}) => {jobId: string, state: string},
+ *   listJobs: (filters?: {repoKey?: string, integrationBranch?: string}) => object[],
+ *   branchHolders: () => object[],
+ * }}
+ */
+export function createMergeQueue({ git, store, config } = {}) {
+  if (!git || typeof git.mergeNoFf !== 'function') {
+    throw new Error('merge-queue: a GitPort must be injected (missing mergeNoFf)')
+  }
+  if (!store || typeof store.upsertJob !== 'function') {
+    throw new Error('merge-queue: a StateStore must be injected (missing upsertJob)')
+  }
+  if (!config || typeof config.worktreeRoot !== 'string' || config.worktreeRoot.length === 0) {
+    throw new Error('merge-queue: config.worktreeRoot (resolved) is required')
+  }
+  const autoCollect = config.autoCollect !== false
+  const retainJobHistory =
+    Number.isFinite(config.retainJobHistory) && config.retainJobHistory > 0
+      ? Math.floor(config.retainJobHistory)
+      : 200
+  const onError = typeof config.onError === 'function' ? config.onError : null
+  // DESIGN §8.1 `mergeTimeoutMs`: the budget for the ONE long git call in
+  // the apply pipeline (`git merge --no-ff`), separated from the port's
+  // general per-command `gitTimeoutMs` (default 15s) — a merge on a big
+  // repo legitimately needs more. Applied per-call in applyOne step 7 via
+  // mergeNoFf's timeoutMs override (runGit SIGKILLs on expiry; a killed
+  // merge surfaces as a non-zero exit → the normal hard-failure path).
+  const mergeTimeoutMs =
+    Number.isFinite(config.mergeTimeoutMs) && config.mergeTimeoutMs > 0
+      ? Math.floor(config.mergeTimeoutMs)
+      : null
+
+  /**
+   * Per-branch serial chains: `Map<repoKey|integrationBranch, Promise>`.
+   * This is the DESIGN §6.1 replacement for task-weaver's exclusive
+   * ResourceLease — inside one process a tail-chained promise IS strict
+   * serialisation, and every job-state mutation happens inside the chain
+   * (the "CAS is unnecessary" invariant).
+   * @type {Map<string, Promise>}
+   */
+  const chains = new Map()
+
+  const chainKey = (repoKey, integrationBranch) => `${repoKey}|${integrationBranch}`
+
+  /** Flush with the terminal-job retention bound (DESIGN §7.1 prune). */
+  function flush() {
+    store.pruneTerminalJobs(retainJobHistory)
+    store.persist()
+  }
+
+  /** Default merge commit message (DESIGN §5.6): integrate <task> (<short head>). */
+  function defaultIntegrateMessage(job) {
+    const task = store.worktrees[job.worktreeId]?.task ?? job.worktreeId ?? job.id
+    const short = String(job.sourceHead ?? '').slice(0, 8)
+    return `dsh-worktrees: integrate ${task} (${short})`
+  }
+
+  /**
+   * Mirror a job transition onto its worktree record (DESIGN §5.2.2 worktree
+   * state machine: merging → merged/conflicted, or back to active on a hard
+   * failure). Missing worktree records (dag-seeded jobs) are skipped.
+   */
+  function markWorktree(job, state, extra = {}) {
+    if (!job.worktreeId) return
+    const record = store.worktrees[job.worktreeId]
+    if (!record) return
+    store.upsertWorktree({ ...record, state, mergeJobId: job.id, ...extra })
+  }
+
+  // ---------------------------------------------------------------------------
+  // collect — change-collector `collectGit` semantics (source L162-222),
+  // with the DSH §5.6 downgrade: a clean tree at base is `no_changes`, a
+  // NORMAL outcome, not an attempt failure.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Collect uncommitted changes in a task worktree and resolve its head.
+   *
+   * 1. `git.status(path)` — dirty AND autoCollect → `git.commitAll` (a
+   *    commit failure throws `git_operation_failed` with clamped stderr);
+   * 2. `sourceHead = git.resolveHead(path)`;
+   * 3. CLEAN tree whose merge-base with `baseCommit` IS `sourceHead` →
+   *    `{ state: 'no_changes', sourceHead }` (nothing to integrate);
+   * 4. otherwise `{ state: 'ok', sourceHead }`.
+   *
+   * A DIRTY tree with autoCollect=false returns the explicit terminal
+   * `{ state: 'dirty_not_collected', sourceHead }` (audit P2): proceeding
+   * with `ok` would merge the OLD head and report `succeeded` while the
+   * uncommitted files were never integrated — the least misunderstandable
+   * contract is a loud stop. The caller maps it to a failed merge job /
+   * return state with the remediation hint (commit the work, or re-enable
+   * autoCollect).
+   * An unresolvable base (mergeBase throws) fails open toward `ok` — the
+   * merge itself will surface any real problem.
+   *
+   * @param {{path: string, repoRoot?: string, baseCommit?: string, task?: string, id?: string}} worktree
+   * @param {string} [commitMessage]  defaults to `dsh-worktrees: collect <task>`.
+   */
+  async function collect(worktree, commitMessage) {
+    if (!worktree || typeof worktree.path !== 'string' || worktree.path.length === 0) {
+      throw new MergeError('invalid_params', 'collect requires a worktree record with a path')
+    }
+    const entries = await git.status(worktree.path)
+    let collected = false
+    if (entries.length > 0 && autoCollect) {
+      const message =
+        commitMessage ?? `dsh-worktrees: collect ${worktree.task ?? worktree.id ?? 'worktree'}`
+      try {
+        await git.commitAll(worktree.path, message)
+        collected = true
+      } catch (error) {
+        throw new MergeError(
+          'git_operation_failed',
+          `auto-collect commit failed in ${worktree.path}: ${clamp(errorText(error))}`,
+        )
+      }
+    }
+    const sourceHead = (await git.resolveHead(worktree.path)).commit
+    // Dirty tree + autoCollect=false: STOP loudly (see the JSDoc above).
+    if (entries.length > 0 && !collected) {
+      return { state: 'dirty_not_collected', sourceHead }
+    }
+    if (!collected && entries.length === 0 && worktree.baseCommit) {
+      let baseOf = null
+      try {
+        baseOf = await git.mergeBase(
+          worktree.repoRoot ?? worktree.path,
+          sourceHead,
+          worktree.baseCommit,
+        )
+      } catch {
+        // Unresolvable base (unrelated history / dangling oid) — fail open.
+      }
+      if (baseOf === sourceHead) return { state: 'no_changes', sourceHead }
+    }
+    return { state: 'ok', sourceHead }
+  }
+
+  // ---------------------------------------------------------------------------
+  // enqueue (DESIGN §6.2; source L205-251)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Enqueue one merge job: id `mgj_<8hex>`, `orderIndex = nextOrderIndex`
+   * (monotonic per branch), state `queued`, origin default `'tool'`.
+   * Registers `store.repos[repoKey]` so `applyOne` can find the repo root
+   * (the crash-reconcile enumeration source, §5.2.2). Persisted immediately.
+   * Returns the stored job record.
+   *
+   * SYNCHRONOUS, seven-key form — the tool layer's contract
+   * (worktree_merge awaits nothing here; git facts were resolved by its
+   * collect step). The DAG four-key dialect (git facts resolved
+   * server-side from the worktree record + check-ref-format vetting +
+   * idempotence-while-active) is layered on TOP of this by the engine
+   * facade (lib/engine-face.js) — the same "wrap, don't change" rule the
+   * drain projection follows. Defense in depth for BOTH dialects lives in
+   * applyOne's check-ref-format choke point: no job record, however it was
+   * seeded, reaches `git branch <name> <startPoint>` unvetted.
+   */
+  function enqueue(params = {}) {
+    const { repoKey, repoRoot, integrationBranch, worktreeId, sourceBranch, sourceHead } = params
+    const required = { repoKey, repoRoot, integrationBranch, worktreeId, sourceBranch, sourceHead }
+    for (const [name, value] of Object.entries(required)) {
+      if (typeof value !== 'string' || value.length === 0) {
+        throw new MergeError('invalid_params', `enqueue requires a non-empty string ${name}`)
+      }
+    }
+    const { message, origin, correlationId } = params
+    const id = newJobId()
+    const orderIndex = store.nextOrderIndex(repoKey, integrationBranch)
+    store.repos[repoKey] = { root: repoRoot, lastSeenAt: Date.now() }
+    const job = store.upsertJob({
+      id,
+      repoKey,
+      integrationBranch,
+      worktreeId,
+      sourceBranch,
+      sourceHead,
+      orderIndex,
+      state: 'queued',
+      ...(message !== undefined && message !== null ? { message } : {}),
+      origin: origin === 'dag' ? 'dag' : 'tool',
+      ...(correlationId !== undefined && correlationId !== null ? { correlationId } : {}),
+    })
+    flush()
+    return job
+  }
+
+  // ---------------------------------------------------------------------------
+  // Provisioning helpers (step 5)
+  // ---------------------------------------------------------------------------
+
+  /** The plugin's integration namespace dir for one repo. */
+  function integrationNamespace(repoKey) {
+    return path.join(config.worktreeRoot, repoKey, '.integration')
+  }
+
+  /**
+   * Deterministic integration worktree path for one apply attempt. The base
+   * path is jobId-derived (crash reconcile can walk it back to the job); a
+   * retry whose old dir still occupies the base path gets an `-rN` suffix
+   * (git requires the leaf to not exist — source L633-635).
+   */
+  function nextIntegrationPath(job) {
+    const token = sanitizeBranch(job.integrationBranch)
+    const base = integrationWorktreePath(config.worktreeRoot, job.repoKey, token, job.id)
+    if (!existsSync(base)) return base
+    for (let n = 2; n <= 64; n += 1) {
+      const candidate = integrationWorktreePath(
+        config.worktreeRoot,
+        job.repoKey,
+        token,
+        `${job.id}-r${n}`,
+      )
+      if (!existsSync(candidate)) return candidate
+    }
+    return integrationWorktreePath(
+      config.worktreeRoot,
+      job.repoKey,
+      token,
+      `${job.id}-${Date.now().toString(36)}`,
+    )
+  }
+
+  /**
+   * Remove STALE holds of `job.integrationBranch` inside OUR integration
+   * namespace: git allows a branch in only one worktree, so a leftover
+   * registration (crashed apply, or the retained scene of a job that has
+   * since been resolved/retried) would make `git worktree add` fail.
+   *
+   * Guards (all must hold — operator worktrees are NEVER touched):
+   *  - the live entry's checked-out branch equals this integration branch;
+   *  - the entry path sits inside `<worktreeRoot>/<repoKey>/.integration`
+   *    (realpath-compared: git reports realpaths, worktreeRoot may be a
+   *    symlinked prefix e.g. /var → /private/var on macOS);
+   *  - its leaf name carries this branch's sanitized prefix;
+   *  - it is NOT the retained scene of a live `conflicted` job on this
+   *    branch (those keep the branch by design until resolve/retry).
+   */
+  async function releaseStaleIntegrationHolds(repoRoot, job) {
+    let entries
+    try {
+      entries = await git.listWorktrees(repoRoot)
+    } catch {
+      return // probe failure → let addWorktreeAt surface the real error
+    }
+    const nsReal = realPathBestEffort(integrationNamespace(job.repoKey))
+    if (nsReal === null) return // namespace absent → nothing stale can exist
+    const prefix = `${sanitizeBranch(job.integrationBranch)}-`
+    const retained = new Set()
+    for (const other of Object.values(store.jobs)) {
+      if (
+        other.state === 'conflicted' &&
+        other.repoKey === job.repoKey &&
+        other.integrationBranch === job.integrationBranch &&
+        other.integrationWorktree
+      ) {
+        retained.add(realPathBestEffort(other.integrationWorktree) ?? other.integrationWorktree)
+      }
+    }
+    for (const entry of entries) {
+      if (entry.branch !== job.integrationBranch) continue
+      const entryReal = realPathBestEffort(entry.path)
+      if (entryReal === null) continue
+      if (path.dirname(entryReal) !== nsReal) continue
+      if (!path.basename(entryReal).startsWith(prefix)) continue
+      if (retained.has(entryReal)) continue
+      await git.removeWorktree(repoRoot, entry.path).catch(() => {})
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // applyOne — the ten steps (DESIGN §6.3 table, source #applyNextBody
+  // L495-845). Step numbers in comments reference the DESIGN table rows.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Mark a job terminally `failed` (source markFailed L904-947 — the
+   * "queued or applying, either way it is failed now" transition) and return
+   * the failed outcome.
+   */
+  function markFailedOutcome(job, headline, detail) {
+    const error = clamp(detail ? `${headline}: ${detail}` : headline)
+    const fresh = store.jobs[job.id] ?? job
+    store.upsertJob({ ...fresh, state: 'failed', error })
+    markWorktree(job, 'active')
+    flush()
+    return { state: 'failed', error, job: store.jobs[job.id] }
+  }
+
+  /**
+   * Apply ONE queued job on its integration branch (must be called inside
+   * the branch's serial chain). Never throws for git-level problems — those
+   * are classified into `conflicted` (scene retained) or `failed` (scene
+   * cleaned) outcomes, exactly like the source.
+   */
+  async function applyOne(inputJob) {
+    const jobId = inputJob.id
+    const job = store.jobs[jobId] ?? inputJob
+    const { repoKey, integrationBranch } = job
+
+    // Step 1 (source L506-520) — double-check the branch holder. A queued
+    // active job is the one we would apply (fall through); applying/conflicted
+    // means the branch is busy.
+    const active = store.findActiveJob(repoKey, integrationBranch)
+    if (active !== undefined && active.state !== 'queued') {
+      return { state: 'blocked', blockedBy: active }
+    }
+    if (job.state !== 'queued') {
+      // The record moved between the caller's read and now (defensive; the
+      // chain makes this unreachable in practice).
+      return { state: 'blocked', blockedBy: job }
+    }
+
+    // Step 3 (source artifact validation L535-579) — its DSH equivalent ran
+    // before enqueue (§5.6 step 2 collect produced sourceHead). The
+    // markFailed path is kept for a missing/foreign record.
+    if (!job.sourceBranch || !job.sourceHead) {
+      return markFailedOutcome(
+        job,
+        'source head missing',
+        `job ${jobId} carries no sourceBranch/sourceHead (collect before enqueue)`,
+      )
+    }
+    const repoRoot = store.repos[repoKey]?.root
+    if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+      return markFailedOutcome(
+        job,
+        'repo root unknown',
+        `no repos entry for repoKey ${repoKey}; enqueue registers it`,
+      )
+    }
+
+    // P1-B choke point (defense in depth): a job record could carry a
+    // poisoned integrationBranch from a hand-edited / pre-fix state.json.
+    // Before ANY git call that puts the name in flag position
+    // (ensureBranch), re-vet it — a violation is a hard failure (scene
+    // never created), keeping the queue drained and the repo untouched.
+    try {
+      await assertValidIntegrationBranch(git, repoRoot, integrationBranch)
+    } catch (error) {
+      return markFailedOutcome(job, 'invalid integration branch', errorText(error))
+    }
+
+    // Step 4 (source CAS L582-631) — queued → applying. The chain's
+    // single-writer property replaces the CAS (DESIGN §6.1).
+    store.upsertJob({ ...job, state: 'applying' })
+    markWorktree(job, 'merging')
+    flush()
+
+    // Step 5 (source L632-657) + Step 6 (baseline, source L659-671).
+    // CRASH-EVIDENCE WRITE ORDER (§6.1 last row): the job record carries
+    // `integrationWorktree` + `integrationHeadBefore` BEFORE the worktree
+    // exists — a crash mid-apply leaves a precise pointer to the scene.
+    let integrationWorktree
+    try {
+      await releaseStaleIntegrationHolds(repoRoot, job)
+      integrationWorktree = nextIntegrationPath(job)
+      const repoHead = (await git.resolveHead(repoRoot)).commit
+      // Bootstrap the integration branch at repo HEAD on first use.
+      await git.ensureBranch(repoRoot, integrationBranch, repoHead)
+      const integrationHeadBefore = await git.resolveRef(repoRoot, integrationBranch)
+      // Baseline patch. A path RECLAIMED from the abandoned list is no
+      // longer abandoned — drop it there so the cleanup scan never targets
+      // the live scene (present only when the job carries such a list).
+      const abandonedLeft = Array.isArray(job.abandonedIntegrationWorktrees)
+        ? job.abandonedIntegrationWorktrees.filter((p) => p !== integrationWorktree)
+        : null
+      store.upsertJob({
+        ...store.jobs[jobId],
+        integrationWorktree,
+        integrationHeadBefore,
+        ...(abandonedLeft !== null ? { abandonedIntegrationWorktrees: abandonedLeft } : {}),
+      })
+      flush()
+      // Parent pre-created; the leaf is created by git (source L633-635).
+      mkdirSync(path.dirname(integrationWorktree), { recursive: true })
+      await git.addWorktreeAt(repoRoot, integrationWorktree, integrationBranch)
+    } catch (error) {
+      // No scene to retain on a provisioning failure (source L646-657);
+      // removeWorktree on a never-added path is an idempotent no-op.
+      await git.removeWorktree(repoRoot, integrationWorktree).catch(() => {})
+      return markFailedOutcome(job, 'integration worktree preparation failed', errorText(error))
+    }
+
+    // Step 7 (source cherry-pick L673-728 → DESIGN D7 merge --no-ff).
+    // mergeTimeoutMs (§8.1) is THIS call's budget — separated from the
+    // port-level gitTimeoutMs so a slow big-repo merge is not killed at 15s.
+    const mergeMessage = job.message ?? defaultIntegrateMessage(job)
+    try {
+      await git.mergeNoFf(integrationWorktree, job.sourceBranch, mergeMessage, {
+        ...(mergeTimeoutMs !== null ? { timeoutMs: mergeTimeoutMs } : {}),
+      })
+    } catch (error) {
+      // Step 8 (source L688-727) — classify conflict vs hard failure.
+      const message = errorText(error)
+      let conflictFiles = []
+      try {
+        conflictFiles = [...(await git.listConflicts(integrationWorktree))]
+      } catch {
+        // listConflicts is best-effort; an empty list still counts as a
+        // conflict when the failure text carries a conflict marker
+        // (defensive semantics, source L696-704).
+      }
+      const hasConflict = conflictFiles.length > 0 || /conflict/i.test(message)
+      if (hasConflict) {
+        // RETAIN the scene: conflicted keeps the integration worktree and
+        // holds the branch (source markConflicted L856-898 + finally L836).
+        store.upsertJob({
+          ...store.jobs[jobId],
+          state: 'conflicted',
+          conflictFiles,
+          error: clamp(message),
+        })
+        markWorktree(job, 'conflicted')
+        flush()
+        return { state: 'conflicted', conflictFiles, job: store.jobs[jobId] }
+      }
+      // Hard failure: abort best-effort, then step-10 cleanup, THEN the
+      // failed persist (failed never retains a scene — source L826-844).
+      await git.abortMerge(integrationWorktree).catch(() => {})
+      await git.removeWorktree(repoRoot, integrationWorktree).catch(() => {})
+      return markFailedOutcome(job, 'merge failed', message)
+    }
+
+    // Step 9 (source L730-825) — success: the merge side effect is committed.
+    let integratedCommit
+    try {
+      integratedCommit = (await git.resolveHead(integrationWorktree)).commit
+    } catch (error) {
+      await git.removeWorktree(repoRoot, integrationWorktree).catch(() => {})
+      return markFailedOutcome(job, 'post-merge HEAD resolution failed', errorText(error))
+    }
+    store.upsertJob({ ...store.jobs[jobId], state: 'succeeded', integratedCommit })
+    markWorktree(job, 'merged', { headCommit: integratedCommit })
+    flush()
+
+    // Step 10 (source finally L826-844) — non-conflicted: best-effort
+    // removal; a removal failure must never mask the applied result.
+    await git.removeWorktree(repoRoot, integrationWorktree).catch(() => {})
+    return { state: 'succeeded', integratedCommit, job: store.jobs[jobId] }
+  }
+
+  // ---------------------------------------------------------------------------
+  // drain / applyUntilBlockedOrEmpty (DESIGN §6.2)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Drain one branch's queue to its natural stopping point (empty or a
+   * conflicted job holding the branch). Tail-chains onto the branch's
+   * promise chain — concurrent calls serialise; the returned promise is the
+   * CALLER's segment (await it to observe this drain's outcome).
+   */
+  function drain(repoKey, integrationBranch) {
+    const key = chainKey(repoKey, integrationBranch)
+    const base = chains.get(key) ?? Promise.resolve()
+    // A rejected predecessor is swallowed here so (a) it never surfaces as
+    // an unhandled rejection and (b) one failing segment never poisons the
+    // next drain — each segment still WAITS for the predecessor to settle,
+    // so strict serialisation is preserved.
+    const next = base
+      .catch(() => {})
+      .then(() => applyUntilBlockedOrEmpty(repoKey, integrationBranch))
+    const cleanup = () => {
+      if (chains.get(key) === next) chains.delete(key)
+    }
+    next.then(cleanup, cleanup)
+    chains.set(key, next)
+    return next
+  }
+
+  /**
+   * Inside the chain: apply queued jobs one at a time until the queue is
+   * empty (`{ drained: true }`) or an applying/conflicted job holds the
+   * branch (`{ blockedBy }`). A hard `failed` outcome does NOT block the
+   * queue (source semantics: failed is terminal, the chain continues).
+   */
+  async function applyUntilBlockedOrEmpty(repoKey, integrationBranch) {
+    for (;;) {
+      const active = store.findActiveJob(repoKey, integrationBranch)
+      if (active !== undefined && active.state !== 'queued') {
+        return { blockedBy: active }
+      }
+      const queuedJobs = store.findQueuedJobs(repoKey, integrationBranch)
+      if (queuedJobs.length === 0) return { drained: true }
+      const outcome = await applyOne(queuedJobs[0])
+      if (outcome.state === 'conflicted') {
+        return { blockedBy: store.jobs[queuedJobs[0].id] ?? queuedJobs[0] }
+      }
+      if (outcome.state === 'blocked') {
+        return { blockedBy: outcome.blockedBy }
+      }
+      // succeeded | failed → loop; each iteration moves one job out of
+      // `queued`, so the loop always makes progress.
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Commands (source L266-400 — cancel / retry / markResolved)
+  // ---------------------------------------------------------------------------
+
+  /** Load a job or throw `merge_job_not_found` (source MERGE_NOT_FOUND). */
+  function requireJob(jobId) {
+    const job = store.jobs[jobId]
+    if (job === undefined) {
+      throw new MergeError('merge_job_not_found', `merge job not found: ${jobId}`)
+    }
+    return job
+  }
+
+  /**
+   * Cancel a QUEUED job → `cancelled` (source cancel L266-297).
+   * Idempotent on an already-cancelled job; any other state throws
+   * `invalid_job_state` (the message names the current state).
+   */
+  function cancel({ jobId }) {
+    const job = requireJob(jobId)
+    if (job.state === 'cancelled') return { jobId, state: 'cancelled' }
+    if (job.state !== 'queued') {
+      throw new MergeError(
+        'invalid_job_state',
+        `cannot cancel a merge job in state '${job.state}' (only 'queued' can be cancelled)`,
+      )
+    }
+    store.upsertJob({ ...job, state: 'cancelled' })
+    flush()
+    return { jobId, state: 'cancelled' }
+  }
+
+  /**
+   * Retry a `failed`/`conflicted` job → `queued` (source retry L313-353).
+   * Clears error / integratedCommit / conflictFiles and the stale
+   * integration-worktree REFERENCE (the directory itself is NOT deleted —
+   * applyOne always provisions a fresh one; source L308-311). A retained
+   * directory that still exists is recorded into
+   * `abandonedIntegrationWorktrees` for the cleanup scan. The re-queued job
+   * goes to the TAIL of the branch queue (`nextOrderIndex`).
+   * Idempotent on an already-queued job.
+   */
+  function retry({ jobId }) {
+    const job = requireJob(jobId)
+    if (job.state === 'queued') return { jobId, state: 'queued' }
+    if (job.state !== 'failed' && job.state !== 'conflicted') {
+      throw new MergeError(
+        'invalid_job_state',
+        `cannot retry a merge job in state '${job.state}' (only 'failed'/'conflicted' can be retried)`,
+      )
+    }
+    const abandoned = Array.isArray(job.abandonedIntegrationWorktrees)
+      ? [...job.abandonedIntegrationWorktrees]
+      : []
+    if (job.integrationWorktree && existsSync(job.integrationWorktree)) {
+      if (!abandoned.includes(job.integrationWorktree)) {
+        abandoned.push(job.integrationWorktree)
+      }
+    }
+    store.upsertJob({
+      ...job,
+      state: 'queued',
+      error: undefined, // dropped by the sanitizer — re-apply starts clean
+      integratedCommit: undefined,
+      conflictFiles: undefined,
+      integrationWorktree: undefined,
+      abandonedIntegrationWorktrees: abandoned,
+      orderIndex: store.nextOrderIndex(job.repoKey, job.integrationBranch),
+    })
+    flush()
+    releaseBranchIfIdle(job.repoKey, job.integrationBranch)
+    return { jobId, state: 'queued' }
+  }
+
+  /**
+   * Resolve a `conflicted` job out-of-band → `resolved` (source
+   * markResolved L368-400). Does NOT force-merge anything — the operator
+   * owns the resolution; the worktree reference fields are KEPT so the
+   * scene stays locatable. Idempotent on an already-resolved job.
+   */
+  function resolve({ jobId }) {
+    const job = requireJob(jobId)
+    if (job.state === 'resolved') return { jobId, state: 'resolved' }
+    if (job.state !== 'conflicted') {
+      throw new MergeError(
+        'invalid_job_state',
+        `cannot resolve a merge job in state '${job.state}' (only 'conflicted' can be resolved)`,
+      )
+    }
+    store.upsertJob({ ...job, state: 'resolved' })
+    flush()
+    releaseBranchIfIdle(job.repoKey, job.integrationBranch)
+    return { jobId, state: 'resolved' }
+  }
+
+  /**
+   * `#releaseRetainedBranchLease` (source L967-975) in the promise-chain
+   * world: once a conflicted job left the active set, the branch is free —
+   * kick one background drain so queued jobs proceed without waiting for
+   * the next tool call. Fire-and-forget; failures are swallowed into the
+   * `onError` callback (never thrown, never unhandled).
+   */
+  function releaseBranchIfIdle(repoKey, integrationBranch) {
+    const key = chainKey(repoKey, integrationBranch)
+    if (chains.has(key)) return // a live chain re-evaluates the queue itself
+    drain(repoKey, integrationBranch).catch((error) => {
+      const text = `merge-queue: background drain on ${key} failed: ${errorText(error)}`
+      if (onError) {
+        try {
+          onError(text)
+        } catch {
+          /* logging must never throw */
+        }
+      }
+    })
+  }
+
+  // ---------------------------------------------------------------------------
+  // Projections (queue `list` data source, DESIGN §5.7)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Job records (copies), optionally filtered by repoKey / integration
+   * branch, enriched with `repoRoot` and `task` from the sibling maps — the
+   * tool layer's list projection needs both and the engine owns the maps.
+   */
+  function listJobs(filters = {}) {
+    const { repoKey, integrationBranch } = filters ?? {}
+    return Object.values(store.jobs)
+      .filter((job) => repoKey === undefined || job.repoKey === repoKey)
+      .filter((job) => integrationBranch === undefined || job.integrationBranch === integrationBranch)
+      .sort(
+        (a, b) =>
+          (Number(a.createdAt) || 0) - (Number(b.createdAt) || 0) ||
+          (Number(a.orderIndex) || 0) - (Number(b.orderIndex) || 0),
+      )
+      .map((job) => ({
+        ...job,
+        repoRoot: store.repos[job.repoKey]?.root ?? null,
+        task: store.worktrees[job.worktreeId]?.task ?? null,
+      }))
+  }
+
+  /** The jobs currently holding a branch slot (queued/applying/conflicted). */
+  function branchHolders() {
+    return Object.values(store.jobs)
+      .filter((job) => ACTIVE_JOB_STATES.has(job.state))
+      .map((job) => ({
+        repoKey: job.repoKey,
+        repoRoot: store.repos[job.repoKey]?.root ?? null,
+        integrationBranch: job.integrationBranch,
+        jobId: job.id,
+        state: job.state,
+      }))
+  }
+
+  return {
+    collect,
+    enqueue,
+    drain,
+    applyUntilBlockedOrEmpty,
+    applyOne,
+    cancel,
+    retry,
+    resolve,
+    listJobs,
+    branchHolders,
+  }
+}