@hone-ai/cli 1.38.0 → 1.39.0

package/lib/batch-follow.js

@@ -17,9 +17,23 @@
  *  - It stops BEFORE acting when a breaker has fired. A terminal batch ends the loop after one last emit-pr pass.
  *  - It is idempotent across restarts: an attempt that already has a verify-patch verdict on the server is not
  *    verified again, and emit-pr's BRANCH_CONFLICT (5) means the branch was already emitted.
+ *  - HC-GF-351: it is never silent. A run paused at anything the loop cannot act on is named once, with its step
+ *    and the first line of why; when every unfinished run is waiting on a person the loop stops with NEEDS_YOU
+ *    instead of waiting out its deadline. And a run hard-paused for files it was not given is re-served ONCE: the
+ *    paused run is killed with a reason that names the new batch (the next start reads it back, which is what
+ *    makes the bound survive a restart), and its story is queued again as a one-story batch whose line carries
+ *    the files, which the loop then follows too. Only paths cli/lib/context-reserve.js lets through are served.
+ *    Killing a run FAILS every queued or paused run in its batch that lists it in `config.dependsOnRunIds`
+ *    (server/src/services/batch-deps.js cascadeOnFailure), so a run anything depends on is never re-served, and the
+ *    decision reads that list, not the dependents' waiting message, which names only one of their blockers.
  */
 
 const { classifyPollState, POLL_OUTCOMES } = require('./poll-decision');
+const { formatStoryLine } = require('./story-line');
+const { isGitRev, isStoryId } = require('./run-target');
+const {
+  reserveReason, reservedBatchOf, hardPauseRequest, judgeRequest, originalPathsOf, batchIdFromQueueOutput,
+} = require('./context-reserve');
 
 /** follow-batch's own exit codes. */
 const EXIT = Object.freeze({ DONE: 0, FATAL: 1, NEEDS_YOU: 2, DEADLINE: 3 });
