mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/gh-exec.js

@@ -1,74 +1,24 @@
 /**
- * gh-exec.js — spawn-based wrapper around the `gh` CLI.
- *
- * Story #1356 (Epic #1179 — v6 Epic A: MCP + gh CLI rebase). This is the
- * core shim that subsequent provider rewrites build on. It deliberately
- * stays narrow:
- *
- *   - `exec({ args, input, timeoutMs })` shells out via
- *     `child_process.spawn('gh', args, { stdio: ['pipe','pipe','pipe'] })`.
- *     `args` is always an array — no string-interpolated command line, no
- *     `shell: true`. That keeps argument injection impossible by
- *     construction.
- *   - When `args` contains the literal `--json` flag, stdout is run through
- *     `JSON.parse` before returning. Callers that pass `--json` are asking
- *     for structured data; honor that.
- *   - When `args` does not contain `--json`, the raw `{ stdout, stderr, code }`
- *     envelope is returned. This is what `gh api` callers and the few
- *     "read raw text" call sites want.
- *
- * Error surface is intentionally a single base class in this Task —
- * `GhExecTimeoutError` is the only specialization required by the
- * acceptance criteria. Task #1369 layers the rest of the typed error
- * classes (auth-required, not-found, GraphQL, etc.) on top of `GhExecError`.
- * Task #1370 adds the typed convenience wrappers (`issue.view`, `pr.create`,
- * `api`, etc.).
- *
- * The module exports `exec` as the default export plus named exports for
- * the error classes so callers can `instanceof`-check without importing
- * the whole module namespace.
+ * gh-exec.js — `gh` CLI wrapper. `args` is always an array spawned without a
+ * shell, so argument injection is impossible by construction.
  */
 
 import { spawn as defaultSpawn } from 'node:child_process';
 
-/**
- * Throw-away in-process spawn counter (Story #1795 / Epic #1788).
- *
- * Incremented once per `exec()` invocation that successfully reaches the
- * `spawnImpl('gh', ...)` call. Exported via `getSpawnCount` so the
- * Story-close structured comment can emit it under `ghSpawnCount` for
- * the ">=100 fewer spawns" acceptance criterion. This counter is
- * deliberately ephemeral — Story #1795's acceptance includes removing
- * the counter and `getSpawnCount` helper in a follow-up cleanup commit
- * before the Story merges to the Epic branch.
- */
 let _spawnCount = 0;
 
 /**
- * Return the running total of `gh` spawns since this module was loaded
- * (or since the last `resetSpawnCount()` call). Counts every spawn
- * attempt, including those that error before the child exits.
- *
  * @returns {number}
  */
 export function getSpawnCount() {
   return _spawnCount;
 }
 
-/**
- * Reset the spawn counter to zero. Test seam — production code never
- * calls this. Tests that exercise the counter MUST reset it in
- * `beforeEach` so test order doesn't bleed across cases.
- */
 export function resetSpawnCount() {
   _spawnCount = 0;
 }
 
-/**
- * Base class for all gh-exec errors. Carries the args that were passed to
- * `gh`, the captured stdout/stderr, and the process exit code (or null when
- * the process never produced one — e.g. timeout, spawn error).
- */
+/** `code` is null when the process never produced one. */
 export class GhExecError extends Error {
   constructor(message, { args, stdout = '', stderr = '', code = null } = {}) {
     super(message);
@@ -80,11 +30,6 @@ export class GhExecError extends Error {
   }
 }
 
-/**
- * Raised when the child process is killed by the `timeout` option before it
- * exits on its own. Distinct from `GhExecError` so callers (retry loops,
- * watchdog code) can match on `instanceof GhExecTimeoutError`.
- */
 export class GhExecTimeoutError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -93,12 +38,6 @@ export class GhExecTimeoutError extends GhExecError {
   }
 }
 
-/**
- * `gh` is not on PATH (ENOENT on spawn, or stderr literally contains the
- * "command not found" / "is not recognized" phrasing for Windows). Callers
- * (`agents-bootstrap-github`) treat this as a hard preflight failure and
- * print install instructions.
- */
 export class GhNotInstalledError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -106,7 +45,6 @@ export class GhNotInstalledError extends GhExecError {
   }
 }
 
-/** `gh auth login` has not been run (or the token expired). */
 export class GhAuthError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -114,10 +52,7 @@ export class GhAuthError extends GhExecError {
   }
 }
 
