mandrel 1.57.0

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -0,0 +1,353 @@
+/**
+ * git-branch-lifecycle.js — Shared git branch state machine helpers.
+ *
+ * Consolidates the "does this branch exist locally / remotely?" and
+ * "ensure this branch exists and is checked out" logic that
+ * `story-init.js` and `dispatch-engine.js` had each re-implemented.
+ *
+ * All helpers take an explicit `cwd`. Callers with worktree isolation
+ * enabled pass the worktree path; single-tree callers pass `PROJECT_ROOT`.
+ *
+ * No helper here reads config, spawns its own logger, or knows about
+ * GitHub. They are pure git-subprocess wrappers with validation on the
+ * branch names they forward to git.
+ */
+
+import { assertBranchSafe } from './branch-name-guard.js';
+import { gitPullWithRetry, gitSpawn, gitSync } from './git-utils.js';
+
+/**
+ * Return the current branch name, or null if in detached HEAD state.
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function currentBranch(cwd) {
+  const result = gitSpawn(cwd, 'branch', '--show-current');
+  if (result.status !== 0 || result.stdout.length === 0) return null;
+  return result.stdout;
+}
+
+/**
+ * Return true iff the given branch exists as a local ref in `cwd`'s repo.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function branchExistsLocally(branch, cwd) {
+  assertBranchSafe(branch);
+  return (
+    gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`)
+      .status === 0
+  );
+}
+
+/**
+ * Return true iff the given branch exists on the `origin` remote.
+ *
+ * Issues a network `ls-remote` call. Prefer `branchExistsViaTrackingRef`
+ * after a `git fetch` has already populated the remote-tracking refs.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function branchExistsRemotely(branch, cwd) {
+  assertBranchSafe(branch);
+  const result = gitSpawn(cwd, 'ls-remote', '--heads', 'origin', branch);
+  return result.status === 0 && result.stdout.length > 0;
+}
+
+/**
+ * Return true iff the given branch exists on `origin` according to the
+ * local remote-tracking ref (`refs/remotes/origin/<branch>`).
+ *
+ * This is a purely-local check (no network) that is authoritative whenever
+ * a `git fetch origin` has already been run — e.g. inside `bootstrapWorktree`
+ * and `bootstrapBranch` which always call `cachedGitFetch` first. Use this
+ * instead of `branchExistsRemotely` in those paths to avoid a redundant
+ * network round-trip.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function branchExistsViaTrackingRef(branch, cwd) {
+  assertBranchSafe(branch);
+  return (
+    gitSpawn(
+      cwd,
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `refs/remotes/origin/${branch}`,
+    ).status === 0
+  );
+}
+
+/**
+ * Pure: classify how a `story-<id>` branch should be seeded from the (local,
+ * remote) ref-presence matrix. This is the single source of truth shared by
+ * both story-init paths (Story #3513):
+ *   - `single-story-init.js#decideStoryBranchSeed` (standalone path)
+ *   - `story-init/branch-initializer.js#planStoryBranchSeed` (Epic path)
+ *
+ * Both call sites previously re-implemented the same `local → no-op, remote →
+ * fetch, else create` decision tree; they now delegate here so the branching
+ * logic lives in exactly one place. The two callers keep their own keyword for
+ * the "local ref already exists" outcome (`reuse` vs `none`) — synonyms for
+ * "do not re-create / do not re-seed" preserved for their existing public/test
+ * contracts — so this classifier returns the neutral `'local'` keyword and
+ * each caller maps it onto its own vocabulary.
+ *
+ * @param {{ localHas: boolean, remoteHas: boolean }} presence
+ * @returns {'local'|'fetch'|'create'}
+ *   - `local`  — a local ref already exists; the caller must not run
+ *                `git branch` (which throws on the existing ref) and must not
+ *                fetch.
+ *   - `fetch`  — only the remote ref exists; materialise the local ref.
+ *   - `create` — neither exists; branch from the base/Epic branch.
+ */
+export function classifyBranchSeed({ localHas, remoteHas }) {
+  if (localHas) return 'local';
+  if (remoteHas) return 'fetch';
+  return 'create';
+}
+
+/**
+ * Ensure an Epic branch exists and is published to `origin`. Handles all
+ * four states of the (local, remote) matrix.
+ *
+ * @param {string} epicBranch
+ * @param {string} baseBranch
+ * @param {string} cwd
+ * @param {{ progress?: (phase: string, message: string) => void }} [opts]
+ */
+export async function ensureEpicBranch(epicBranch, baseBranch, cwd, opts = {}) {
+  assertBranchSafe(epicBranch, baseBranch);
+  const progress = opts.progress ?? (() => {});
+
+  // Short-circuit: if we're already on the epic branch, just sync with remote.
+  // This avoids redundant checkout calls and prevents the edge case where
+  // branchExistsLocally returns false while we're on the branch (detached HEAD,
+  // worktree race), which would route into the create path and fail on -b.
+  const onBranch = currentBranch(cwd);
+  if (onBranch === epicBranch) {
+    const remote = branchExistsRemotely(epicBranch, cwd);
+    if (remote) {
+      progress('GIT', `Already on ${epicBranch}. Syncing with remote.`);
+      await gitPullWithRetry(cwd, 'origin', epicBranch);
+    } else {
+      progress('GIT', `Already on ${epicBranch}. Publishing to remote.`);
+      gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
+    }
+    return;
+  }
+
+  const local = branchExistsLocally(epicBranch, cwd);
+  const remote = branchExistsRemotely(epicBranch, cwd);
+
+  if (!local && !remote) {
+    progress('GIT', `Creating Epic branch: ${epicBranch} (from ${baseBranch})`);
+    gitSync(cwd, 'checkout', baseBranch);
+    await gitPullWithRetry(cwd, 'origin', baseBranch);
+    gitSync(cwd, 'checkout', '-b', epicBranch);
+    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
+    _assertOnBranch(cwd, epicBranch);
+    return;
+  }
+
+  if (local && !remote) {
+    progress(
+      'GIT',
+      `Epic branch exists locally only: ${epicBranch}. Publishing.`,
+    );
+    gitSync(cwd, 'checkout', epicBranch);
+    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
+    _assertOnBranch(cwd, epicBranch);
+    return;
+  }
+
+  if (!local && remote) {
+    progress('GIT', `Tracking remote Epic branch: ${epicBranch}`);
+    gitSync(cwd, 'checkout', '-b', epicBranch, `origin/${epicBranch}`);
+    await gitPullWithRetry(cwd, 'origin', epicBranch);
+    _assertOnBranch(cwd, epicBranch);
+    return;
+  }
+
+  progress('GIT', `Epic branch exists. Syncing: ${epicBranch}`);
+  gitSync(cwd, 'checkout', epicBranch);
+  await gitPullWithRetry(cwd, 'origin', epicBranch);
+  _assertOnBranch(cwd, epicBranch);
+}
+
+/**
+ * Post-operation assertion: verify HEAD is on the expected branch.
+ * Guards against TOCTOU races where a parallel agent switches branches
+ * between our checkout and pull.
+ */
+function _assertOnBranch(cwd, expected) {
+  const actual = currentBranch(cwd);
+  if (actual !== expected) {
+    throw new Error(
+      `[git-branch-lifecycle] Branch assertion failed after checkout. ` +
+        `Expected HEAD on '${expected}', found '${actual}'. ` +
+        `A concurrent process may have switched branches.`,
+    );
+  }
+}
+
+/**
+ * Check out a Story branch, creating it from `epicBranch` if neither local
+ * nor remote exists. Non-destructive: if the branch already exists, this
+ * plain-`checkout`s it rather than `-B`-resetting.
+ *
+ * @param {string} storyBranch
+ * @param {string} epicBranch
+ * @param {string} cwd
+ * @param {{ progress?: (phase: string, message: string) => void }} [opts]
+ */
+export async function checkoutStoryBranch(
+  storyBranch,
+  epicBranch,
+  cwd,
+  opts = {},
+) {
+  assertBranchSafe(storyBranch, epicBranch);
+  const progress = opts.progress ?? (() => {});
+
+  // Short-circuit: already on the story branch — just sync.
+  if (currentBranch(cwd) === storyBranch) {
+    const remote = branchExistsRemotely(storyBranch, cwd);
+    if (remote) {
+      progress('GIT', `Already on ${storyBranch}. Syncing with remote.`);
+      await gitPullWithRetry(cwd, 'origin', storyBranch);
+    } else {
+      progress('GIT', `Already on ${storyBranch}. No remote to sync.`);
+    }
+    return;
+  }
+
+  const local = branchExistsLocally(storyBranch, cwd);
+  const remote = branchExistsRemotely(storyBranch, cwd);
+
+  if (local || remote) {
+    progress(
+      'GIT',
+      `Story branch already exists (local=${local}, remote=${remote}). Checking out non-destructively: ${storyBranch}`,
+    );
+    if (local) {
+      gitSync(cwd, 'checkout', storyBranch);
+      if (remote) {
+        await gitPullWithRetry(cwd, 'origin', storyBranch);
+      }
+    } else {
+      gitSync(cwd, 'checkout', '-b', storyBranch, `origin/${storyBranch}`);
+    }
+    return;
+  }
+
+  progress('GIT', `Creating Story branch: ${storyBranch} (from ${epicBranch})`);
+  gitSync(cwd, 'checkout', '-b', storyBranch, epicBranch);
+}
+
+/**
+ * Ensure an Epic branch ref exists locally and is published to `origin`,
+ * **without moving HEAD**. Designed for the worktree bootstrap path where
+ * the main checkout must not switch branches (a parallel agent may be
+ * working there, or the tree may be dirty).
+ *
+ * Uses `git branch` (not `checkout -b`) to create refs, and `git push` to
+ * publish. Callers that need HEAD on the epic branch should use
+ * `ensureEpicBranch()` instead.
+ *
+ * @param {string} epicBranch
+ * @param {string} baseBranch
+ * @param {string} cwd
+ * @param {{ progress?: (phase: string, message: string) => void }} [opts]
+ */
+/**
+ * Pure: choose the action to take for `ensureEpicBranchRef` given whether
+ * the branch exists locally and/or remotely. One of:
+ *   - `'noop'` — both refs exist; nothing to do.
+ *   - `'fetch'` — only remote exists; fetch into local.
+ *   - `'publish-existing'` — only local exists; push it.
+ *   - `'create-and-publish'` — neither exists; create from base then push.
+ *
+ * @param {boolean} local
+ * @param {boolean} remote
+ * @returns {'noop' | 'fetch' | 'publish-existing' | 'create-and-publish'}
+ */
+export function planEnsureEpicBranchRefAction(local, remote) {
+  if (local) return remote ? 'noop' : 'publish-existing';
+  return remote ? 'fetch' : 'create-and-publish';
+}
+
+export function ensureEpicBranchRef(epicBranch, baseBranch, cwd, opts = {}) {
+  assertBranchSafe(epicBranch, baseBranch);
+  const progress = opts.progress ?? (() => {});
+
+  // `ensureEpicBranchRef` is always called after a `git fetch origin` (via
+  // `cachedGitFetch` / `fetchMainRefs` in `bootstrapWorktree`). The
+  // remote-tracking refs are therefore authoritative, so we check
+  // `refs/remotes/origin/<branch>` locally rather than issuing a second
+  // network `ls-remote` call.
+  const action = planEnsureEpicBranchRefAction(
+    branchExistsLocally(epicBranch, cwd),
+    branchExistsViaTrackingRef(epicBranch, cwd),
+  );
+
+  if (action === 'noop') {
+    progress('GIT', `Epic branch ref exists (local+remote): ${epicBranch}`);
+    return;
+  }
+
+  if (action === 'fetch') {
+    progress('GIT', `Fetching remote Epic branch ref: ${epicBranch}`);
+    const res = gitSpawn(cwd, 'fetch', 'origin', `${epicBranch}:${epicBranch}`);
+    if (res.status !== 0) {
+      throw new Error(
+        `ensureEpicBranchRef: failed to fetch ${epicBranch}: ${res.stderr}`,
+      );
+    }
+    return;
+  }
+
+  if (action === 'create-and-publish') {
+    progress(
+      'GIT',
+      `Creating Epic branch ref: ${epicBranch} (from ${baseBranch})`,
+    );
+    gitSync(cwd, 'branch', epicBranch, baseBranch);
+  }
+
+  progress('GIT', `Publishing Epic branch: ${epicBranch}`);
+  gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
+}
+
+/**
+ * Ensure an arbitrary branch exists locally, creating from `baseBranch` if
+ * missing. Used by the dispatcher's task-dispatch path where the expected
+ * side-effect is "branch ref exists"; the caller does not want HEAD to
+ * move. After creation, HEAD is restored to `baseBranch`.
+ *
+ * @param {string} branchName
+ * @param {string} baseBranch
+ * @param {string} cwd
+ * @param {{ log?: (message: string) => void }} [opts]
+ */
+export function ensureLocalBranch(branchName, baseBranch, cwd, opts = {}) {
+  assertBranchSafe(branchName, baseBranch);
+  const log = opts.log ?? (() => {});
+
+  const exists =
+    gitSpawn(cwd, 'rev-parse', '--verify', branchName).status === 0;
+  if (exists) {
+    log(`Branch already exists: ${branchName}`);
+    return;
+  }
+  gitSync(cwd, 'checkout', '-b', branchName, baseBranch);
+  gitSync(cwd, 'checkout', baseBranch);
+  log(`Created branch: ${branchName} from ${baseBranch}`);
+}