@@ -91,7 +105,7 @@ function priorVerdict(run, attempt) {
  */
 function step4Action(run) {
   const c = classifyPollState(run);
-  // Not a step_4 gate: not this loop's business, and nothing to say about it.
+  // Not a step_4 gate: not this function's business. planTick asks otherPause who such a pause waits on (HC-GF-351).
   if (c.outcome !== POLL_OUTCOMES.HUMAN_GATE || c.stepKey !== 'step_4') return { actionable: false };
   const why = String((run && run.errorMessage) || '');
   if (NOT_A_GATE.test(why)) return { actionable: false, reason: `paused, not at a gate: ${firstLine(why)}` };
@@ -124,6 +138,20 @@ function buildArgs(verb, runId, { attempt, openPr = false, branch } = {}) {
   return args;
 }
 
+/**
+ * The argv that queues one story again (HC-GF-351). The file, repository and branch are values from outside this
+ * module, so they ride in `--flag=value` form: a value that starts with a dash cannot become an option. No flag
+ * here overrides a safety gate, and none is `--overnight` (the loop does not know the original batch's mode).
+ * @param {string} file  a stories file holding the one line
+ */
+function buildReserveArgs(file, { repoName, branch } = {}) {
+  const args = ['queue-stories', `--file=${file}`];
+  if (repoName) args.push(`--repo=${repoName}`);
+  if (branch && isGitRev(branch)) args.push(`--branch=${branch}`);
+  args.push('--format', 'json');
+  return args;
+}
+
 /** The step_4 attempt a run is on now: the highest step_4 attempt in its steps, or null. */
 function currentStep4Attempt(run) {
   const steps = Array.isArray(run && run.steps) ? run.steps : [];
@@ -147,25 +175,203 @@ function draftBranch(storyId, runId, attempt) {
   return `hone/${storyId || 'story'}-${String(runId).slice(0, 8)}-a${attempt}`;
 }
 
+/** One line of agent- or server-written text, safe to print: control characters (a terminal escape) become spaces. */
+const oneLine = (s, max = 240) => firstLine(String(s || '')).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').trim().slice(0, max);
+
+/** The statuses a batch child ends in. Anything else is still moving as far as the loop can tell. */
+const TERMINAL_RUN = new Set(['completed', 'failed', 'killed', 'stalled']);
+
+/** The shape every planTick return carries, so a caller never meets an absent field. `stop` is always the caller's. */
+const tickPlan = (over) => ({ actions: [], notes: [], waiting: [], moving: 0, follow: [], ...over });
+
+/**
+ * Batches the server's own rows say were re-served: a killed run whose reason names the batch its story went on in.
+ * @param {object} batch  a `GET /orchestrate/batch/:id` payload
+ * @returns {Array<{storyId: string, batchId: string}>}
+ */
+function reservedFrom(batch) {
+  const out = [];
+  for (const r of Array.isArray(batch && batch.runs) ? batch.runs : []) {
+    const batchId = reservedBatchOf(r);
+    if (batchId) out.push({ storyId: r.storyId, batchId });
+  }
+  return out;
+}
+
+/**
+ * A paused run that is not at a step_4 gate and has no request to serve: who is it waiting on?
+ * `person`: a gate or a refusal only a human clears. `dependency`: it will wake when the run it waits on ends.
+ * `moving`: paused without a gate or a reason the loop knows (the server decides what is next); a poll more costs
+ * an interval, and calling it stuck would end a live run.
+ * @returns {{kind: 'person', stepKey: string|null, reason: string}|{kind: 'dependency'}|{kind: 'moving'}}
+ */
+function otherPause(run, row) {
+  const msg = String((run && run.errorMessage) || '');
+  const stepKey = (run && run.currentStep) || (row && row.currentStep) || null;
+  if (/^BATCH_DEPENDENCY_WAITING:/.test(msg)) return { kind: 'dependency' };
+  const c = classifyPollState(run);
+  if (c.outcome === POLL_OUTCOMES.EDITOR_PARKED) {
+    return { kind: 'person', stepKey, reason: 'parked for your editor (execution.mode: editor): submit its output, then approve' };
+  }
+  if (c.outcome === POLL_OUTCOMES.EXHAUSTED || NOT_A_GATE.test(msg)) return { kind: 'person', stepKey, reason: oneLine(msg) };
+  if (c.outcome === POLL_OUTCOMES.HUMAN_GATE) {
+    return { kind: 'person', stepKey, reason: msg ? oneLine(msg) : `awaiting your approval: hone run-story ${run.runId} --approve ${stepKey}` };
+  }
+  return { kind: 'moving' };
+}
+
+/**
+ * True when a verdict from `source` drives the step_4 gate on this run. Mirrors isEnforced in
+ * server/src/services/verification-refusal.js (the CLI does not ship server code); tests/regression/HC-GF-351 pins
+ * the two equal.
+ */
+function gateEnforced(config, source = 'verify-patch') {
+  const mode = String((config && config.verification_gate) || 'advisory').toLowerCase();
+  const sources = config && Array.isArray(config.verification_gate_sources) && config.verification_gate_sources.length
+    ? config.verification_gate_sources : ['verify-patch'];
+  return mode === 'enforce' && sources.includes(source);
+}
+
+/**
+ * A paused step_4 gate whose attempt passed verify-patch under `verification_gate: enforce`. The pass only QUEUES the
+ * approval (POST /:runId/verdict → enqueueApproval); the run stays paused at step_4 until a worker takes the job. It
+ * is moving, not waiting on a person, and saying "approve it" in that window sends the operator to a gate that is
+ * already being approved.
+ */
+function approvalQueued(run) {
+  const why = String((run && run.errorMessage) || '');
+  return !!run && run.currentStep === 'step_4' && !NOT_A_GATE.test(why) && !run.approvalRefusal
+    && gateEnforced(run.config) && verifiedStep4Attempt(run) !== null;
+}
+
+/** step_0 → 0, step_4 → 400, step_5b → 502: the order steps run in, for "after step_4". NaN for a key it cannot read. */
+function stepRank(stepKey) {
+  const m = String(stepKey).match(/^step_(\d+)([a-z]?)$/);
+  return m ? Number(m[1]) * 100 + (m[2] ? m[2].charCodeAt(0) - 96 : 0) : NaN;
+}
+
+/**
+ * The queued or paused runs of this batch that killing `runId` would fail: those whose `config.dependsOnRunIds` lists
+ * it, or whose waiting message names it. `unread` are queued or paused runs whose config was not read, so nothing is
+ * known about them.
+ * @returns {{found: string[], unread: string[]}}  story ids
+ */
+function dependentsOf(runId, runs, details) {
+  const found = [];
+  const unread = [];
+  for (const x of runs) {
+    if (!x || x.runId === runId || (x.status !== 'queued' && x.status !== 'paused')) continue;
+    const d = details[x.runId];
+    const listed = !!d && !!d.config && Array.isArray(d.config.dependsOnRunIds) && d.config.dependsOnRunIds.includes(runId);
+    const named = String(x.errorMessage || (d && d.errorMessage) || '').startsWith(`BATCH_DEPENDENCY_WAITING:${runId}`);
+    if (listed || named) found.push(x.storyId);
+    else if (!d) unread.push(x.storyId);
+  }
+  return { found, unread };
+}
+
+/** Why a story that was served before is not served again, in the words of what actually happened. */
+function priorWhy(prior, runId) {
+  const b = prior.batchId;
+  if (prior.state === 'kill-failed') {
+    return `it was queued again as batch ${b}, but this run could not be killed; kill it (hone run-story ${runId} --kill) once you have looked at that batch. Nothing more is tried`;
+  }
+  if (prior.state === 'adopted') {
+    return `a newer run of this story already exists${b ? ` (batch ${b})` : ''}, queued by an earlier re-serve or by you, so it is not re-served again`;
+  }
+  if (prior.state === 'queue-failed') return 're-serving it failed earlier in this run; nothing more is tried';
+  return `it names files again after being re-served as batch ${b}; a second re-serve is not tried`;
+}
+
+/**
+ * HC-GF-351: may this hard-paused run be re-served now? One of
+ *  - `{ action }`: yes, here is the action;
+ *  - `{ retry }`: not this tick, something transient (the text says what), and the run is still moving;
+ *  - `{ why }`: no, and a person has to look.
+ */
+function decideReserve({ r, d, request, runs, details, ctx, prior, planned, batchId }) {
+  if (prior) return { why: priorWhy(prior, r.runId) };
+  if (planned.has(r.storyId)) return { why: 'the same story is hard-paused twice in this batch; only one is re-served' };
+  const dep = dependentsOf(r.runId, runs, details);
+  if (dep.found.length) {
+    return { why: `${dep.found.length} run(s) in this batch depend on it (${dep.found.slice(0, 5).join(', ')}), and killing it fails them` };
+  }
+  if (dep.unread.length) {
+    return { why: `${dep.unread.length} queued or paused run(s) in this batch could not be checked for a dependency on it, and killing it fails its dependents` };
+  }
+  if (!isStoryId(r.storyId)) return { why: 'its story id cannot be written into a stories file' };
+  const rank = stepRank(request.stepKey);
+  const verified = verifiedStep4Attempt(d);
+  if (rank > 400 && verified !== null) {
+    return { why: `step_4 attempt ${verified} already passed verify-patch, and re-serving from ${request.stepKey} would throw that verified work away` };
+  }
+  if (ctx.tracked == null && ctx.trackedRetry) {
+    return { retry: `could not list the files git tracks (${oneLine(ctx.trackedRetry, 120)}); trying again next poll` };
+  }
+  const original = originalPathsOf(d);
+  if (original.dropped) {
+    return { why: `${original.dropped} path(s) on the story's own line hold characters a shell could misread; nothing was served` };
+  }
+  const judged = judgeRequest(request, { tracked: ctx.tracked, realPath: ctx.realPath, original: original.paths });
+  if (!judged.ok) return { why: judged.reason };
+  return { action: { kind: 'reserve', runId: r.runId, storyId: r.storyId, stepKey: request.stepKey, batchId, paths: judged.tokens,
+    since: d.createdAt || null, repoName: r.repoName || ctx.repoName || null, branch: r.branch || null } };
+}
+
+/** What the loop says when every unfinished run is waiting on a person. */
+function stuckReason(waiting) {
+  const who = waiting.map((w) => `${w.storyId} ${w.runId} at ${w.stepKey || 'a step'} (${oneLine(w.reason, 120)})`);
+  return `every unfinished run is waiting on you: ${who.join('; ')}`;
+}
+
 /**
  * One tick's decisions, from the batch and the details of its paused runs. Pure.
+ *
+ * `stop.kind` says why the batch ends the loop: `breaker` (stop before acting), `terminal` (the server settled
+ * it), or `stuck` (HC-GF-351: nothing is running, nothing is left to do, and the unfinished runs wait on a person).
+ * `waiting` lists those runs, `moving` counts the ones still in motion, and `follow` the batches this one's killed
+ * runs were re-served as.
+ *
  * @param {object} batch     `GET /orchestrate/batch/:id`
  * @param {Record<string, object>} details  runId → `GET /orchestrate/:runId`, for paused runs and runs to emit
- * @param {{emitted: Set<string>}} memory   runs whose emit-pr already ran in this process
- * @param {{repoName?: string|null}} [ctx]  this checkout, so a run for another repository is not touched
- * @returns {{stop: {exitCode: number, reason: string}|null, actions: object[], notes: string[]}}
+ * @param {{emitted: Set<string>, reserved?: Map<string, {batchId: string|null, state: string}>}} memory  `emitted`: runs
+ *   whose emit-pr already ran in this process; `reserved`: story → what became of its re-serve (`state`: served,
+ *   kill-failed, queue-failed or adopted)
+ * @param {{repoName?: string|null, openPr?: boolean, tracked?: Set<string>|null, trackedRetry?: string|null,
+ *          realPath?: ((file: string) => string|null)|null}} [ctx]  this checkout, so a run for another repository is
+ *   not touched; `tracked`: the regular files git tracks here, which a request is checked against (`trackedRetry`:
+ *   why listing them failed this tick, which is worth another poll); `realPath`: where a path resolves on the disk
+ * @returns {{stop: {kind: string, exitCode: number, reason: string}|null, actions: object[], notes: string[],
+ *            waiting: Array<{runId: string, storyId: string, stepKey: string|null, reason: string}>,
+ *            moving: number, follow: Array<{storyId: string, batchId: string}>}}
  */
 function planTick(batch, details, memory, ctx = {}) {
   const b = (batch && typeof batch === 'object') ? batch : {};
   const halt = breakerStop(b);
-  if (halt) return { stop: { exitCode: EXIT.NEEDS_YOU, reason: halt }, actions: [], notes: [] };
+  if (halt) return tickPlan({ stop: { kind: 'breaker', exitCode: EXIT.NEEDS_YOU, reason: halt } });
 
   const actions = [];
   const notes = [];
-  for (const r of Array.isArray(b.runs) ? b.runs : []) {
+  const waiting = [];
+  let moving = 0;
+  const runs = Array.isArray(b.runs) ? b.runs : [];
+  // Stories already re-served: by this process (memory), or by an earlier one (a killed run says so).
+  const follow = reservedFrom(b);
+  const reserved = new Map(memory.reserved || []);
+  for (const f of follow) reserved.set(f.storyId, { batchId: f.batchId, state: 'served' });
+  const planned = new Set();
+  const waitOn = (r, stepKey, reason) => waiting.push({ runId: r.runId, storyId: r.storyId, stepKey, reason });
+  const needsYou = (r, stepKey, reason) => {
+    const why = oneLine(reason, 300);
+    notes.push(`${r.storyId} ${r.runId} needs you at ${stepKey || 'a step'}: ${why}`);
+    waitOn(r, stepKey, why);
+  };
+
+  for (const r of runs) {
     if (!r || !r.runId) continue;
     if (ctx.repoName && r.repoName && r.repoName !== ctx.repoName) {
       notes.push(`${r.storyId} ${r.runId} belongs to ${r.repoName}, not this checkout (${ctx.repoName}): skipped`);
+      if (!TERMINAL_RUN.has(r.status) && r.status !== 'paused') moving += 1;
       continue;
     }
     if (r.status === 'completed') {
@@ -178,14 +384,19 @@ function planTick(batch, details, memory, ctx = {}) {
       }
       continue;
     }
-    if (r.status !== 'paused' || !details[r.runId]) continue;
+    if (r.status !== 'paused') {
+      if (!TERMINAL_RUN.has(r.status)) moving += 1;
+      continue;
+    }
+    const d = details[r.runId];
+    if (!d) { moving += 1; continue; }
     // HC-GF-301: opening PRs, a step_4 attempt that passed verify-patch gets its draft now, while step_5 and its
     // gate are still ahead, instead of when the whole run completes.
-    const verified = ctx.openPr ? verifiedStep4Attempt(details[r.runId]) : null;
+    const verified = ctx.openPr ? verifiedStep4Attempt(d) : null;
     if (verified && !(memory.drafted && memory.drafted.has(`${r.runId}#${verified}`))) {
-      actions.push({ kind: 'draft', runId: r.runId, storyId: r.storyId, attempt: verified, run: details[r.runId],
+      actions.push({ kind: 'draft', runId: r.runId, storyId: r.storyId, attempt: verified, run: d,
         branch: draftBranch(r.storyId, r.runId, verified) });
-      const vs = Array.isArray(details[r.runId].verifications) ? details[r.runId].verifications : [];
+      const vs = Array.isArray(d.verifications) ? d.verifications : [];
       const earlier = vs.filter((v) => v && v.source === 'verify-patch' && v.stepKey === 'step_4' && v.verdict === 'pass'
         && Number(v.attempt) < verified).map((v) => Number(v.attempt));
       if (earlier.length) {
@@ -193,28 +404,114 @@ function planTick(batch, details, memory, ctx = {}) {
         notes.push(`${r.storyId} ${r.runId}: the draft for attempt ${verified} supersedes the one on ${draftBranch(r.storyId, r.runId, m)}; close that one when you are ready`);
       }
     }
-    const a = step4Action(details[r.runId]);
+
+    // HC-GF-351: a hard pause for files the step was not given. Served once per story, and only if every path passes.
+    const request = hardPauseRequest(d);
+    if (request) {
+      const decided = decideReserve({ r, d, request, runs, details, ctx, prior: reserved.get(r.storyId), planned, batchId: b.batchId });
+      if (decided.action) {
+        planned.add(r.storyId);
+        actions.push(decided.action);
+      } else if (decided.retry) {
+        notes.push(`${r.storyId} ${r.runId}: ${decided.retry}`);
+        moving += 1;
+      } else {
+        needsYou(r, request.stepKey, `it asked for files it was not given: ${decided.why}`);
+      }
+      continue;
+    }
+
+    const a = step4Action(d);
     // verify-patch's verdict POST is best-effort: an attempt this process already ran is not re-run every tick.
     if (a.actionable && memory.tried && memory.tried.has(`${r.runId}#${a.attempt}`)) {
-      notes.push(`${r.storyId} ${r.runId} needs you: attempt ${a.attempt} was verified here but no verdict reached the server`);
+      needsYou(r, 'step_4', `attempt ${a.attempt} was handled here (see the lines above) and the server holds no verdict for it`);
       continue;
     }
     if (a.actionable) {
-      actions.push({ kind: 'verify', runId: r.runId, storyId: r.storyId, attempt: a.attempt, run: details[r.runId] });
+      actions.push({ kind: 'verify', runId: r.runId, storyId: r.storyId, attempt: a.attempt, run: d });
+    } else if (a.reason && approvalQueued(d)) {
+      moving += 1;
     } else if (a.reason) {
-      notes.push(`${r.storyId} ${r.runId} needs you: ${a.reason}`);
+      needsYou(r, 'step_4', a.reason);
+    } else {
+      const p = otherPause(d, r);
+      if (p.kind === 'person') needsYou(r, p.stepKey, p.reason);
+      else if (p.kind === 'moving') moving += 1;
     }
   }
 
-  if (!isTerminal(b)) return { stop: null, actions, notes };
-  const unfinished = (b.counts && ((b.counts.failed || 0) + (b.counts.killed || 0) + (b.counts.stalled || 0))) || 0;
-  return {
+  if (!isTerminal(b)) {
+    const stuck = actions.length === 0 && moving === 0 && waiting.length > 0;
+    return tickPlan({ stop: stuck ? { kind: 'stuck', exitCode: EXIT.NEEDS_YOU, reason: stuckReason(waiting) } : null,
+      actions, notes, waiting, moving, follow });
+  }
+  // A killed run that was re-served is not unfinished: its story went on in the batch it names.
+  const raw = (b.counts && ((b.counts.failed || 0) + (b.counts.killed || 0) + (b.counts.stalled || 0))) || 0;
+  const unfinished = Math.max(0, raw - follow.length);
+  return tickPlan({
     stop: unfinished
-      ? { exitCode: EXIT.NEEDS_YOU, reason: `batch ${b.status}: ${unfinished} run(s) did not complete` }
-      : { exitCode: EXIT.DONE, reason: `batch ${b.status}` },
-    actions,
-    notes,
-  };
+      ? { kind: 'terminal', exitCode: EXIT.NEEDS_YOU, reason: `batch ${b.status}: ${unfinished} run(s) did not complete` }
+      : { kind: 'terminal', exitCode: EXIT.DONE, reason: `batch ${b.status}` },
+    actions, notes, waiting, moving, follow,
+  });
+}
+
+/**
+ * HC-GF-351: queue the story again with the files its step asked for, then kill the paused run. In that order: the
+ * kill's reason names the new batch (the next start reads it back, which is what keeps the story from being served
+ * twice), and a story with no run in flight is worse than one with two. If the queue fails the paused run is left
+ * alone; if the kill fails the new batch still runs and the paused run is named for a person.
+ *
+ * Before queueing it asks the server whether the story was served already (io.priorServe): a kill that failed, or a
+ * crash between the queue and the kill, leaves no marker, and only a newer run of the same story shows it happened.
+ * @returns {Promise<{lines: string[], needsYou: boolean, batchId: string|null, state: string|null, retry?: boolean}>}
+ *   `batchId`: the batch the story was queued as, set whenever it was, even when the kill then failed; `state`: what
+ *   became of the re-serve (served, kill-failed, queue-failed, adopted); `retry`: nothing was decided, ask again
+ */
+async function reserve(action, io, tag) {
+  if (io.priorServe) {
+    let prior;
+    try {
+      prior = await io.priorServe(action);
+    } catch (e) {
+      return { lines: [`${tag} not re-served yet: could not ask whether the story was served already (${firstLine(e && e.message)}); asking again next poll`],
+        needsYou: false, batchId: null, state: null, retry: true };
+    }
+    if (prior && prior.kind === 'unknown') {
+      return { lines: [`${tag} not re-served: could not tell whether the story was served already; the paused run was left alone`],
+        needsYou: true, batchId: null, state: 'queue-failed' };
+    }
+    if (prior) {
+      const where = prior.batchId ? ` in batch ${prior.batchId}` : '';
+      return { lines: [`${tag} not re-served: run ${prior.runId}${where} is this story's ${prior.kind === 'later' ? 'newer' : 'earlier, re-served'} run; following it`],
+        needsYou: true, batchId: prior.batchId || null, state: 'adopted' };
+    }
+  }
+  let queued;
+  let file = null;
+  try {
+    file = io.writeStoriesFile(`${formatStoryLine({ storyId: action.storyId, paths: action.paths })}\n`);
+    queued = await io.runVerb(buildReserveArgs(file.file, { repoName: action.repoName, branch: action.branch }), { capture: true });
+  } catch (e) {
+    return { lines: [`${tag} not re-served: ${firstLine(e && e.message)}; the paused run was left alone`], needsYou: true, batchId: null, state: 'queue-failed' };
+  } finally {
+    if (file) file.remove();
+  }
+  const batchId = queued.code === 0 ? batchIdFromQueueOutput(queued.stdout) : null;
+  if (!batchId) {
+    const why = queued.code === 0 ? 'printed no batch id' : `exited ${queued.code}`;
+    return { lines: [`${tag} not re-served: queue-stories ${why}; the paused run was left alone`], needsYou: true, batchId: null, state: 'queue-failed' };
+  }
+  const lines = [`${tag} ${action.stepKey} named files it was not given: queued batch ${batchId} with paths:${action.paths.join(',')}`];
+  try {
+    await io.killRun(action.runId, reserveReason(batchId, action.stepKey));
+  } catch (e) {
+    const status = e && e.response && e.response.status;
+    lines.push(`${tag} could NOT kill the paused run (${status || firstLine(e && e.message)}); it is still paused beside batch ${batchId}: kill it with hone run-story ${action.runId} --kill`);
+    return { lines, needsYou: true, batchId, state: 'kill-failed' };
+  }
+  lines.push(`${tag} killed the paused run: ${reserveReason(batchId, action.stepKey)}`);
+  return { lines, needsYou: false, batchId, state: 'served' };
 }
 
 /**
@@ -229,6 +526,7 @@ function planTick(batch, details, memory, ctx = {}) {
  */
 async function runTask(action, io, opts = {}) {
   const tag = `[follow-batch] ${action.storyId} ${action.runId}`;
+  if (action.kind === 'reserve') return reserve(action, io, tag);
   if (action.kind === 'emit' || action.kind === 'draft') {
     // emit-pr re-runs the tests before it commits, even as a local dry run, so it needs the same consent and
     // provenance verify-patch does. Without this, a repository that never set ci.local_command gets `make ci`.
@@ -255,11 +553,33 @@ async function runTask(action, io, opts = {}) {
   return { lines, needsYou: v.code !== 0 };
 }
 
+/**
+ * What the loop returns once every batch it follows has ended (settled by the server, or stuck on a person).
+ * DONE only when every one of them completed and no emit is owed; the reason of each batch that did not is kept.
+ * A batch stuck on a person is not over: step_5's gate is mandatory, so this is where most runs end, and the reason
+ * says how to continue (`again`: the batches to follow once the person has acted).
+ */
+function settle(stops, memory, again = []) {
+  const open = stops.filter((s) => s.exitCode !== EXIT.DONE);
+  const owed = memory.owed.size ? `${memory.owed.size} run(s) were not emitted: ${[...memory.owed.values()].join(', ')}` : '';
+  if (open.length === 0 && !owed) return { exitCode: EXIT.DONE, reason: stops.map((s) => s.reason).join('; ') };
+  const why = [...open.map((s) => s.reason), owed].filter(Boolean);
+  const next = again.length ? ` (after you act, run again to emit: hone follow-batch ${again.join('; hone follow-batch ')})` : '';
+  return { exitCode: EXIT.NEEDS_YOU, reason: (open.length ? why.join('; ') : `${stops.map((s) => s.reason).join('; ')}, but ${owed}`) + next };
+}
+
 /**
  * The loop. Every effect is injected, so a test drives it with a stub server and a recording runVerb.
+ *
+ * It follows a SET of batches: the one it was given, and every batch a killed run says its story was re-served as
+ * (HC-GF-351), found in the same tick. It ends when every one of them has ended, or when one has fired a breaker.
  * @param {string} batchId
  * @param {{fetchBatch: Function, fetchRun: Function, runVerb: Function, verifyDecision: Function,
- *          sleep: (ms: number) => Promise<void>, now: () => number, log: (line: string) => void}} io
+ *          sleep: (ms: number) => Promise<void>, now: () => number, log: (line: string) => void,
+ *          trackedPaths?: () => Promise<Set<string>>|Set<string>, realPath?: (file: string) => string|null,
+ *          priorServe?: Function, writeStoriesFile?: Function, killRun?: Function}} io
+ *   trackedPaths, realPath, priorServe, writeStoriesFile and killRun serve a re-serve; without trackedPaths or
+ *   realPath every request is refused, and without priorServe nobody asks whether the story was served already.
  * @param {{pollMs?: number, deadlineMs?: number|null, maxOfflineMs?: number, openPr?: boolean,
  *          repoName?: string|null}} [opts]
  * @returns {Promise<{exitCode: number, reason: string}>}
@@ -268,8 +588,10 @@ async function followBatch(batchId, io, opts = {}) {
   const pollMs = opts.pollMs || 30_000;
   const maxOfflineMs = opts.maxOfflineMs || 15 * 60_000;
   // owed: runs whose emit-pr needed a person. A completed batch with one of these is not DONE (HC-GF-207's shape:
-  // a failure path that exits 0).
-  const memory = { emitted: new Set(), tried: new Set(), drafted: new Set(), said: new Set(), owed: new Map() };
+  // a failure path that exits 0). reserved: story → what became of its re-serve ({batchId, state}). trackedFails:
+  // consecutive ticks on which listing the tracked files failed.
+  const memory = { emitted: new Set(), tried: new Set(), drafted: new Set(), said: new Set(), owed: new Map(), reserved: new Map(), trackedFails: 0 };
+  const followed = [batchId];
   const start = io.now();
   let offlineSince = null;
   const say = (line) => { if (!memory.said.has(line)) { memory.said.add(line); io.log(line); } };
@@ -280,19 +602,36 @@ async function followBatch(batchId, io, opts = {}) {
     }
     // A tick reads everything or acts on nothing: a run that could not be read is the server being unreachable,
     // not a run with no details (which would skip its gate, or emit it with no provenance to assess).
-    let batch;
-    const details = {};
+    const reads = [];
+    let reading = batchId;
     try {
-      batch = await io.fetchBatch(batchId);
-      for (const r of Array.isArray(batch && batch.runs) ? batch.runs : []) {
-        const wanted = r && r.runId && (r.status === 'paused' || (r.status === 'completed' && !memory.emitted.has(r.runId)));
-        if (wanted) details[r.runId] = await io.fetchRun(r.runId);
+      for (let i = 0; i < followed.length; i += 1) {
+        reading = followed[i];
+        const batch = await io.fetchBatch(reading);
+        const details = {};
+        for (const r of Array.isArray(batch && batch.runs) ? batch.runs : []) {
+          const wanted = r && r.runId && (r.status === 'paused' || (r.status === 'completed' && !memory.emitted.has(r.runId)));
+          if (wanted) details[r.runId] = await io.fetchRun(r.runId);
+        }
+        // A run hard-paused on a request is only re-served if nothing depends on it, and a queued run has not said
+        // what it depends on: its config is the only place that is written. Read them when a request is waiting.
+        if (Object.values(details).some((d) => hardPauseRequest(d))) {
+          for (const r of Array.isArray(batch && batch.runs) ? batch.runs : []) {
+            if (r && r.runId && r.status === 'queued' && !details[r.runId]) details[r.runId] = await io.fetchRun(r.runId);
+          }
+        }
+        reads.push({ batch, details });
+        // A killed run that says where its story went: follow that batch, and do not serve the story again.
+        for (const f of reservedFrom(batch)) {
+          memory.reserved.set(f.storyId, { batchId: f.batchId, state: 'served' });
+          if (!followed.includes(f.batchId)) followed.push(f.batchId);
+        }
       }
       offlineSince = null;
     } catch (e) {
       const status = e && e.response && e.response.status;
       if (status === 401 || status === 403 || status === 404) {
-        return { exitCode: EXIT.FATAL, reason: `the server answered ${status} while reading batch ${batchId}` };
+        return { exitCode: EXIT.FATAL, reason: `the server answered ${status} while reading batch ${reading}` };
       }
       if (offlineSince === null) offlineSince = io.now();
       if (io.now() - offlineSince >= maxOfflineMs) {
@@ -302,32 +641,60 @@ async function followBatch(batchId, io, opts = {}) {
       continue;
     }
 
-    const plan = planTick(batch, details, memory, { repoName: opts.repoName || null, openPr: !!opts.openPr });
-    for (const n of plan.notes) say(`[follow-batch] ${n}`);
-    for (const action of plan.actions) {
-      const out = await runTask(action, io, { openPr: opts.openPr });
-      if (action.kind === 'emit' || action.kind === 'draft') {
-        if (action.kind === 'emit') memory.emitted.add(action.runId);
-        else memory.drafted.add(`${action.runId}#${action.attempt}`);
-        // A run is owed until an emit for it succeeds: a draft that failed is retried by the completed-run emit.
-        if (out.needsYou) memory.owed.set(action.runId, `${action.storyId} ${action.runId}`);
-        else if (action.kind === 'emit') memory.owed.delete(action.runId);
-      } else {
-        memory.tried.add(`${action.runId}#${action.attempt}`);
+    // The checkout's tracked files, asked for only when a run is hard-paused on a request. Without them every
+    // path is refused: a request cannot be served on a list that could not be read. A listing that fails is
+    // worth three more polls (git can be busy), not an exit.
+    let tracked = null;
+    let trackedRetry = null;
+    const asks = reads.some((x) => Object.values(x.details).some((d) => hardPauseRequest(d)));
+    if (asks && io.trackedPaths) {
+      try {
+        tracked = await io.trackedPaths();
+        memory.trackedFails = 0;
+      } catch (e) {
+        memory.trackedFails += 1;
+        if (memory.trackedFails <= 3) trackedRetry = firstLine(e && e.message) || 'git ls-files failed';
+      }
+    }
+    const ctx = { repoName: opts.repoName || null, openPr: !!opts.openPr, tracked, trackedRetry, realPath: io.realPath || null };
+    const plans = reads.map((x) => planTick(x.batch, x.details, memory, ctx));
+    for (const plan of plans) for (const n of plan.notes) say(`[follow-batch] ${n}`);
+    // A fired breaker stops the loop BEFORE any batch's action runs.
+    const halted = plans.find((plan) => plan.stop && plan.stop.kind === 'breaker');
+    if (halted) return { exitCode: halted.stop.exitCode, reason: halted.stop.reason };
+
+    let grew = false;
+    for (const plan of plans) {
+      for (const action of plan.actions) {
+        const out = await runTask(action, io, { openPr: opts.openPr });
+        if (action.kind === 'reserve') {
+          if (!out.retry) {
+            memory.reserved.set(action.storyId, { batchId: out.batchId, state: out.state });
+            if (out.batchId && !followed.includes(out.batchId)) { followed.push(out.batchId); grew = true; }
+          }
+        } else if (action.kind === 'emit' || action.kind === 'draft') {
+          if (action.kind === 'emit') memory.emitted.add(action.runId);
+          else memory.drafted.add(`${action.runId}#${action.attempt}`);
+          // A run is owed until an emit for it succeeds: a draft that failed is retried by the completed-run emit.
+          if (out.needsYou) memory.owed.set(action.runId, `${action.storyId} ${action.runId}`);
+          else if (action.kind === 'emit') memory.owed.delete(action.runId);
+        } else {
+          memory.tried.add(`${action.runId}#${action.attempt}`);
+        }
+        for (const line of out.lines) io.log(line);
       }
-      for (const line of out.lines) io.log(line);
     }
-    if (plan.stop && plan.stop.exitCode === EXIT.DONE && memory.owed.size) {
-      return { exitCode: EXIT.NEEDS_YOU,
-        reason: `${plan.stop.reason}, but ${memory.owed.size} run(s) were not emitted: ${[...memory.owed.values()].join(', ')}` };
+    // Ended means every batch read this tick has: settled by the server, or stuck on a person. A batch queued
+    // this tick has not been read yet.
+    if (!grew && plans.every((plan) => plan.stop)) {
+      return settle(plans.map((plan) => plan.stop), memory, followed.filter((id, i) => plans[i].stop.kind === 'stuck'));
     }
-    if (plan.stop) return plan.stop;
     await io.sleep(pollMs);
   }
 }
 
 module.exports = {
   EXIT, FORBIDDEN_FLAGS, NOT_A_GATE,
-  breakerStop, isTerminal, priorVerdict, step4Action, buildArgs, planTick, runTask, followBatch,
-  currentStep4Attempt, verifiedStep4Attempt, draftBranch,
+  breakerStop, isTerminal, priorVerdict, step4Action, buildArgs, buildReserveArgs, planTick, runTask, followBatch,
+  currentStep4Attempt, verifiedStep4Attempt, draftBranch, reservedFrom, otherPause, stuckReason, gateEnforced, stepRank,
 };