-/**
- * Hit a primary or secondary rate limit. Distinct from auth so caller retry
- * loops can back off rather than re-prompt for credentials.
- */
+/** Primary or secondary rate limit — callers back off, not re-auth. */
 export class GhRateLimitError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -125,7 +60,6 @@ export class GhRateLimitError extends GhExecError {
   }
 }
 
-/** Resource (issue, PR, repo, branch) does not exist or is not visible. */
 export class GhNotFoundError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -133,11 +67,6 @@ export class GhNotFoundError extends GhExecError {
   }
 }
 
-/**
- * The authenticated user is authenticated but missing a required scope (e.g.
- * `project` for Projects V2). `gh auth refresh -s <scope>` is the canonical
- * recovery.
- */
 export class GhScopeError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -145,12 +74,6 @@ export class GhScopeError extends GhExecError {
   }
 }
 
-/**
- * GraphQL endpoint returned `errors[]` (most commonly emitted by
- * `gh api graphql`). The stderr carries the rendered error string; we
- * surface it as-is so callers can pattern-match on the specific GraphQL
- * failure if they care.
- */
 export class GhGraphqlError extends GhExecError {
   constructor(message, details = {}) {
     super(message, details);
@@ -159,23 +82,11 @@ export class GhGraphqlError extends GhExecError {
 }
 
 /**
- * Render a `gh` failure as one operator-legible line: the error message plus
- * the reason `gh` itself printed.
- *
- * Every `GhExecError` carries the captured `stderr`, but the classified
- * message keeps only the exit status — so a caller that logs `err.message`
- * alone flattens every unclassified failure to `gh-exec: gh exited with code
- * 1`. That is exactly what hid an HTTP 422 `description is too long` behind
- * three identical "label ensure failed" warnings (Story #5201). `gh` prints
- * the actionable sentence on the *last* stderr line — the leading lines are
- * the `HTTP 422:` banner and the API URL — so that line is what is appended.
- *
- * Non-`GhExecError` inputs (a plain `Error` from a provider fake, a thrown
- * string) degrade to their own message, so this is safe on any catch path.
+ * Message plus the last stderr line — where `gh` prints the actionable
+ * reason, which the classified message omits.
  *
  * @param {unknown} err
- * @returns {string} `"<message>: <gh stderr detail>"`, or just the message
- *   when no stderr was captured.
+ * @returns {string}
  */
 export function describeGhFailure(err) {
   const message = String(err?.message ?? err ?? 'unknown error');
@@ -188,44 +99,22 @@ export function describeGhFailure(err) {
 }
 
 /**
- * Classify a non-zero `gh` invocation into the most specific typed error
- * subclass available. Pure function — no side effects, no I/O.
- *
- * Pattern table (order-sensitive: more specific patterns first):
- *
- *   spawnError.code === 'ENOENT'  → GhNotInstalledError
- *   /command not found|not recognized/i (no spawnError) → GhNotInstalledError
- *   /requires authentication|auth (login|status)/i      → GhAuthError
- *   /rate limit|secondary rate limit|API rate limit/i   → GhRateLimitError
- *   /missing.*scope|requires the .* scope/i             → GhScopeError
- *   /HTTP 404|not found|could not resolve/i             → GhNotFoundError
- *   /GraphQL: |graphql.*error/i                         → GhGraphqlError
- *   anything else                                       → GhExecError
- *
  * @param {object} ctx
  * @param {string} [ctx.stderr]
  * @param {number|null} [ctx.code]
  * @param {string[]} [ctx.args]
  * @param {string} [ctx.stdout]
  * @param {Error}  [ctx.spawnError]
- *   Raw error thrown by `spawn` (e.g. ENOENT). Passed through so the auth
- *   path can distinguish "missing binary" from "binary present, said no".
  * @returns {GhExecError}
  */
 /**
- * Ordered rule table for `classify`. The first row whose `test(haystack)`
- * is truthy wins. Pulling these out of the function body collapses
- * `classify` from a giant if/else chain (cc ≈ 4 with many condition
- * literals → CRAP 22) to a simple find-then-construct (cc = 2).
+ * First match wins.
  *
  * @type {Array<{
  *   test: (h: string) => boolean,
  *   build: (details: object) => Error,
  * }>}
  */
-// Per-category combined regexes. Alternation keeps each pattern at cc=1
-// (regex literals don't carry control-flow weight) so `classify`'s
-// dispatch loop stays well under the CRAP=20 ceiling for the file.
 const CLASSIFY_RULES = [
   {
     pattern:
@@ -289,8 +178,7 @@ export function classify({
   const spawnVerdict = classifySpawnError(spawnError, details);
   if (spawnVerdict) return spawnVerdict;
   const haystack = `${stderr}`.toLowerCase();
-  // If spawnError is present we skip the not-installed text heuristics so
-  // callers can distinguish "binary missing" from "binary present, refused".
+  // With a spawnError, skip the not-installed text rule.
   const startIdx = spawnError ? 1 : 0;
   for (let i = startIdx; i < CLASSIFY_RULES.length; i += 1) {
     if (CLASSIFY_RULES[i].pattern.test(haystack))
@@ -300,24 +188,13 @@ export function classify({
 }
 
 /**
- * Spawn `gh` with the given args. Returns a Promise.
- *
  * @param {object} opts
  * @param {string[]} opts.args
- *   Positional + flag arguments to pass to `gh`. Must be an array — string
- *   command lines are rejected so callers cannot accidentally invite shell
- *   interpolation.
  * @param {string} [opts.input]
- *   Optional stdin payload. Written to the child once and then closed.
  * @param {number} [opts.timeoutMs]
- *   Optional wall-clock timeout. When the child is killed by this timeout
- *   the returned Promise rejects with `GhExecTimeoutError`.
  * @param {Function} [opts.spawnImpl]
- *   Test seam — defaults to `child_process.spawn`. Tests inject a fake that
- *   returns an `EventEmitter`-shaped object.
  * @returns {Promise<object|{stdout:string,stderr:string,code:number}>}
- *   When `args` contains `--json`, resolves to the parsed JSON value.
- *   Otherwise resolves to `{ stdout, stderr, code }`.
+ *   Parsed JSON when `args` contains `--json`, else the raw envelope.
  */
 export function exec({
   args,
@@ -344,10 +221,7 @@ export function exec({
   return new Promise((resolve, reject) => {
     let child;
     try {
-      // Throw-away spawn-count instrumentation (Story #1795). Counted
-      // before the spawnImpl call so an immediate-throw spawnError still
-      // reflects in the total — the measurement we care about is "did we
-      // attempt to launch gh", not "did gh exit cleanly".
+      // Counted before the call so an immediate-throw spawn still counts.
       _spawnCount += 1;
       child = spawnImpl('gh', args, spawnOpts);
     } catch (err) {
@@ -420,47 +294,22 @@ export function exec({
   });
 }
 
-/* ---------------------------------------------------------------------- */
-/* Typed convenience wrappers (Task #1370)                                 */
-/* ---------------------------------------------------------------------- */
-
 /**
- * Build a typed `gh` facade bound to a specific `exec` implementation. The
- * factory exists so tests can inject a fake `exec` (which itself wraps a fake
- * `spawn`) and assert the argv shape each wrapper produces. Production code
- * just imports the pre-bound `gh` singleton.
- *
- * The wrappers are deliberately thin: each one builds the argv array,
- * delegates to `exec`, and returns the parsed result. The only logic worth
- * naming lives in `gh.api`, which translates the structured
- * `{ method, endpoint, body, fields, paginate }` shape into the right
- * `-X / -f / --paginate / --input -` flag combination.
+ * Typed `gh` facade over an `exec` implementation (tests inject a fake).
  *
- * @param {Function} execImpl — exec implementation. Defaults to module exec.
- * @param {object} [defaultExecOpts] — Default exec options spread into every
- *   wrapper's invocation (e.g. `{ timeoutMs: 60_000 }`). Per-call options
- *   override the defaults via spread order. Story #2860.
+ * @param {Function} execImpl
+ * @param {object} [defaultExecOpts] — per-call options win.
  */
 export function createGh(execImpl = exec, defaultExecOpts = {}) {
-  // Wrap execImpl so every wrapper inherits defaultExecOpts (e.g. timeoutMs)
-  // without having to thread the option through each callsite. Per-call opts
-  // win because they spread after the defaults. Story #2860.
   const execWithDefaults = (opts) => execImpl({ ...defaultExecOpts, ...opts });
   /**
-   * `gh api` wrapper.
-   *
    * @param {object} opts
-   * @param {string} [opts.method='GET']  HTTP method (passed as -X <method>).
-   * @param {string} opts.endpoint        e.g. '/repos/{owner}/{repo}/issues'.
-   * @param {object} [opts.body]          JSON body — written to stdin via --input -.
-   * @param {string[]} [opts.fields]      For graphql-style --jq field projection;
-   *                                       passed as repeated --jq is not what callers
-   *                                       want, so we currently surface it as
-   *                                       `--jq .${fields.join(',.')}` only when
-   *                                       set. Most callers will leave it unset
-   *                                       and pass `endpoint` directly.
-   * @param {boolean} [opts.paginate]     Add --paginate for list endpoints.
-   * @param {object}  [opts.execOpts]     Forwarded to exec (timeoutMs, etc.).
+   * @param {string} [opts.method='GET']
+   * @param {string} opts.endpoint
+   * @param {object} [opts.body]          Written to stdin via --input -.
+   * @param {string[]} [opts.fields]      Projected as `--jq .a,.b`.
+   * @param {boolean} [opts.paginate]
+   * @param {object}  [opts.execOpts]
    */
   function api({
     method = 'GET',
@@ -488,19 +337,11 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
     return execWithDefaults({ args, input, ...execOpts });
   }
 
-  /**
-   * Build a `--json a,b,c` flag pair from a fields array. Returns `[]` when
-   * fields is unset so callers can spread without branching.
-   */
   function jsonFlag(fields) {
     if (!Array.isArray(fields) || fields.length === 0) return [];
     return ['--json', fields.join(',')];
   }
 
-  /**
-   * Coerce numeric ids to strings — gh accepts both but tests assert on
-   * stringly args.
-   */
   function idStr(id) {
     return typeof id === 'number' ? String(id) : id;
   }
@@ -534,12 +375,7 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
       execWithDefaults({ args: ['pr', 'edit', idStr(id), ...flags] }),
     merge: (id, flags = []) =>
       execWithDefaults({ args: ['pr', 'merge', idStr(id), ...flags] }),
-    /**
-     * Bring a `mergeStateStatus: BEHIND` PR up to date with its base
-     * (Story #4543). The close-and-land merge wait calls this a bounded
-     * number of times rather than waiting out its budget behind a base it
-     * could have caught up to.
-     */
+    /** Bring a `mergeStateStatus: BEHIND` PR up to date with its base. */
     updateBranch: (id, flags = []) =>
       execWithDefaults({ args: ['pr', 'update-branch', idStr(id), ...flags] }),
     list: (flags = [], fields) =>
@@ -574,31 +410,15 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
     },
   };
 
-  // Expose the resolved defaults so callers (and tests) can introspect what
-  // ceiling the facade enforces. Frozen to discourage post-construction
-  // mutation. Story #2860.
   const defaults = Object.freeze({ ...defaultExecOpts });
   return { api, issue, pr, label, repo, defaults };
 }
 
-/**
- * Module-level singleton bound to the real `exec`. Production callers
- * import this; tests reach for `createGh(fakeExec)` instead.
- */
 export const gh = createGh();
 
-/* ---------------------------------------------------------------------- */
-/* GraphQL reachability preflight (Story #5355)                            */
-/* ---------------------------------------------------------------------- */
-
 /**
- * The `gh pr` subcommands the facade above reaches GitHub's pull-request
- * surface through. `gh` routes **every one of them** through GitHub's
- * GraphQL API, so they stand or fall together: where GraphQL answers HTTP
- * 403 there is no PR operation left to attempt, not a degraded subset.
- *
- * Kept beside the `pr` facade it enumerates, and module-private, so the
- * refusal text below cannot drift from the surface it claims to describe.
+ * `gh` routes every one of these through GraphQL, so a GraphQL 403 gates the
+ * whole PR surface. Kept beside `pr` so the refusal text cannot drift.
  */
 const GH_PR_SUBCOMMANDS = Object.freeze([
   'view',
@@ -609,39 +429,17 @@ const GH_PR_SUBCOMMANDS = Object.freeze([
   'list',
 ]);
 
-/**
- * The cheapest authenticated GraphQL read there is — "who am I". It touches
- * no repository, needs no scope beyond the one `gh` already has, and costs a
- * single API read, which is the whole budget the preflight is allowed.
- */
+/** Cheapest authenticated GraphQL read: no repo, no extra scope. */
 const GRAPHQL_PROBE_QUERY = 'query{viewer{login}}';
 
-/** Wall-clock ceiling for the probe. A hung probe must never hold a close. */
 const GRAPHQL_PROBE_TIMEOUT_MS = 15_000;
 
 /**
- * Classify a failed probe into one of the two refusing verdicts, or back to
- * `available` when the failure says nothing about GraphQL reachability.
- *
- * The fall-through is deliberate and it is **fail-open**: a timeout, a DNS
- * blip or a novel `gh` error is not evidence that this session cannot reach
- * GraphQL, and blocking a healthy close on an ambiguous probe would trade a
- * rare late failure for a common early one. Such a probe reports `available`
- * with `reason: 'probe-inconclusive'`, so the log still shows it happened.
- *
- * A **rate limit is that same fail-open case wearing a 403** (Story #5362).
- * GitHub answers both its primary and its secondary rate limits with HTTP
- * 403, and a throttled session says nothing about whether GraphQL is
- * reachable from here — so the rate-limit test runs *before* the bare status
- * match, and it accepts either shape the evidence arrives in: the typed
- * {@link GhRateLimitError} the shared classifier already produces, or
- * rate-limit text riding on an otherwise untyped 403. Classifying it
- * `unavailable` would block the Story behind a remedy that cannot work —
- * "re-run from a local session" is an instruction to go reproduce the same
- * throttle. A 403 with no rate-limit evidence is still the web-session shape
- * this preflight was built for and still refuses.
+ * Fail-open: an ambiguous error reports `available`. A rate limit also
+ * arrives as a 403 but says nothing about reachability, so it is matched
+ * before the bare 403.
  *
- * @param {unknown} err The rejection `gh.api` produced.
+ * @param {unknown} err
  * @returns {{ verdict: 'available'|'unavailable'|'auth-failed', reason: string }}
  */
 function classifyGraphqlProbeFailure(err) {
@@ -663,29 +461,11 @@ function classifyGraphqlProbeFailure(err) {
 }
 
 /**
- * Probe whether GitHub's GraphQL API is reachable from this session.
- *
- * One `gh api graphql` read, three verdicts:
- *
- *   - `available`    — GraphQL answered (or the probe failed in a way that
- *                      says nothing about reachability — an ambiguous error
- *                      or a rate limit; see the fail-open note on
- *                      {@link classifyGraphqlProbeFailure}).
- *   - `unavailable`  — GraphQL answered HTTP 403. This is the Claude Code
- *                      web-session shape: the token is fine, the endpoint
- *                      is simply not reachable from here, so the entire
- *                      `gh pr` surface is gated.
- *   - `auth-failed`  — `gh` has no usable token (missing, expired or
- *                      under-scoped). A different fault with a different
- *                      remedy, deliberately NOT flattened into the one
- *                      above: telling an unauthenticated operator to "run
- *                      this somewhere else" sends them to reproduce it.
- *
- * Never throws — a preflight that can fail a close is worse than no
- * preflight at all.
+ * Is GraphQL reachable from this session? `unavailable` is the web-session
+ * 403 shape; `auth-failed` has a different remedy and is kept distinct.
+ * Never throws.
  *
  * @param {{ ghFacade?: { api: Function } }} [opts]
- *   `ghFacade` is the injection seam; production passes nothing.
  * @returns {Promise<{ verdict: string, available: boolean, reason: string,
  *   detail: string|null }>}
  */
@@ -715,14 +495,6 @@ export async function probeGraphqlAvailability({ ghFacade = gh } = {}) {
 }
 
 /**
- * Render a refusing probe verdict as the operator-facing blocker.
- *
- * The two refusals get two messages because they have two remedies. The
- * unavailable text names all three things the operator needs — that GraphQL
- * is unavailable *in this session*, the whole `gh pr` surface that gates, and
- * that the fix is to run the close from a local session rather than to retry
- * here.
- *
  * @param {{ verdict?: string, detail?: string|null }} probe
  * @returns {string}
  */

package/.agents/scripts/lib/git/cached-fetch.js

@@ -1,38 +1,14 @@
 /**
- * cached-fetch.js — coalesce redundant `git fetch origin <ref>` calls.
- *
- * A single dispatch wave runs multiple Story inits in parallel; each one
- * fetches the same epic ref before creating its worktree. The fetches are
- * idempotent w.r.t. the local refs but cost wall-clock and contend on
- * `packed-refs.lock`. This module caches successful fetches by
- * `(cwd, ref)` for a configurable window (default 30s) so subsequent
- * callers within the window are no-ops.
- *
- * Two wrappers are exported because callers in the codebase split along a
- * sync/async line:
- *   - `cachedGitFetch` — async, wraps `gitFetchWithRetry` (used by
- *     story-init's `bootstrapWorktree`).
- *   - `cachedGitFetchSync` — sync, wraps a `gitSpawn(cwd, 'fetch', ref)`
- *     style call (used by `projectMaintainabilityRegressions` in
- *     close-validation).
- *
- * Both share the same underlying cache state, so a fetch issued by
- * story-init satisfies a later sync caller (and vice versa) inside the
- * window.
- *
- * The cache lives at module scope — invocations within one Node process
- * (one wave-runner) see the same state. Callers that need an isolated
- * cache (mostly tests) can construct a `FetchCache` directly.
+ * cached-fetch.js — coalesce redundant `git fetch origin <ref>` calls (they
+ * contend on `packed-refs.lock`) by caching successes per `(cwd, ref)` for a
+ * window; the async and sync wrappers share one cache.
  */
 
 import { gitFetchWithRetry as defaultGitFetchWithRetry } from '../git-utils.js';
 
 const DEFAULT_WINDOW_MS = 30_000;
 
-/**
- * Pure-ish cache state keyed by `(cwd, ref)`. Exposed so tests can build
- * fresh instances without poking module globals.
- */
+/** Cache state keyed by `(cwd, ref)`; constructible for isolated tests. */
 export class FetchCache {
   constructor({ now = () => Date.now() } = {}) {
     /** @type {Map<string, number>} */
@@ -44,11 +20,6 @@ export class FetchCache {
     return `${cwd}\u0000${ref}`;
   }
 
-  /**
-   * Return true when a fetch for `(cwd, ref)` is needed because either no
-   * fetch has been recorded yet, or the recorded one is older than
-   * `windowMs`.
-   */
   shouldFetch(cwd, ref, windowMs = DEFAULT_WINDOW_MS) {
     const key = FetchCache._key(cwd, ref);
     const last = this._lastFetchAt.get(key);
@@ -56,17 +27,14 @@ export class FetchCache {
     return this._now() - last >= windowMs;
   }
 
-  /** Record that a fetch for `(cwd, ref)` just succeeded. */
   recordFetch(cwd, ref) {
     this._lastFetchAt.set(FetchCache._key(cwd, ref), this._now());
   }
 
-  /** Test seam: drop all cached entries. */
   reset() {
     this._lastFetchAt.clear();
   }
 
-  /** Diagnostics: number of cached `(cwd, ref)` entries. */
   size() {
     return this._lastFetchAt.size;
   }
@@ -74,28 +42,22 @@ export class FetchCache {
 
 const moduleCache = new FetchCache();
 
-/**
- * Reset the module-level cache. Test-only — production code should never
- * call this.
- */
+/** Test-only. */
 export function __resetModuleCache() {
   moduleCache.reset();
 }
 
-/** Test helper: expose module cache size. */
+/** Test-only. */
 export function __moduleCacheSize() {
   return moduleCache.size();
 }
 
 /**
- * Async fetch with `(cwd, ref, windowMs)` caching.
- *
  * @param {string} cwd
- * @param {string} ref  The single ref argument passed to `git fetch origin`.
- *                      Pass `'origin'` (no second arg) by using ref=''.
+ * @param {string} ref  `''` fetches without a ref.
  * @param {object} [opts]
  * @param {number} [opts.windowMs=30000]
- * @param {FetchCache} [opts.cache]            Override the module cache.
+ * @param {FetchCache} [opts.cache]
  * @param {typeof defaultGitFetchWithRetry} [opts.fetchFn]
  * @returns {Promise<{ status: 0, cached: true, attempts: 0 } | { status: number, stdout: string, stderr: string, attempts: number, cached: false }>}
  */
@@ -120,13 +82,8 @@ export async function cachedGitFetch(
 }
 
 /**
- * Sync fetch with `(cwd, ref, windowMs)` caching. Wraps a `gitSpawn`-style
- * synchronous fetch (used by `close-validation`'s MI projection helper,
- * which must stay synchronous).
- *
  * @param {string} cwd
- * @param {string} ref  Required for sync callers — the projection helper
- *                      always passes an explicit epic branch ref.
+ * @param {string} ref
  * @param {object} opts
  * @param {(cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }} opts.gitSpawn
  * @param {number} [opts.windowMs=30000]