dsh-plugin-worktrees 0.1.0

package/lib/git-port.js

@@ -0,0 +1,773 @@
+/**
+ * GitPort — the git operations abstraction the WorktreeService and MergeQueue
+ * depend on.
+ *
+ * AGENTS.md hard rule: ALL git commands use argv arrays, NEVER shell strings.
+ * The production {@link NodeGitPort} uses `node:child_process` `spawn` with
+ * `shell: false`. Every command is bounded by a timeout (15s default) and a
+ * capped output buffer.
+ *
+ * The port returns STRUCTURED results and never throws on a non-zero git exit
+ * status — the caller inspects `status` / `ok` to decide how to classify the
+ * failure. A throw is reserved for a true spawn failure (binary not found,
+ * timeout killed) which the caller surfaces as `git_not_available`.
+ *
+ * Ported line-for-line from task-weaver `packages/workspaces/src/git-port.ts`
+ * (TS type erasure only) with the DESIGN §4.1 rewrites:
+ *  - class renamed `BunGitPort` → `NodeGitPort` (it never depended on Bun —
+ *    the source imports `node:child_process`; the rename is honesty, not a
+ *    behaviour change);
+ *  - the private mkdtemp `worktreePath()` layout was CUT — the worktree path
+ *    decision belongs to the caller (WorktreeService's explicit layout);
+ *  - new integration-queue methods: `listWorktrees` / `isAncestor` /
+ *    `validateBranch` / `mergeNoFf` / `abortMerge`;
+ *  - `createGitPort({ spawnImpl })` factory as the spawn injection seam.
+ */
+import { spawn } from "node:child_process";
+
+/** Default per-command timeout (matches the testkit fixture bound). */
+const DEFAULT_GIT_TIMEOUT_MS = 15_000;
+
+/** Cap stdout/stderr capture at 8 MiB to bound memory. */
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+/**
+ * Raw git command result: stdout/stderr captured verbatim + exit status.
+ *
+ * @typedef {object} GitCommandResult
+ * @property {string} stdout  captured stdout (utf8).
+ * @property {string} stderr  captured stderr (utf8); carries the
+ *   `[output capped at 8 MiB]` marker when either stream hit the cap.
+ * @property {number} status  git exit status (0 on success).
+ */
+
+/**
+ * Resolved HEAD of a repository.
+ *
+ * @typedef {object} GitHead
+ * @property {string} commit  full commit oid of HEAD.
+ * @property {string} branch  current branch name (detached HEAD reports
+ *   `HEAD`).
+ * @property {boolean} dirty  true when the working tree has uncommitted
+ *   changes.
+ */
+
+/**
+ * Outcome of a worktree creation.
+ *
+ * @typedef {object} WorktreeCreation
+ * @property {string} path    absolute path of the new working tree.
+ * @property {string} branch  branch the worktree was created on.
+ */
+
+/**
+ * Outcome of a commit operation.
+ *
+ * @typedef {object} CommitResult
+ * @property {string} commit        new HEAD commit oid after the commit.
+ * @property {readonly string[]} changedFiles  files changed in this commit
+ *   (relative paths).
+ * @property {readonly GitStatusEntry[]} statusEntries  files changed in this
+ *   commit with status codes, derived from `git diff-tree --name-status -r`.
+ *   Each entry's `path` is the post-rename target. Used by the change
+ *   collector to populate the artifact's `changedFiles[].status` accurately
+ *   for committed changes (porcelain v1 collapses untracked directories
+ *   pre-commit).
+ */
+
+/**
+ * A single file change reported by `git status --porcelain`.
+ *
+ * `statusXY` is the raw 2-char porcelain status code (e.g. `M `, ` A`, `MM`,
+ * `R `, `D `); callers usually consume the normalised `status` field.
+ *
+ * @typedef {object} GitStatusEntry
+ * @property {string} path      relative path of the changed file (post-rename
+ *   target for renames).
+ * @property {"added"|"modified"|"deleted"|"renamed"|"copied"|"type_changed"|"unknown"} status
+ *   normalised change status mapped to the artifact `changedFiles[].status`
+ *   picklist. Falls back to `unknown` for ambiguous combinations.
+ * @property {string} statusXY  raw 2-char porcelain status code (XY).
+ */
+
+/**
+ * One worktree reported by `git worktree list --porcelain`.
+ *
+ * @typedef {object} WorktreeListEntry
+ * @property {string} path      absolute worktree path (git reports the
+ *   realpath).
+ * @property {string} head      HEAD commit oid; empty string when git does not
+ *   report one (e.g. a bare worktree).
+ * @property {string} branch    short branch name (`refs/heads/` prefix
+ *   stripped); empty string for detached-HEAD / bare worktrees.
+ * @property {boolean} detached true when the worktree is on a detached HEAD.
+ */
+
+/**
+ * Run git in `cwd` with an argv array via `spawn` (shell disabled). Rejects
+ * ONLY on spawn failure or timeout; a non-zero exit status is a normal result
+ * the caller inspects via `status`.
+ *
+ * `env` merges over `process.env` so callers can set GIT_AUTHOR_* etc.
+ *
+ * @param {string} cwd
+ * @param {readonly string[]} args
+ * @param {{env?: Record<string, string|undefined>, timeoutMs?: number}} [opts]
+ * @returns {Promise<GitCommandResult>}
+ */
+export function runGit(cwd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", [...args], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...opts.env },
+      shell: false,
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutCapped = false;
+    let stderrCapped = false;
+    child.stdout?.on("data", (chunk) => {
+      if (stdoutCapped) return;
+      const remaining = MAX_BUFFER - stdoutBytes;
+      if (remaining <= 0) {
+        stdoutCapped = true;
+        return;
+      }
+      if (chunk.length <= remaining) {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      } else {
+        // Admit the partial remainder that still fits instead of dropping it.
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes = MAX_BUFFER;
+        stdoutCapped = true;
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderrCapped) return;
+      const remaining = MAX_BUFFER - stderrBytes;
+      if (remaining <= 0) {
+        stderrCapped = true;
+        return;
+      }
+      if (chunk.length <= remaining) {
+        stderrChunks.push(chunk);
+        stderrBytes += chunk.length;
+      } else {
+        stderrChunks.push(chunk.subarray(0, remaining));
+        stderrBytes = MAX_BUFFER;
+        stderrCapped = true;
+      }
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+    }, opts.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS);
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (signal === "SIGKILL") {
+        reject(new Error(`git ${args.join(" ")} timed out`));
+        return;
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      let stderr = Buffer.concat(stderrChunks).toString("utf8");
+      if (stdoutCapped || stderrCapped) {
+        stderr += "\n[output capped at 8 MiB]";
+      }
+      resolve({ stdout, stderr, status: code ?? 0 });
+    });
+  });
+}
+
+/** Trim trailing whitespace from git stdout (oids, branch names). */
+function trim(s) {
+  return s.replace(/\s+$/, "");
+}
+
+/**
+ * Parse `git status --porcelain` output into {@link GitStatusEntry} rows.
+ *
+ * Porcelain v1 line format: `XY <path>` or `XY <orig> -> <path>` for renames,
+ * where XY is the 2-char status code (index state = X, working-tree state = Y).
+ * A space in either position means "no change in that area".
+ *
+ * Status mapping (workspace-and-artifacts.md changedFiles picklist):
+ *  - `R` (rename, X or Y) → `renamed`
+ *  - `A` (index add) / `?` (untracked) → `added`
+ *  - `D` (delete, X or Y) → `deleted`
+ *  - `M` / `T` / `C` / anything else → `modified`
+ *
+ * The post-rename target path is what the artifact records (the file's actual
+ * location after the commit).
+ *
+ * @param {string} stdout
+ * @returns {GitStatusEntry[]}
+ */
+export function parseGitStatusPorcelain(stdout) {
+  const out = [];
+  const lines = stdout.split("\n");
+  for (const raw of lines) {
+    if (raw.length === 0) continue;
+    // Each porcelain line is exactly: XY<space><path>  (3-char prefix minimum).
+    if (raw.length < 3) continue;
+    const xy = raw.slice(0, 2);
+    const body = raw.slice(3);
+    const x = xy.charAt(0);
+    const y = xy.charAt(1);
+
+    // Rename/copy lines use the form: <orig> -> <target>
+    // M2 fix: also check y (worktree status) for R/C, not just x (index status).
+    let path;
+    if (x === "R" || x === "C" || y === "R" || y === "C") {
+      const arrow = body.indexOf(" -> ");
+      path = arrow >= 0 ? body.slice(arrow + 4) : body;
+    } else {
+      path = body;
+    }
+    // Strip surrounding quotes (porcelain quotes paths with special chars).
+    if (path.startsWith('"') && path.endsWith('"') && path.length >= 2) {
+      path = path.slice(1, -1);
+    }
+    if (path.length === 0) continue;
+
+    let status;
+    if (x === "R" || y === "R") status = "renamed";
+    else if (x === "A" || y === "A" || x === "?") status = "added";
+    else if (x === "D" || y === "D") status = "deleted";
+    else status = "modified";
+
+    out.push({ path, status, statusXY: xy });
+  }
+  return out;
+}
+
+/**
+ * Parse `git diff-tree --name-status -r` (or `git diff --name-status`) output.
+ *
+ * Line format: `<status>\t<path>` or `R<tens>\t<orig>\t<target>` for renames
+ * (the rename-similarity percentage is optional and ignored here). The
+ * resulting {@link GitStatusEntry.path} is the post-rename target.
+ *
+ * Status letters (gitsinks/git-status):
+ *  - A → added, M → modified, D → deleted, R → renamed, C → copied,
+ *    T → type_changed. Unrecognised letters fall back to `unknown`.
+ *
+ * @param {string} stdout
+ * @returns {GitStatusEntry[]}
+ */
+export function parseGitNameStatus(stdout) {
+  const out = [];
+  const lines = stdout.split("\n");
+  for (const raw of lines) {
+    if (raw.length === 0) continue;
+    const tab = raw.indexOf("\t");
+    if (tab < 0) continue;
+    const code = raw.slice(0, tab);
+    const rest = raw.slice(tab + 1);
+    const letter = code.charAt(0);
+
+    let path;
+    if (letter === "R" || letter === "C") {
+      const arrow = rest.indexOf("\t");
+      path = arrow >= 0 ? rest.slice(arrow + 1) : rest;
+    } else {
+      path = rest;
+    }
+    if (path.length === 0) continue;
+
+    let status;
+    if (letter === "R") status = "renamed";
+    else if (letter === "A") status = "added";
+    else if (letter === "D") status = "deleted";
+    else if (letter === "C") status = "copied";
+    else if (letter === "T") status = "type_changed";
+    else if (letter === "M") status = "modified";
+    else status = "unknown";
+
+    out.push({ path, status, statusXY: code });
+  }
+  return out;
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into {@link WorktreeListEntry}
+ * rows (new in dsh-worktrees; consumed by list/status and crash reconcile).
+ *
+ * Porcelain format: one blank-line-separated block per worktree; each block
+ * is a sequence of attribute lines —
+ *  - `worktree <path>`   absolute path (git reports the realpath),
+ *  - `HEAD <sha>`        the worktree's HEAD commit,
+ *  - `branch refs/heads/<name>`  checked-out branch (short name recorded),
+ *  - `detached`          bare marker line for detached-HEAD worktrees.
+ * Unknown attribute lines (e.g. `bare`, `prunable ...` on newer gits) are
+ * ignored so parsing survives format additions. A block without a `worktree`
+ * line is dropped.
+ *
+ * @param {string} stdout
+ * @returns {WorktreeListEntry[]}
+ */
+export function parseWorktreeListPorcelain(stdout) {
+  const out = [];
+  let current = null;
+  const flush = () => {
+    if (current !== null && current.path.length > 0) out.push(current);
+    current = null;
+  };
+  for (const raw of stdout.split("\n")) {
+    if (raw.length === 0) {
+      // Blank line terminates the current block.
+      flush();
+      continue;
+    }
+    if (current === null) {
+      current = { path: "", head: "", branch: "", detached: false };
+    }
+    if (raw.startsWith("worktree ")) {
+      current.path = raw.slice("worktree ".length);
+    } else if (raw.startsWith("HEAD ")) {
+      current.head = raw.slice("HEAD ".length);
+    } else if (raw.startsWith("branch ")) {
+      const ref = raw.slice("branch ".length);
+      current.branch = ref.startsWith("refs/heads/")
+        ? ref.slice("refs/heads/".length)
+        : ref;
+    } else if (raw === "detached") {
+      current.detached = true;
+    }
+    // Unknown attribute lines are ignored (forward compatibility).
+  }
+  flush();
+  return out;
+}
+
+/**
+ * Production GitPort backed by `node:child_process` spawn (shell disabled).
+ *
+ * Uses the SAME argv patterns as the testkit fixture
+ * (packages/testkit/src/git-fixture.ts) so behaviour is consistent across the
+ * fixture-driven tests and production.
+ */
+export class NodeGitPort {
+  /**
+   * @param {{env?: Record<string, string|undefined>, timeoutMs?: number,
+   * spawnImpl?: typeof runGit}} [opts]  `spawnImpl` overrides the raw git
+   * runner (injection seam; defaults to {@link runGit}).
+   */
+  constructor(opts = {}) {
+    this.env = { ...process.env, GIT_TERMINAL_PROMPT: "0", ...opts.env };
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    this.spawn = opts.spawnImpl ?? runGit;
+  }
+
+  /** True when `cwd` is inside a git repository (`.git` resolves). */
+  async isGitRepo(cwd) {
+    const r = await this.spawn(cwd, ["rev-parse", "--is-inside-work-tree"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    }).catch(() => null);
+    return r !== null && r.status === 0 && trim(r.stdout) === "true";
+  }
+
+  /** Resolve HEAD commit, current branch, and dirty state for `cwd`.
+   * @returns {Promise<GitHead>} */
+  async resolveHead(cwd) {
+    const head = await this.spawn(cwd, ["rev-parse", "HEAD"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    const branch = await this.spawn(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    const status = await this.spawn(cwd, ["status", "--porcelain"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    return {
+      commit: trim(head.stdout),
+      branch: trim(branch.stdout),
+      dirty: status.stdout.length > 0,
+    };
+  }
+
+  /**
+   * Resolve an arbitrary ref (branch, tag, commit oid, or `HEAD`) to its
+   * concrete commit oid. Uses an argv array with an explicit end-of-options
+   * boundary so a caller-supplied ref can never inject flags. Throws when the
+   * ref does not resolve (the caller MUST fail closed).
+   */
+  async resolveRef(cwd, ref) {
+    // End-of-options boundary prevents a caller-supplied ref from injecting
+    // flags. rev-parse resolves branches, tags, commit oids and HEAD alike.
+    const r = await this.spawn(cwd, ["rev-parse", "--verify", "--end-of-options", ref + "^{commit}"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(`git resolveRef failed for "${ref}": ${trim(r.stderr)}`);
+    }
+    return trim(r.stdout);
+  }
+
+  /**
+   * Create a git worktree at an EXPLICIT `path` on a NEW `branch` off
+   * `baseCommit` (or HEAD when omitted). The `path` parent MUST already
+   * exist; the leaf is created by git.
+   *
+   * (dsh-worktrees rewrite: the task-weaver original resolved the path itself
+   * via a private mkdtemp `worktreePath(branch)` layout — cut per DESIGN §4.1;
+   * the path decision belongs to the caller.)
+   *
+   * @returns {Promise<WorktreeCreation>}
+   */
+  async createWorktree(repoRoot, path, branch, baseCommit) {
+    // git worktree add -b <branch> <path> [<base-commit>]
+    // The caller resolves a concrete absolute path BEFORE calling; the leaf
+    // directory is created by git. We pass the path verbatim (no shell quoting).
+    const args = ["worktree", "add", "-b", branch, path];
+    if (baseCommit !== undefined && baseCommit.length > 0) args.push(baseCommit);
+    const r = await this.spawn(repoRoot, args, { env: this.env, timeoutMs: this.timeoutMs });
+    if (r.status !== 0) {
+      throw new Error(
+        `git worktree add failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+    return { path, branch };
+  }
+
+  /** Remove a worktree (force). Idempotent: a missing worktree is a no-op. */
+  async removeWorktree(repoRoot, path) {
+    // --force so a dirty/unlocked worktree still removes; idempotent on missing.
+    await this.spawn(repoRoot, ["worktree", "remove", "--force", path], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    }).catch(() => {
+      // Swallow: a missing worktree is a no-op (the caller wants it gone).
+    });
+  }
+
+  /** Stage all changes and commit; returns the new HEAD + changed files.
+   * @returns {Promise<CommitResult>} */
+  async commitAll(cwd, message) {
+    const addR = await this.spawn(cwd, ["add", "-A"], { env: this.env, timeoutMs: this.timeoutMs });
+    if (addR.status !== 0) {
+      throw new Error(`git add -A failed (status ${addR.status}): ${addR.stderr}`);
+    }
+    const commitR = await this.spawn(cwd, ["commit", "-m", message], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (commitR.status !== 0) {
+      // A commit with nothing staged exits non-zero; surface as an empty commit.
+      throw new Error(
+        `git commit failed (status ${commitR.status}): ${commitR.stderr || commitR.stdout}`,
+      );
+    }
+    const head = await this.spawn(cwd, ["rev-parse", "HEAD"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    const names = await this.spawn(
+      cwd,
+      ["diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"],
+      { env: this.env, timeoutMs: this.timeoutMs },
+    );
+    const changedFiles = names.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+    // Per-file status from `--name-status` (R/C lines carry `orig -> target`).
+    const statusOut = await this.spawn(
+      cwd,
+      ["diff-tree", "--no-commit-id", "--name-status", "-r", "HEAD"],
+      { env: this.env, timeoutMs: this.timeoutMs },
+    );
+    const statusEntries = parseGitNameStatus(statusOut.stdout);
+    return { commit: trim(head.stdout), changedFiles, statusEntries };
+  }
+
+  /** Checkout `ref` in `cwd`. Throws when the checkout fails. */
+  async checkout(cwd, ref) {
+    const r = await this.spawn(cwd, ["checkout", ref], { env: this.env, timeoutMs: this.timeoutMs });
+    if (r.status !== 0) {
+      throw new Error(`git checkout ${ref} failed (status ${r.status}): ${r.stderr}`);
+    }
+  }
+
+  /**
+   * Cherry-pick `commit` onto the current branch in `cwd`. Resolves on success;
+   * rejects on a git failure (a non-zero exit includes conflicts — inspect
+   * {@link NodeGitPort#listConflicts} to classify).
+   */
+  async cherryPick(cwd, commit) {
+    // argv-only (AGENTS.md hard rule). A non-zero exit signals a conflict or a
+    // real failure — the caller inspects listConflicts() to classify. We do not
+    // pass --strategy options so a conflict surfaces the native git state.
+    const r = await this.spawn(cwd, ["cherry-pick", commit], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git cherry-pick ${commit} failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+  }
+
+  /**
+   * Resolve the merge-base (common ancestor) of two commits/refs. Returns the
+   * commit oid, or throws if git cannot resolve them.
+   */
+  async mergeBase(cwd, a, b) {
+    const r = await this.spawn(cwd, ["merge-base", a, b], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git merge-base ${a} ${b} failed (status ${r.status}): ${r.stderr}`,
+      );
+    }
+    return trim(r.stdout);
+  }
+
+  /**
+   * List files in conflict in `cwd` via `git diff --name-only --diff-filter=U`.
+   * Returns the relative paths of unmerged files (empty when the tree is clean
+   * or the cherry-pick/merge succeeded).
+   */
+  async listConflicts(cwd) {
+    const r = await this.spawn(
+      cwd,
+      ["diff", "--name-only", "--diff-filter=U"],
+      { env: this.env, timeoutMs: this.timeoutMs },
+    );
+    if (r.status !== 0) {
+      // No conflicts to list is a normal state — surface an empty list rather
+      // than throwing so the merge queue can call this defensively.
+      return [];
+    }
+    return r.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+  }
+
+  /**
+   * Add a worktree at an EXPLICIT `path` checking out `ref` (an existing
+   * branch). Used to provision the integration worktree at a deterministic
+   * path. The parent of `path` MUST exist; the leaf is created by git. Unlike
+   * {@link NodeGitPort#createWorktree} this does NOT create a new branch — it
+   * checks out an existing one.
+   */
+  async addWorktreeAt(repoRoot, path, ref) {
+    // git worktree add <path> <ref>  (ref must already exist as a branch).
+    const r = await this.spawn(repoRoot, ["worktree", "add", path, ref], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git worktree add ${path} ${ref} failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+  }
+
+  /**
+   * Ensure `branch` exists in `repoRoot`. When missing, create it at
+   * `startPoint` (default HEAD). Used to bootstrap the integration branch on
+   * first apply. Callers MUST vet caller-supplied names with
+   * {@link NodeGitPort#validateBranch} first (a leading-dash name would land
+   * in flag position for `git branch`).
+   */
+  async ensureBranch(repoRoot, branch, startPoint = "HEAD") {
+    // Existence probe uses an explicit end-of-options boundary so a
+    // caller-supplied branch name can never inject flags (it is vetted by
+    // validateBranch upstream, but the boundary is the same belt-and-braces
+    // resolveRef applies — AGENTS.md red line 2).
+    const exists = await this.spawn(repoRoot, ["rev-parse", "--verify", "--end-of-options", branch], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (exists.status === 0) return;
+    const r = await this.spawn(repoRoot, ["branch", branch, startPoint], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git branch ${branch} ${startPoint} failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+  }
+
+  /**
+   * List working-tree changes via `git status --porcelain`. Returns an empty
+   * array when the tree is clean.
+   */
+  async status(cwd) {
+    const r = await this.spawn(cwd, ["status", "--porcelain"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(`git status failed (status ${r.status}): ${r.stderr}`);
+    }
+    return parseGitStatusPorcelain(r.stdout);
+  }
+
+  // -------------------------------------------------------------------------
+  // New in dsh-worktrees (DESIGN §4.1): integration-queue support methods.
+  // All argv arrays; caller-controlled names sit after `--` or in an option's
+  // value slot, never in flag position.
+  // -------------------------------------------------------------------------
+
+  /**
+   * List the repo's worktrees via `git worktree list --porcelain`, parsed by
+   * {@link parseWorktreeListPorcelain}. Feeds worktree list/status and the
+   * crash reconcile (state file × live worktree comparison).
+   *
+   * @param {string} repoRoot
+   * @returns {Promise<WorktreeListEntry[]>}
+   */
+  async listWorktrees(repoRoot) {
+    const r = await this.spawn(repoRoot, ["worktree", "list", "--porcelain"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(`git worktree list failed (status ${r.status}): ${r.stderr}`);
+    }
+    return parseWorktreeListPorcelain(r.stdout);
+  }
+
+  /**
+   * True when commit `a` is an ancestor of (or equal to) commit `b`.
+   * `git merge-base --is-ancestor` is a two-state probe: exit 0 = yes,
+   * exit 1 = no — both are NORMAL results mapped to a boolean. Any other
+   * non-zero exit (e.g. an unresolvable ref) is a real failure and throws,
+   * same style as {@link NodeGitPort#mergeBase}. Used by cleanup's
+   * unmerged-work protection check.
+   */
+  async isAncestor(repoRoot, a, b) {
+    const r = await this.spawn(repoRoot, ["merge-base", "--is-ancestor", a, b], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status === 0) return true;
+    if (r.status === 1) return false;
+    throw new Error(
+      `git merge-base --is-ancestor ${a} ${b} failed (status ${r.status}): ${r.stderr}`,
+    );
+  }
+
+  /**
+   * True when `name` is a valid branch name (`git check-ref-format --branch`,
+   * exit 0 = valid). Front-door guard for model-supplied task slugs before
+   * they reach createWorktree/ensureBranch/mergeNoFf — rejects `..`, spaces,
+   * leading `-`, control characters, and ambiguous names.
+   */
+  async validateBranch(repoRoot, name) {
+    const r = await this.spawn(repoRoot, ["check-ref-format", "--branch", name], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    return r.status === 0;
+  }
+
+  /**
+   * Merge `branch` into the current branch of `cwd` with `--no-ff`, creating
+   * a merge commit carrying `message`. Rejects on a non-zero exit (a conflict
+   * included) — the caller inspects {@link NodeGitPort#listConflicts} to
+   * classify, exactly like cherryPick. The branch sits AFTER the `--`
+   * end-of-options terminator so a caller-supplied name can never inject
+   * flags (and it is vetted by validateBranch upstream anyway).
+   *
+   * `opts.timeoutMs` OVERRIDES the port-level per-command budget for this
+   * one call (DESIGN §8.1 `mergeTimeoutMs`: merges on big repos legitimately
+   * need a budget of their own, separated from the general 15s gitTimeoutMs).
+   * The override is passed straight to {@link runGit}, which SIGKILLs the
+   * merge process on expiry — the killed merge then surfaces as a non-zero
+   * exit here and the caller's normal conflict/hard-failure classification
+   * applies (a timed-out merge leaves no conflict state, so it lands on the
+   * `failed` path and the integration worktree is cleaned).
+   *
+   * @param {string} cwd
+   * @param {string} branch
+   * @param {string} message
+   * @param {{timeoutMs?: number}} [opts]
+   */
+  async mergeNoFf(cwd, branch, message, opts = {}) {
+    const r = await this.spawn(cwd, ["merge", "--no-ff", "--no-edit", "-m", message, "--", branch], {
+      env: this.env,
+      timeoutMs: opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs)
+        ? opts.timeoutMs
+        : this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git merge --no-ff ${branch} failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+  }
+
+  /**
+   * Delete a branch (force, `git branch -D`). The branch name sits AFTER
+   * the `--` end-of-options terminator so a caller-supplied name can never
+   * inject flags (and is vetted by validateBranch upstream anyway). A
+   * missing branch exits non-zero (`error: branch 'x' not found`) and
+   * THROWS here — callers treat "not found" as the idempotent no-op they
+   * choose to swallow; any other failure (e.g. the branch is checked out
+   * in another worktree) also throws. Used by worktree cleanup.
+   */
+  async deleteBranch(repoRoot, branch) {
+    const r = await this.spawn(repoRoot, ["branch", "-D", "--", branch], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `git branch -D ${branch} failed (status ${r.status}): ${r.stderr || r.stdout}`,
+      );
+    }
+    return true;
+  }
+
+  /**
+   * Abort an in-progress merge in `cwd` (`git merge --abort`). Hard-failure
+   * recovery path only — the conflict-retention path must NOT call this (the
+   * conflicted scene stays for out-of-band resolution). Throws when there is
+   * no merge in progress; callers use it best-effort (`.catch(() => {})`).
+   */
+  async abortMerge(cwd) {
+    const r = await this.spawn(cwd, ["merge", "--abort"], {
+      env: this.env,
+      timeoutMs: this.timeoutMs,
+    });
+    if (r.status !== 0) {
+      throw new Error(`git merge --abort failed (status ${r.status}): ${r.stderr || r.stdout}`);
+    }
+  }
+}
+
+/**
+ * GitPort factory with a spawn-implementation injection seam. Defaults to the
+ * real {@link runGit}; tests (and a future migration onto a host subprocess
+ * service) can inject a fake with the same
+ * `(cwd, args, opts) => Promise<GitCommandResult>` shape. This is the
+ * "self-contained today, swappable tomorrow" seam from DESIGN §4.2 — it adds
+ * no current complexity and zero host coupling.
+ *
+ * @param {{env?: Record<string, string|undefined>, timeoutMs?: number,
+ * spawnImpl?: typeof runGit}} [opts]
+ * @returns {NodeGitPort}
+ */
+export function createGitPort(opts = {}) {
+  return new NodeGitPort(opts);
+}