package/.agents/scripts/lib/git-merge-orchestrator.js

@@ -0,0 +1,261 @@
+/* node:coverage ignore file -- ephemeral merge orchestrator over live git state; conflict triage tested via integration. Unit-mocking requires asserting only the mock structure */
+
+/**
+ * git-merge-orchestrator.js — Ephemeral Candidate Branch Merge Logic
+ *
+ * Encapsulates the complete merge-and-conflict-resolution lifecycle for
+ * a single Task integration candidate. Extracted from the legacy
+ * integration script to satisfy SRP: the orchestrator owns only Git
+ * state transitions.
+ *
+ * Responsibilities:
+ *   - Create and tear down the ephemeral candidate branch.
+ *   - Detect and triage merge conflicts (major vs minor threshold).
+ *   - Auto-resolve minor conflicts (accept theirs) with audit logging.
+ */
+
+import { resolveConfig } from './config-resolver.js';
+import { gitSpawn } from './git-utils.js';
+
+/**
+ * Analyse conflict severity using git's binary-safe diff --check.
+ *
+ * @param {string} cwd - Project root.
+ * @returns {{ files: number, lines: number, fileList: string[] }}
+ */
+function analyzeConflicts(cwd) {
+  const unmerged = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
+  if (!unmerged.stdout) return { files: 0, lines: 0, fileList: [] };
+
+  const fileList = unmerged.stdout.split('\n').filter(Boolean);
+  const check = gitSpawn(cwd, 'diff', '--check');
+  const markerMatches = check.stdout.match(/leftover conflict marker/g);
+
+  return {
+    files: fileList.length,
+    lines: markerMatches ? markerMatches.length : 0,
+    fileList,
+  };
+}
+
+/**
+ * Merge the feature branch into the current (candidate) branch.
+ * Handles conflict triage and auto-resolution.
+ *
+ * @param {string}   cwd           - Project root.
+ * @param {string}   featureBranch - Branch name to merge in.
+ * @param {Function} vlog          - `(level, context, message, meta)` warn helper for conflict triage output.
+ * @param {object}   [opts]
+ * @param {string}   [opts.message] - Explicit merge commit message (passed as `-m`).
+ * @returns {{ merged: true } | { merged: false, major: true } | never}
+ *   Returns `{ merged: true }` on clean merge or resolved minor conflicts.
+ *   Returns `{ merged: false, major: true }` on major conflict (caller should exit 2).
+ *   Throws on internal git errors.
+ */
+/**
+ * Pure: classify a conflict snapshot as `'major'` (caller aborts) or
+ * `'minor'` (caller auto-resolves). Thresholds default to the values in
+ * `delivery.mergeThresholds` and fall back to file=3, line=20.
+ *
+ * @param {{ files: number, lines: number }} conflicts
+ * @param {{ files?: number, lines?: number } | undefined} thresholds
+ * @returns {'major' | 'minor'}
+ */
+export function classifyConflictSeverity(conflicts, thresholds = {}) {
+  const fileCap = thresholds.files ?? 3;
+  const lineCap = thresholds.lines ?? 20;
+  if (conflicts.files >= fileCap || conflicts.lines >= lineCap) return 'major';
+  return 'minor';
+}
+
+/**
+ * Auto-resolve a minor merge conflict by accepting the feature-branch version
+ * for each file in `conflicts.fileList`, capturing the discarded line counts
+ * for the audit trailer. Side effects: shells out to git checkout/add.
+ *
+ * @returns {Array<{ file: string, discardedLines: number }>}
+ */
+function autoResolveAcceptingTheirs(cwd, conflicts, vlog) {
+  const autoResolvedFiles = [];
+  for (const file of conflicts.fileList) {
+    const ourVersion = gitSpawn(cwd, 'show', `:2:${file}`);
+    const discardedLines = ourVersion.stdout
+      ? ourVersion.stdout.split('\n').length
+      : 0;
+    autoResolvedFiles.push({ file, discardedLines });
+    if (ourVersion.stdout) {
+      vlog(
+        'warn',
+        'integration',
+        `Auto-resolving "${file}" to theirs — discarding base version (${discardedLines} lines)`,
+        {
+          file,
+          discardedLines,
+          discardedPreview: ourVersion.stdout.substring(0, 500),
+        },
+      );
+    }
+    gitSpawn(cwd, 'checkout', '--theirs', file);
+    gitSpawn(cwd, 'add', file);
+  }
+  return autoResolvedFiles;
+}
+
+/**
+ * Commit the auto-resolved working tree. When the caller supplied an explicit
+ * merge message, append the audit trailer; otherwise use git's default
+ * `--no-edit` message.
+ */
+function commitAutoResolution(cwd, opts, autoResolvedFiles) {
+  const trailer = buildAutoResolveTrailer(autoResolvedFiles);
+  const finalMessage = opts.message ? `${opts.message}\n\n${trailer}` : null;
+  const commitArgs = finalMessage
+    ? ['commit', '-m', finalMessage]
+    : ['commit', '--no-edit'];
+  const commitResult = gitSpawn(cwd, ...commitArgs);
+  if (commitResult.status !== 0) {
+    throw new Error(`Auto-resolution commit failed: ${commitResult.stderr}`);
+  }
+}
+
+// Epic #3078: pre-commit hooks (notably lint-staged's stash/restore dance)
+// can leave `git merge --no-ff` exiting 0 without recording the commit.
+// Verify HEAD advanced; distinguish silent failure from "Already up to date".
+function classifyZeroExitMerge({
+  headBefore,
+  headAfter,
+  mergeStdout,
+  featureBranch,
+}) {
+  if (headAfter !== headBefore) return { merged: true };
+  if (/Already up to date/i.test(mergeStdout)) {
+    return { merged: true, alreadyMerged: true };
+  }
+  throw new Error(
+    `git merge --no-ff ${featureBranch} exited 0 but HEAD did not advance ` +
+      `(was ${headBefore || '<unknown>'}). Most likely a pre-commit hook ` +
+      `(commonly lint-staged) accepted the merge content into the index ` +
+      `without recording the commit. Inspect the index and any active ` +
+      `stash, commit the merge content manually if appropriate, then ` +
+      `re-run story-close with --resume. See Epic #3078 for incident notes.`,
+  );
+}
+
+export function mergeFeatureBranch(cwd, featureBranch, vlog, opts = {}) {
+  const headBefore = gitSpawn(cwd, 'rev-parse', 'HEAD').stdout;
+  const mergeArgs = ['merge', '--no-ff', featureBranch];
+  if (opts.message) mergeArgs.push('-m', opts.message);
+  const merge = gitSpawn(cwd, ...mergeArgs);
+  if (merge.status === 0) {
+    return classifyZeroExitMerge({
+      headBefore,
+      headAfter: gitSpawn(cwd, 'rev-parse', 'HEAD').stdout,
+      mergeStdout: merge.stdout,
+      featureBranch,
+    });
+  }
+
+  const conflicts = analyzeConflicts(cwd);
+
+  // `git merge` exited non-zero but the index has no unmerged entries and
+  // no leftover conflict markers. The merge either already landed (a hook
+  // emitted a non-zero exit after the merge commit was created) or was a
+  // no-op (feature branch is already an ancestor / does not exist). In
+  // both cases there is nothing to auto-resolve and nothing to commit —
+  // attempting `git commit` here fails with "nothing to commit", which
+  // turns a successful merge into a fatal and strands story-close work.
+  if (conflicts.files === 0 && conflicts.lines === 0) {
+    return { merged: true, alreadyMerged: true };
+  }
+
+  vlog('warn', 'integration', 'Merge conflict detected', {
+    files: conflicts.files,
+    lines: conflicts.lines,
+    fileList: conflicts.fileList,
+  });
+
+  // Epic #2880 / F14B: read mergeThresholds from the canonical resolved
+  // config (`delivery.mergeThresholds`). The legacy `agentSettings`
+  // pointer is gone — destructuring it throws `Cannot read properties of
+  // undefined`. The threshold block remains optional; `classifyConflict
+  // Severity` falls back to file=3/line=20 when undefined.
+  const config = resolveConfig();
+  const severity = classifyConflictSeverity(
+    conflicts,
+    config?.delivery?.mergeThresholds,
+  );
+  if (severity === 'major') {
+    gitSpawn(cwd, 'merge', '--abort');
+    return { merged: false, major: true, conflicts };
+  }
+
+  const autoResolvedFiles = autoResolveAcceptingTheirs(cwd, conflicts, vlog);
+  commitAutoResolution(cwd, opts, autoResolvedFiles);
+  return { merged: true, autoResolved: true, conflicts, autoResolvedFiles };
+}
+
+/**
+ * Build a merge-commit message body + trailer documenting which files were
+ * auto-resolved by accepting the feature-branch version and how many lines
+ * of the base version were discarded.
+ *
+ * The output is split into three blocks separated by blank lines so
+ * commitlint's per-line caps (`body-max-line-length` and
+ * `footer-max-line-length`, both default 100) all pass:
+ *
+ *   1. Header sentence.
+ *   2. Body prose listing each file and its discarded line count.
+ *   3. `Auto-resolved-file:` trailers — one per file, path only, so the
+ *      verbose line count never appears on the footer line.
+ *
+ * Paths that would still bust the per-line cap are middle-truncated with
+ * an ellipsis. This is a last-resort safety net for pathological repo
+ * layouts; the common case (short relative paths) emits the full path.
+ *
+ * Exported for contract testing of the cap behaviour.
+ *
+ * @param {Array<{ file: string, discardedLines: number }>} resolved
+ * @param {{ maxLineLength?: number }} [opts]
+ * @returns {string}
+ */
+export function buildAutoResolveTrailer(resolved, opts = {}) {
+  const maxLineLength = opts.maxLineLength ?? 100;
+  const header =
+    'Auto-resolved-conflicts: accepted feature branch for the following file(s).';
+
+  const bodyLines = resolved.map((r) => {
+    const suffix = `: discarded ${r.discardedLines} base line(s)`;
+    const prefix = '- ';
+    const available = maxLineLength - prefix.length - suffix.length;
+    return `${prefix}${truncatePathForLine(r.file, available)}${suffix}`;
+  });
+
+  const trailerKey = 'Auto-resolved-file: ';
+  const trailerLines = resolved.map((r) => {
+    const available = maxLineLength - trailerKey.length;
+    return `${trailerKey}${truncatePathForLine(r.file, available)}`;
+  });
+
+  return `${header}\n\n${bodyLines.join('\n')}\n\n${trailerLines.join('\n')}`;
+}
+
+/**
+ * Middle-truncate a path with an ellipsis so it fits within `max`
+ * characters. When `max` is too small to keep any meaningful slice
+ * (≤ 4 chars after the ellipsis), the leading characters win — the
+ * tail is dropped and an ellipsis is appended. Pure helper, no I/O.
+ *
+ * @param {string} p
+ * @param {number} max
+ * @returns {string}
+ */
+function truncatePathForLine(p, max) {
+  if (max <= 0) return '…';
+  if (p.length <= max) return p;
+  const ellipsis = '…';
+  const keep = max - ellipsis.length;
+  if (keep <= 4) return `${p.slice(0, max - 1)}${ellipsis}`;
+  const head = Math.ceil(keep / 2);
+  const tail = Math.floor(keep / 2);
+  return `${p.slice(0, head)}${ellipsis}${p.slice(p.length - tail)}`;
+}