mandrel 1.57.0

package/.agents/scripts/lib/story-init/donor-precheck.js

@@ -0,0 +1,207 @@
+/**
+ * donor-precheck.js — verify the symlink-strategy donor is primed.
+ *
+ * When `delivery.worktreeIsolation.nodeModulesStrategy === 'symlink'`, every
+ * Story worktree junctions/symlinks its `node_modules/` from a donor (the
+ * `primeFromPath` directory, typically the repo root). If the donor lacks
+ * `node_modules/` the symlink will resolve to nothing and the worktree
+ * cannot install or run tests. This module runs once, just before
+ * `applyNodeModulesStrategy`, to make sure the donor is primed.
+ *
+ * The pre-check is idempotent across concurrent wave dispatches via a
+ * filesystem lock directory at `<donor>/.agents-donor-precheck.lock`. The
+ * first arrival creates the lock atomically (`fs.mkdirSync`), runs
+ * `npm ci`, and removes the lock. Concurrent callers either skip
+ * (donor already primed) or wait for the lock to clear and re-check
+ * existence — they do not double-run the installer.
+ *
+ * The helpers are split so the pure decision logic (`planDonorAction`) is
+ * trivially testable without filesystem or child-process side-effects.
+ */
+
+import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
+import nodePath from 'node:path';
+
+const LOCK_DIRNAME = '.agents-donor-precheck.lock';
+const LOCK_POLL_INTERVAL_MS = 100;
+const LOCK_WAIT_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * Pure: decide whether the donor needs a one-shot install.
+ *
+ * Returns one of:
+ *   - `{ action: 'skip', reason }` — strategy is not symlink, or donor
+ *     already has node_modules.
+ *   - `{ action: 'install', donorPath }` — caller should run install at
+ *     `donorPath`.
+ *
+ * @param {object} opts
+ * @param {string} opts.strategy         The configured `nodeModulesStrategy`.
+ * @param {string|null} opts.primeFromPath  Relative donor path.
+ * @param {string} opts.repoRoot         Absolute repo root.
+ * @param {{ existsSync: (p: string) => boolean }} [opts.fs]
+ *   Filesystem facade for tests.
+ * @returns {{ action: 'skip', reason: string } | { action: 'install', donorPath: string }}
+ */
+export function planDonorAction({
+  strategy,
+  primeFromPath,
+  repoRoot,
+  fs = nodeFs,
+  path = nodePath,
+}) {
+  if (strategy !== 'symlink') {
+    return { action: 'skip', reason: 'strategy-not-symlink' };
+  }
+  if (!primeFromPath) {
+    return { action: 'skip', reason: 'no-prime-from-path' };
+  }
+  const donorPath = path.resolve(repoRoot, primeFromPath);
+  if (fs.existsSync(path.join(donorPath, 'node_modules'))) {
+    return { action: 'skip', reason: 'donor-already-primed' };
+  }
+  return { action: 'install', donorPath };
+}
+
+/**
+ * Wait for the donor lock directory to be removed by the lock holder.
+ * Returns true if the lock cleared in time, false on timeout.
+ *
+ * Exported for tests.
+ */
+export function waitForLockClear({
+  lockPath,
+  fs = nodeFs,
+  pollIntervalMs = LOCK_POLL_INTERVAL_MS,
+  timeoutMs = LOCK_WAIT_TIMEOUT_MS,
+  now = () => Date.now(),
+  sleepFn,
+}) {
+  const start = now();
+  const sleep =
+    sleepFn ??
+    ((ms) => {
+      const signal = new Int32Array(new SharedArrayBuffer(4));
+      Atomics.wait(signal, 0, 0, ms);
+    });
+  while (fs.existsSync(lockPath)) {
+    if (now() - start >= timeoutMs) return false;
+    sleep(pollIntervalMs);
+  }
+  return true;
+}
+
+/**
+ * Ensure the symlink-strategy donor is primed. Runs at most once per
+ * dispatch wave because the lock directory is created atomically with
+ * `fs.mkdirSync` (EEXIST = another concurrent process already won).
+ *
+ * Behaviour by lock outcome:
+ *   - Lock acquired → run `npm ci`, then remove the lock.
+ *   - Lock contended → wait for the lock to clear, then re-check
+ *     existence. If `node_modules` is now present, skip; otherwise,
+ *     surface an error (the lock holder failed and the caller cannot
+ *     safely proceed).
+ *
+ * @param {object} opts
+ * @param {string} opts.strategy
+ * @param {string|null} opts.primeFromPath
+ * @param {string} opts.repoRoot
+ * @param {{ progress?: (kind: string, msg: string) => void }} [opts.logger]
+ * @param {{ existsSync: typeof nodeFs.existsSync, mkdirSync: typeof nodeFs.mkdirSync, rmSync: typeof nodeFs.rmSync }} [opts.fs]
+ * @param {typeof spawnSync} [opts.spawnFn]   Injected installer for tests.
+ * @param {(opts: object) => boolean} [opts.waitFn]  Injected lock waiter.
+ * @returns {{ action: 'skip' | 'installed' | 'waited', reason?: string, donorPath?: string, durationMs?: number }}
+ */
+export function ensureDonorPrimed({
+  strategy,
+  primeFromPath,
+  repoRoot,
+  logger,
+  fs = nodeFs,
+  path = nodePath,
+  spawnFn = spawnSync,
+  waitFn = waitForLockClear,
+  now = () => Date.now(),
+}) {
+  const t0 = now();
+  const progress = logger?.progress ?? (() => {});
+  const plan = planDonorAction({ strategy, primeFromPath, repoRoot, fs, path });
+  if (plan.action === 'skip') {
+    return { action: 'skip', reason: plan.reason, durationMs: now() - t0 };
+  }
+
+  const { donorPath } = plan;
+  const lockPath = path.join(donorPath, LOCK_DIRNAME);
+  let lockAcquired = false;
+  try {
+    fs.mkdirSync(lockPath);
+    lockAcquired = true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+
+  if (!lockAcquired) {
+    progress('DONOR-PRECHECK', `donor=${donorPath} lock contended, waiting...`);
+    const cleared = waitFn({ lockPath, fs });
+    if (!cleared) {
+      throw new Error(
+        `donor-precheck: timed out waiting for lock ${lockPath} to clear after ${LOCK_WAIT_TIMEOUT_MS}ms`,
+      );
+    }
+    if (!fs.existsSync(path.join(donorPath, 'node_modules'))) {
+      throw new Error(
+        `donor-precheck: lock holder released ${lockPath} without priming node_modules at ${donorPath}`,
+      );
+    }
+    progress(
+      'DONOR-PRECHECK',
+      `donor=${donorPath} primed by concurrent dispatch, proceeding.`,
+    );
+    return { action: 'waited', donorPath, durationMs: now() - t0 };
+  }
+
+  try {
+    // Re-check between mkdir and install: another process could have run
+    // and finished while we were racing on mkdirSync.
+    if (fs.existsSync(path.join(donorPath, 'node_modules'))) {
+      progress(
+        'DONOR-PRECHECK',
+        `donor=${donorPath} already primed (post-lock recheck), skipping install.`,
+      );
+      return {
+        action: 'skip',
+        reason: 'donor-primed-post-lock',
+        donorPath,
+        durationMs: now() - t0,
+      };
+    }
+    progress(
+      'DONOR-PRECHECK',
+      `donor=${donorPath} missing node_modules — running one-shot npm ci...`,
+    );
+    const result = spawnFn('npm', ['ci'], {
+      cwd: donorPath,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      timeout: 10 * 60_000,
+    });
+    if (result.status !== 0) {
+      throw new Error(
+        `donor-precheck: 'npm ci' at ${donorPath} exited with status ${result.status}`,
+      );
+    }
+    progress('DONOR-PRECHECK', `donor=${donorPath} primed in ${now() - t0}ms.`);
+    return { action: 'installed', donorPath, durationMs: now() - t0 };
+  } finally {
+    try {
+      fs.rmSync(lockPath, { recursive: true, force: true });
+    } catch (_err) {
+      // Best-effort lock release; subsequent runs will recover by
+      // re-checking node_modules existence.
+    }
+  }
+}
+
+export const __LOCK_DIRNAME = LOCK_DIRNAME;

package/.agents/scripts/lib/story-init/hierarchy-tracer.js

@@ -0,0 +1,36 @@
+import { Logger } from '../Logger.js';
+/**
+ * hierarchy-tracer.js — Stage 2 of the story-init pipeline.
+ *
+ * Given an epicId, resolves the linked PRD and Tech Spec issue IDs by
+ * fetching the Epic. Fetch failures are logged but non-fatal — the result
+ * simply reports `null` for whichever linkage could not be resolved, which
+ * mirrors legacy behaviour in story-init.js.
+ */
+
+/**
+ * @param {object} deps
+ * @param {object} deps.provider
+ * @param {object} [deps.logger]
+ * @param {object} deps.input
+ * @param {number} deps.input.epicId
+ * @returns {Promise<{ prdId: number|null, techSpecId: number|null }>}
+ */
+export async function traceHierarchy({ provider, logger, input }) {
+  const { epicId } = input;
+  const warn = logger?.warn ?? ((msg) => Logger.error(msg));
+
+  let prdId = null;
+  let techSpecId = null;
+  try {
+    const epic = await provider.getEpic(epicId);
+    prdId = epic.linkedIssues?.prd ?? null;
+    techSpecId = epic.linkedIssues?.techSpec ?? null;
+  } catch (err) {
+    warn(
+      `[story-init] Warning: Could not fetch Epic #${epicId}: ${err.message}`,
+    );
+  }
+
+  return { prdId, techSpecId };
+}

package/.agents/scripts/lib/story-init/state-transitioner.js

@@ -0,0 +1,80 @@
+/**
+ * state-transitioner.js — Stage 6 of the story-init pipeline.
+ *
+ * Flips the Story ticket to `agent::executing` at init time. Under the
+ * 3-tier hierarchy the Story has inline acceptance and no child Task
+ * lifecycle — `/story-deliver` runs a single Story-implementation phase.
+ */
+
+import {
+  STATE_LABELS,
+  transitionTicketState,
+} from '../orchestration/ticketing.js';
+import { batchTransitionTickets } from '../story-lifecycle.js';
+
+/**
+ * Flip the Story to `agent::executing` and cascade upward (Epic / Feature).
+ *
+ * @param {object} deps
+ * @param {object} deps.provider
+ * @param {object} [deps.logger]
+ * @param {object} deps.input
+ * @param {number} deps.input.storyId
+ * @param {object} deps.input.story - Prefetched Story ticket (`ticketSnapshot`).
+ * @param {Function|null} [deps.input.notify]
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function transitionStoryToExecuting({ provider, logger, input }) {
+  const { storyId, story, notify = null } = input;
+  const progress = logger?.progress ?? (() => {});
+
+  progress('TICKETS', `Transitioning Story #${storyId} to agent::executing...`);
+  await transitionTicketState(provider, storyId, STATE_LABELS.EXECUTING, {
+    ticketSnapshot: story,
+    cascade: true,
+    notify,
+  });
+
+  return { ok: true };
+}
+
+/**
+ * Batch-transitions every child Task to a target label. Retained for
+ * `batchTransitionTickets` unit coverage and post-merge batch closes;
+ * story-init no longer calls this at startup.
+ *
+ * @param {object} deps
+ * @param {object} deps.provider
+ * @param {object} [deps.logger]
+ * @param {object} deps.input
+ * @param {Array<object>} deps.input.tasks
+ * @param {Function|null} [deps.input.notify]
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   failed: Array<{id:number,attempts:number,error:string}>,
+ *   transitioned: number[],
+ *   skipped: number[],
+ * }>}
+ */
+export async function transitionTaskStates({ provider, logger, input }) {
+  const { tasks, notify = null } = input;
+  const progress = logger?.progress ?? (() => {});
+
+  progress(
+    'TICKETS',
+    `Transitioning ${tasks.length} Task(s) to agent::executing...`,
+  );
+  const transitionResult = await batchTransitionTickets(
+    provider,
+    tasks,
+    STATE_LABELS.EXECUTING,
+    { progress, notify },
+  );
+
+  return {
+    ok: transitionResult.failed.length === 0,
+    failed: transitionResult.failed,
+    transitioned: transitionResult.transitioned,
+    skipped: transitionResult.skipped,
+  };
+}

package/.agents/scripts/lib/story-init/task-graph-builder.js

@@ -0,0 +1,114 @@
+/**
+ * task-graph-builder.js — Stage 4 of the story-init pipeline.
+ *
+ * Enumerates child Tasks of the Story, then topologically sorts them using
+ * `blocked by` edges that reference other Tasks in the same set. Inter-Task
+ * dependencies outside the child set are ignored (they are handled by the
+ * Story-level blocker validator).
+ */
+
+import { parseBlockedBy } from '../dependency-parser.js';
+import { buildGraph, detectCycle, topologicalSort } from '../Graph.js';
+import { Logger } from '../Logger.js';
+import { fetchChildTickets } from '../story-lifecycle.js';
+
+/**
+ * Detect whether a Story body carries inline acceptance criteria, the
+ * structural signal that the Story is authored in the 3-tier
+ * (Story-with-inline-acceptance) shape and therefore should not be expected
+ * to enumerate child Task tickets. Recognises both `## Acceptance` and
+ * `## Acceptance Criteria` headings, with at least one list bullet under
+ * them (mirroring the heading set the manifest-builder extracts).
+ *
+ * @param {string} body
+ * @returns {boolean}
+ */
+export function hasInlineAcceptance(body) {
+  if (typeof body !== 'string' || body.length === 0) return false;
+  const headingRe = /^##\s+Acceptance(?:\s+Criteria)?\s*$/im;
+  const match = body.match(headingRe);
+  if (!match || match.index == null) return false;
+  const rest = body.slice(match.index + match[0].length);
+  const nextHeading = rest.search(/^##\s+/m);
+  const block = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  for (const rawLine of block.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (/^[-*]\s+(?:\[[ xX]\]\s+)?\S/.test(line)) return true;
+  }
+  return false;
+}
+
+function sortTasksByDependencies(tasks) {
+  if (tasks.length <= 1) return tasks;
+
+  const graphTasks = tasks.map((t) => ({
+    ...t,
+    dependsOn: parseBlockedBy(t.body ?? '').filter((dep) =>
+      tasks.some((tt) => tt.id === dep),
+    ),
+  }));
+  const { adjacency, taskMap } = buildGraph(graphTasks);
+
+  const cycle = detectCycle(adjacency);
+  if (cycle) {
+    throw new Error(
+      `[story-init] Dependency cycle detected among child tasks: ` +
+        `#${cycle.join(' → #')}. Fix the \`blocked by\` references before retrying.`,
+    );
+  }
+
+  return topologicalSort(adjacency, taskMap);
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.provider
+ * @param {object} [deps.logger]
+ * @param {object} deps.input
+ * @param {number} deps.input.storyId
+ * @param {string} [deps.input.storyBody]   Story body — used to detect
+ *   whether the Story carries inline acceptance (3-tier shape) so the
+ *   empty-Task-list path is treated as expected rather than as a warning.
+ *
+ * Task #3154 (Epic #3078) deleted the `planning.hierarchy` flag; the
+ * 3-tier vs 4-tier mode is now derived entirely from the ticket shape —
+ * inline acceptance + zero Tasks resolves to `'3-tier'`, otherwise
+ * `'4-tier'`.
+ *
+ * @returns {Promise<{ sortedTasks: Array<object>, mode: '3-tier'|'4-tier' }>}
+ */
+export async function buildTaskGraph({ provider, logger, input }) {
+  const { storyId, storyBody = '' } = input;
+  const warn = logger?.warn ?? ((msg) => Logger.error(msg));
+  const progress = logger?.progress ?? (() => {});
+
+  const tasks = await fetchChildTickets(provider, storyId);
+
+  const inlineAcceptance = hasInlineAcceptance(storyBody);
+  const mode = tasks.length === 0 && inlineAcceptance ? '3-tier' : '4-tier';
+
+  if (tasks.length === 0) {
+    if (inlineAcceptance) {
+      progress(
+        'TASKS',
+        `Story #${storyId} has inline acceptance — no child Tasks expected (3-tier shape).`,
+      );
+    } else {
+      warn(
+        `[story-init] Warning: Story #${storyId} has no child Tasks. The agent will need to work from the Story body directly.`,
+      );
+    }
+  }
+
+  const sortedTasks = sortTasksByDependencies(tasks);
+  if (sortedTasks.length > 0) {
+    progress(
+      'TASKS',
+      `Found ${sortedTasks.length} child Task(s) in dependency order`,
+    );
+  }
+
+  return { sortedTasks, mode };
+}
+
+export { sortTasksByDependencies };

package/.agents/scripts/lib/story-init/transition-summary.js

@@ -0,0 +1,34 @@
+/**
+ * transition-summary.js — Story-level summary of the batched task-start
+ * fanout produced by `transitionTaskStates`.
+ *
+ * Replaces the previous N-per-Task `agent::executing` GitHub-comment fanout
+ * with a single `low` notification routed to the Story. The dispatch
+ * carries no `event` field, so under the curated `commentEvents` /
+ * `webhookEvents` allowlists it never reaches either channel — init stays
+ * silent on the GitHub timeline by default. The call remains as a sentinel
+ * for operators who curate a `story-task-summary` event into their
+ * `commentEvents` allowlist (out-of-tree extension).
+ */
+
+/**
+ * @param {object} deps
+ * @param {Function|null} deps.notify - The standard `notify(ticketId, payload)` hook.
+ * @param {number} deps.storyId
+ * @param {number[]} deps.transitioned - IDs of Tasks that flipped to `agent::executing`.
+ * @returns {Promise<{posted: boolean, message: string|null}>}
+ */
+export async function postBatchedTransitionSummary({
+  notify,
+  storyId,
+  transitioned,
+}) {
+  if (typeof notify !== 'function') return { posted: false, message: null };
+  if (!Array.isArray(transitioned) || transitioned.length === 0) {
+    return { posted: false, message: null };
+  }
+  const taskList = transitioned.map((id) => `#${id}`).join(', ');
+  const message = `Story #${storyId} · ${transitioned.length} Task(s) transitioned to \`agent::executing\`: ${taskList}`;
+  await notify(storyId, { severity: 'low', message });
+  return { posted: true, message };
+}

package/.agents/scripts/lib/story-lifecycle.js

@@ -0,0 +1,186 @@
+/**
+ * Story lifecycle helpers shared between story-init and story-close.
+ *
+ * These three pure/IO-helpers capture the overlap previously duplicated across
+ * the two CLI scripts — parsing the `Epic: #N` / `parent: #N` references out
+ * of a Story body, fetching child sub-tickets, and batch-transitioning
+ * tickets to a target state label.
+ *
+ * The shape is narrow on purpose: init/close still own their own orchestration
+ * (branch bootstrap, merge, cascade, notifications). Expanding this module to
+ * cover those would over-abstract — they are genuinely different concerns.
+ *
+ * Under the 3-tier hierarchy (Epic #3078) Stories have no child tickets, so
+ * `fetchChildTickets` typically returns `[]` — but the helper remains in
+ * place so legacy callers still resolve the Story's direct children cleanly.
+ */
+
+import { Logger } from './Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+} from './orchestration/ticketing.js';
+/**
+ * Parse the `Epic: #N` and `parent: #N` references from a Story body.
+ *
+ * @param {string} body  Raw Story body Markdown.
+ * @returns {{ epicId: number|null, featureId: number|null }}
+ */
+export function resolveStoryHierarchy(body) {
+  const source = body ?? '';
+  const epicMatch = source.match(/(?:^\s*epic:\s*#(\d+))/im);
+  const parentMatch = source.match(/(?:^\s*parent:\s*#(\d+))/im);
+  return {
+    epicId: epicMatch ? Number.parseInt(epicMatch[1], 10) : null,
+    featureId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
+  };
+}
+
+/**
+ * Fetch the Story's direct child tickets via the provider.
+ *
+ * Under the 3-tier hierarchy (Epic #3078) Stories no longer enumerate
+ * child Task tickets — acceptance criteria and verification steps live
+ * inline on the Story body, and decomposers emit only Epic / Feature /
+ * Story issues. For those Stories this helper resolves to an empty
+ * array because `provider.getSubTickets(storyId)` itself returns no
+ * rows. The helper is retained as a thin pass-through so the three
+ * orchestration callers (`story-deliver-prepare`, `task-graph-builder`,
+ * and `locked-pipeline`) keep a single, named seam for sub-ticket
+ * hydration that is easy to mock in tests and to instrument in the
+ * provider layer.
+ *
+ * Legacy ticket trees that were planned before the 3-tier cutover may
+ * still carry sub-tickets (PRD/Tech-Spec links recorded as direct
+ * children, for example). The helper deliberately does **not** filter
+ * those out — the caller is responsible for classifying anything that
+ * comes back. The previous `type::task`-only filter has been removed in
+ * Story #3191 because no current call site relies on that narrowing.
+ *
+ * @param {object} provider  ITicketingProvider instance.
+ * @param {number} storyId   Story ticket number to hydrate children for.
+ * @returns {Promise<object[]>} Array of child tickets (empty under 3-tier).
+ */
+export async function fetchChildTickets(provider, storyId) {
+  return provider.getSubTickets(storyId);
+}
+
+/**
+ * Detect transient HTTP errors (rate limits, gateways, server errors) that
+ * are worth retrying. Permission/validation errors are not retried — the
+ * second attempt would fail the same way.
+ *
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isRetryableError(err) {
+  const status = err?.status ?? err?.statusCode;
+  if (status === 429) return true;
+  if (typeof status === 'number' && status >= 500 && status < 600) return true;
+  const msg = (err?.message ?? '').toLowerCase();
+  return (
+    msg.includes('rate limit') ||
+    msg.includes('timeout') ||
+    msg.includes('econnreset') ||
+    msg.includes('etimedout') ||
+    msg.includes('socket hang up')
+  );
+}
+
+/**
+ * Batch-transition a set of tickets to the target state label. Tickets
+ * already carrying `STATE_LABELS.DONE` (or the target itself) are skipped.
+ * Each transition runs in parallel with a per-ticket retry budget for
+ * transient errors (429, 5xx, network). Permanent failures are recorded
+ * in `failed` without aborting the batch.
+ *
+ * @param {object} provider  ITicketingProvider instance.
+ * @param {object[]} tickets Array of ticket objects with `id` and `labels`.
+ * @param {string} targetLabel  Target `agent::...` label (e.g. STATE_LABELS.EXECUTING).
+ * @param {object} [opts]
+ * @param {(phase: string, message: string) => void} [opts.progress]  Progress reporter.
+ * @param {(ticketId: number, err: Error) => void}  [opts.onError]     Per-failure callback.
+ * @param {number} [opts.concurrency=10]    Max parallel ticket transitions.
+ * @param {number} [opts.retries=3]         Max attempts per ticket on transient errors.
+ * @param {number} [opts.retryBaseMs=500]   Base for exponential backoff (attempt * base).
+ * @param {Function} [opts.notify] Optional notify function — forwarded to
+ *   each `transitionTicketState` call so successful transitions fire a
+ *   state-transition notification.
+ * @returns {Promise<{ transitioned: number[], skipped: number[], failed: Array<{ id: number, error: string, attempts: number }> }>}
+ */
+export async function batchTransitionTickets(
+  provider,
+  tickets,
+  targetLabel,
+  opts = {},
+) {
+  const { progress, onError, notify } = opts;
+  const transitioned = [];
+  const skipped = [];
+  const failed = [];
+
+  const concurrency = opts.concurrency ?? 10;
+  const maxRetries = opts.retries ?? 3;
+  const retryBaseMs = opts.retryBaseMs ?? 500;
+
+  const processTicket = async (ticket) => {
+    if (ticket.labels.includes(targetLabel)) {
+      progress?.('TICKETS', `  #${ticket.id} already ${targetLabel} — skipped`);
+      skipped.push(ticket.id);
+      return;
+    }
+    if (
+      targetLabel !== STATE_LABELS.DONE &&
+      ticket.labels.includes(STATE_LABELS.DONE)
+    ) {
+      progress?.('TICKETS', `  #${ticket.id} already done — skipped`);
+      skipped.push(ticket.id);
+      return;
+    }
+    let lastErr;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        // Story #1795 — thread the already-hydrated ticket through
+        // `opts.ticketSnapshot` so `transitionTicketState` skips both
+        // round-trips (notify snapshot + label merge). `batchTransitionTickets`
+        // is the single hot caller of this seam — every wave-close passes
+        // its full task list through here.
+        await transitionTicketState(provider, ticket.id, targetLabel, {
+          notify,
+          ticketSnapshot: ticket,
+        });
+        progress?.(
+          'TICKETS',
+          `  #${ticket.id} → ${targetLabel} ✅${attempt > 1 ? ` (after ${attempt} attempts)` : ''}`,
+        );
+        transitioned.push(ticket.id);
+        return;
+      } catch (err) {
+        lastErr = err;
+        if (attempt >= maxRetries || !isRetryableError(err)) break;
+        const delay = retryBaseMs * 2 ** (attempt - 1);
+        progress?.(
+          'TICKETS',
+          `  #${ticket.id} transient error (${err.message}); retrying in ${delay}ms (${attempt}/${maxRetries - 1})`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    failed.push({
+      id: ticket.id,
+      error: lastErr?.message ?? String(lastErr),
+      attempts: maxRetries,
+    });
+    if (onError) onError(ticket.id, lastErr);
+    else
+      Logger.error(`  #${ticket.id} → FAILED: ${lastErr?.message ?? lastErr}`);
+  };
+
+  // Process in batches to avoid overwhelming the API with concurrent requests.
+  for (let i = 0; i < tickets.length; i += concurrency) {
+    const batch = tickets.slice(i, i + concurrency);
+    await Promise.all(batch.map(processTicket));
+  }
+
+  return { transitioned, skipped, failed };
+}