@hone-ai/cli 1.39.0 → 1.40.0

package/lib/batch-follow.js

@@ -14,6 +14,18 @@
  *  - The loop never approves and never posts a verdict (`verify-patch --report` does). It never passes
  *    `--trust-source`, `--skip-verify`, `--ready` or `--acknowledge-*`: an untrusted story stays paused for a
  *    person (HC-GF-270), and so does one whose repository never consented to running its tests (HC-GF-064).
+ *  - HC-GF-363: under `verification.gate: enforce` the server refuses to approve a step_4 attempt whose
+ *    verify-patch verdict is `fail`, and the loop used to stop there (exit 2). It now sends that one case back
+ *    to the builder: POST /orchestrate/:runId/reject at step_4, with the measured failing tests as the reason,
+ *    at most AUTO_REJECT_LIMIT (2) times per run. It rejects ONLY when every one of these holds: the gate is
+ *    enforce for verify-patch, the server refuses approval, the latest completed step_4 attempt's LATEST
+ *    verify-patch record says `fail` (not timeout, unresolved, not_run, error, pass_narrowed), the run's error
+ *    says the same, and fewer than two earlier attempts carry AUTO_REJECT_PREFIX in their reject reason. The
+ *    count is read from the server's rows on every decision, never kept here, so a restart cannot reset it; a
+ *    read that fails means "unknown", and unknown never rejects. The two rejects spend step_4's re-execution
+ *    budget (`max_retries_per_step`, default 2): a later step_5 route-back can pause MAX_RETRIES_EXCEEDED.
+ *    A run stopped at the limit is named for a person (step, attempts, count, last failure) and the loop exits 2.
+ *    Upgrading changes one thing: a run already paused on a refused `fail` is rejected on the first tick.
  *  - 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.
@@ -29,6 +41,7 @@
  */
 
 const { classifyPollState, POLL_OUTCOMES } = require('./poll-decision');
+const { routerSafe } = require('./verify-patch');
 const { formatStoryLine } = require('./story-line');
 const { isGitRev, isStoryId } = require('./run-target');
 const {
@@ -92,10 +105,26 @@ function isTerminal(batch) {
   return !!(batch && batch.status && batch.status !== 'active');
 }
 
-/** The verify-patch verdict the server already holds for this run's step_4 attempt, or null. */
+/**
+ * The verify-patch verdict the server holds for this run's step_4 attempt, or null: the LATEST record for it, as the
+ * server reads them (verdictForAttempt takes the last by reportedAt). A record names its attempt, or carries
+ * `forAttempt` (the latest completed attempt when it arrived). HC-GF-363: this used to return the FIRST match, so an
+ * attempt that failed and then passed read as failed.
+ */
 function priorVerdict(run, attempt) {
   const list = Array.isArray(run && run.verifications) ? run.verifications : [];
-  return list.find((v) => v && v.source === 'verify-patch' && v.stepKey === 'step_4' && Number(v.attempt) === attempt) || null;
+  const forThis = (v) => v && v.source === 'verify-patch' && v.stepKey === 'step_4'
+    && (v.attempt != null ? Number(v.attempt) === attempt : v.forAttempt != null && Number(v.forAttempt) === attempt);
+  let best = null;
+  let bestAt = -Infinity;
+  for (const v of list) {
+    if (!forThis(v)) continue;
+    const at = Date.parse(v.reportedAt);
+    const t = Number.isFinite(at) ? at : -Infinity;
+    // Later by clock wins; equal or unreadable clocks fall back to list order (the server appends).
+    if (best === null || t >= bestAt) { best = v; bestAt = t; }
+  }
+  return best;
 }
 
 /**
@@ -123,6 +152,88 @@ function step4Action(run) {
   return { actionable: true, attempt };
 }
 
+/** Marks a step_4 reject reason as this loop's own. It starts the reason (position 0), and is counted back from rows. */
+const AUTO_REJECT_PREFIX = 'auto-rejected by follow-batch: ';
+
+/** Automatic rejects per run. Each one is a full step_4 rebuild plus a verify-patch run. */
+const AUTO_REJECT_LIMIT = 2;
+
+/** The reason's tail, from the server-held verdict detail: one line, no control characters, bounded. */
+const DETAIL_IN_REASON = 1500;
+
+/**
+ * HC-GF-363: is this paused run a step_4 gate whose latest attempt FAILED verification under enforce, so that the
+ * loop may send it back? Every condition, none inferred from another (`approvalRefusal` alone is also set for a
+ * timeout, an unresolved or narrowed run, which are not measured failures and are never sent back):
+ *  1. a human gate at step_4 (not a breaker, budget, retry-limit or hard pause: condition 6 excludes those);
+ *  2. verification.gate is enforce for verify-patch;
+ *  3. the server refuses approval (`approvalRefusal`);
+ *  4. the latest step_4 attempt is completed (attempt L);
+ *  5. the LATEST verify-patch record for L has verdict exactly `fail`;
+ *  6. the run's error message is the one the enforce red branch writes for a `fail`.
+ * The count of earlier rejects (7) is read from the server by the caller: see autoRejectDecision.
+ * @returns {{attempt: number, detail: string}|null}
+ */
+function autoRejectCandidate(run) {
+  const c = classifyPollState(run);
+  if (c.outcome !== POLL_OUTCOMES.HUMAN_GATE || c.stepKey !== 'step_4') return null;
+  // Not a breaker, budget, retry-limit or hard pause (NOT_A_GATE): each carries its own error prefix, so the
+  // enforce-fail message required below already excludes them, and tests/…/batch-follow-reject.test.js drives them.
+  const why = String((run && run.errorMessage) || '');
+  if (!gateEnforced(run.config, 'verify-patch')) return null;
+  if (!run.approvalRefusal) return null;
+  const attempt = currentStep4Attempt(run);
+  if (!attempt) return null;
+  const row = run.steps.find((st) => st && st.stepKey === 'step_4' && (Number(st.attempt) || 1) === attempt);
+  if (!row || row.status !== 'completed') return null;
+  // A hard pause (files the step asked for) that a fail verdict then overwrote the error message of: HC-GF-351's
+  // re-serve owns it, not this reject.
+  const fr = row.diagnostics && row.diagnostics.failure_record;
+  if (fr && fr.context_requests && typeof fr.context_requests === 'object') return null;
+  const v = priorVerdict(run, attempt);
+  if (!v || v.verdict !== 'fail') return null;
+  if (!why.startsWith("verify verdict 'fail' at step_4")) return null;
+  return { attempt, detail: String(v.detail == null ? '' : v.detail) };
+}
+
+/** The attempts (1-based, of `contexts`) whose reject reason starts with the prefix. */
+function autoRejectedAttempts(contexts) {
+  const out = [];
+  (Array.isArray(contexts) ? contexts : []).forEach((ctx, i) => {
+    if (typeof ctx === 'string' && ctx.startsWith(AUTO_REJECT_PREFIX)) out.push(i + 1);
+  });
+  return out;
+}
+
+/**
+ * HC-GF-363: what to do about a paused run, given each earlier step_4 attempt's `errorContext`. Pure.
+ * @param {object} run  a fresh `GET /orchestrate/:runId`
+ * @param {Array<string|null>|null} contexts  `errorContext` of attempts 1..L-1, in order; null when any read failed
+ * @returns {{kind: 'none'} | {kind: 'unknown', attempt: number, why: string}
+ *   | {kind: 'exhausted', attempt: number, count: number, rejected: number[], note: string}
+ *   | {kind: 'reject', attempt: number, n: number, reason: string}}
+ */
+function autoRejectDecision(run, contexts) {
+  const cand = autoRejectCandidate(run);
+  if (!cand) return { kind: 'none' };
+  const L = cand.attempt;
+  if (!Array.isArray(contexts) || contexts.length !== L - 1) {
+    return { kind: 'unknown', attempt: L, why: 'the earlier attempts could not all be read, so the rejects already used are unknown' };
+  }
+  const rejected = autoRejectedAttempts(contexts);
+  const count = rejected.length;
+  const clean = routerSafe(cand.detail).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, DETAIL_IN_REASON);
+  if (count >= AUTO_REJECT_LIMIT) {
+    const budget = contexts.some((x) => /MAX_RETRIES_EXCEEDED/.test(String(x || ''))) || /MAX_RETRIES_EXCEEDED/.test(String(run.errorMessage || ''))
+      ? ' MAX_RETRIES_EXCEEDED was seen: the rejects use step_4\'s retry budget.' : '';
+    return { kind: 'exhausted', attempt: L, count, rejected,
+      note: `step_4 attempt ${L} failed verify-patch; ${count} automatic reject(s) used (attempt${rejected.length === 1 ? '' : 's'} ${rejected.join(', ')}); `
+        + `last failure: ${clean.slice(0, 200) || '(no detail)'}.${budget} Read it: hone run-report ${run.runId || '<runId>'}` };
+  }
+  return { kind: 'reject', attempt: L, n: count + 1,
+    reason: `${AUTO_REJECT_PREFIX}attempt ${L} failed verify-patch under verification.gate: enforce (automatic reject ${count + 1} of ${AUTO_REJECT_LIMIT}). ${clean || '(no detail)'}` };
+}
+
 /**
  * The argv for one child verb. Exit codes are the contract; `--format json` only carries detail.
  * @param {'check-patch'|'verify-patch'|'emit-pr'} verb
@@ -178,11 +289,14 @@ function draftBranch(storyId, runId, 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);
 
+/** Polls an accepted reject may wait for the worker before a person is told. */
+const REJECT_WAIT_TICKS = 20;
+
 /** 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 });
+const tickPlan = (over) => ({ actions: [], notes: [], waiting: [], moving: 0, follow: [], rejecting: [], ...over });
 
 /**
  * Batches the server's own rows say were re-served: a killed run whose reason names the batch its story went on in.
@@ -320,7 +434,7 @@ function decideReserve({ r, d, request, runs, details, ctx, prior, planned, batc
 
 /** 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)})`);
+  const who = waiting.map((w) => `${w.storyId} ${w.runId} at ${w.stepKey || 'a step'} (${oneLine(w.reason, 400)})`);
   return `every unfinished run is waiting on you: ${who.join('; ')}`;
 }
 
@@ -354,6 +468,7 @@ function planTick(batch, details, memory, ctx = {}) {
   const notes = [];
   const waiting = [];
   let moving = 0;
+  const rejecting = [];
   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);
@@ -362,7 +477,7 @@ function planTick(batch, details, memory, ctx = {}) {
   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);
+    const why = oneLine(reason, 400);
     notes.push(`${r.storyId} ${r.runId} needs you at ${stepKey || 'a step'}: ${why}`);
     waitOn(r, stepKey, why);
   };
@@ -421,6 +536,19 @@ function planTick(batch, details, memory, ctx = {}) {
       continue;
     }
 
+    // HC-GF-363: a refused `fail` is sent back, once per attempt, by the executor, which re-reads the run and the
+    // earlier attempts' rows before it POSTs. `memory.rejected` and `rejectStuck` only stop this tick repeating
+    // itself; the bound is read from the server.
+    const cand = autoRejectCandidate(d);
+    if (cand) {
+      const key = `${r.runId}#${cand.attempt}`;
+      const stuck = memory.rejectStuck && memory.rejectStuck.get(key);
+      if (stuck) needsYou(r, 'step_4', stuck);
+      else if (memory.rejected && memory.rejected.has(key)) { moving += 1; rejecting.push(key); }
+      else actions.push({ kind: 'reject', runId: r.runId, storyId: r.storyId, attempt: cand.attempt, run: d });
+      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}`)) {
@@ -443,7 +571,7 @@ function planTick(batch, details, memory, ctx = {}) {
   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 });
+      actions, notes, waiting, moving, follow, rejecting });
   }
   // 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;
@@ -452,7 +580,7 @@ function planTick(batch, details, memory, ctx = {}) {
     stop: unfinished
       ? { 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,
+    actions, notes, waiting, moving, follow, rejecting,
   });
 }
 
@@ -514,6 +642,69 @@ async function reserve(action, io, tag) {
   return { lines, needsYou: false, batchId, state: 'served' };
 }
 
+/** The HTTP status of a thrown axios error, or undefined. */
+const statusOf = (e) => (e && e.response && e.response.status) || undefined;
+
+/**
+ * HC-GF-363: send a refused step_4 `fail` back to the builder, if the bound allows. Re-reads the run and re-decides
+ * right before the POST (the plan is up to one poll old), then counts the earlier rejects from each earlier attempt's
+ * stored reject reason. Any read that fails means the count is unknown, and unknown never rejects.
+ * @returns {Promise<{lines: string[], needsYou: boolean, state: 'posted'|'moved'|'stuck'|'retry', note?: string,
+ *   countsRead?: boolean, fatal?: string}>}
+ *   `retry`: nothing was sent, ask again next poll (`countsRead: true` when it was a read that failed, which is
+ *   given up on after three); `fatal`: the server answered 401, 403 or 404 where it never should
+ */
+async function autoReject(action, io, tag) {
+  const where = `step_4 attempt ${action.attempt}`;
+  const fatal = (e, what) => ([401, 403, 404].includes(statusOf(e)) ? `the server answered ${statusOf(e)} while ${what}` : null);
+  if (!io.rejectRun || !io.fetchStep) {
+    return { lines: [`${tag} ${where} failed verification; this client cannot reject, so it is left for you`], needsYou: true, state: 'stuck', note: `${where} failed verification and was not sent back` };
+  }
+  let fresh;
+  try {
+    fresh = await io.fetchRun(action.runId);
+  } catch (e) {
+    const f = fatal(e, `re-reading run ${action.runId}`);
+    if (f) return { lines: [], needsYou: false, state: 'retry', fatal: f };
+    return { lines: [`${tag} not rejected yet: could not re-read the run (${firstLine(e && e.message)}); asking again next poll`], needsYou: false, state: 'retry' };
+  }
+  const now = autoRejectCandidate(fresh);
+  if (!now || now.attempt !== action.attempt) {
+    return { lines: [`${tag} ${where} is no longer a refused failure; nothing sent`], needsYou: false, state: 'moved' };
+  }
+  const contexts = [];
+  for (let k = 1; k < action.attempt; k += 1) {
+    try {
+      const row = await io.fetchStep(action.runId, 'step_4', k);
+      contexts.push(row && typeof row.errorContext === 'string' ? row.errorContext : null);
+    } catch (e) {
+      return { lines: [`${tag} not rejected yet: could not read step_4 attempt ${k} (${statusOf(e) || firstLine(e && e.message)}), so the rejects already used are unknown; asking again next poll`],
+        needsYou: false, state: 'retry', countsRead: true };
+    }
+  }
+  const dec = autoRejectDecision(fresh, contexts);
+  if (dec.kind === 'exhausted') {
+    return { lines: [`${tag} ${dec.note}`], needsYou: true, state: 'stuck', note: dec.note };
+  }
+  if (dec.kind !== 'reject') {
+    return { lines: [`${tag} ${where}: no automatic reject (${dec.why || dec.kind})`], needsYou: false, state: 'retry', countsRead: true };
+  }
+  try {
+    await io.rejectRun(action.runId, { stepKey: 'step_4', reason: dec.reason });
+  } catch (e) {
+    const status = statusOf(e);
+    const f = fatal(e, `rejecting ${where}`);
+    if (f) return { lines: [], needsYou: false, state: 'retry', fatal: f };
+    if (status === 409) return { lines: [`${tag} ${where} was not rejected: the run moved on (409); this does not count`], needsYou: false, state: 'moved' };
+    if (status === 400) {
+      const note = `${where} failed verification and the server refused the reject (400: ${oneLine(e.response.data && e.response.data.error, 120)})`;
+      return { lines: [`${tag} ${note}`], needsYou: true, state: 'stuck', note };
+    }
+    return { lines: [`${tag} not rejected yet: ${status || firstLine(e && e.message)}; asking again next poll`], needsYou: false, state: 'retry' };
+  }
+  return { lines: [`${tag} ${where} failed verification: rejected it (automatic reject ${dec.n} of ${AUTO_REJECT_LIMIT}): ${oneLine(now.detail, 200)}`], needsYou: false, state: 'posted' };
+}
+
 /**
  * Run one action's child verbs, in order, and describe what happened. Nothing that executes the adopter's tests
  * (verify-patch, or emit-pr, which re-verifies) starts unless the repository's consent and the story's provenance
@@ -527,6 +718,7 @@ async function reserve(action, io, tag) {
 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 === 'reject') return autoReject(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`.
@@ -577,7 +769,8 @@ function settle(stops, memory, again = []) {
  * @param {{fetchBatch: Function, fetchRun: Function, runVerb: Function, verifyDecision: Function,
  *          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
+ *          priorServe?: Function, writeStoriesFile?: Function, killRun?: Function, rejectRun?: Function,
+ *          fetchStep?: 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,
@@ -590,7 +783,10 @@ async function followBatch(batchId, io, opts = {}) {
   // 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). 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 memory = { emitted: new Set(), tried: new Set(), drafted: new Set(), said: new Set(), owed: new Map(), reserved: new Map(), trackedFails: 0,
+    // HC-GF-363: only to stop a tick repeating itself. rejected: attempt key → ticks waited since the reject was accepted;
+    // rejectStuck: key → why a person has to act; rejectReads: key → consecutive failed reads of the earlier attempts.
+    rejected: new Map(), rejectStuck: new Map(), rejectReads: new Map() };
   const followed = [batchId];
   const start = io.now();
   let offlineSince = null;
@@ -663,10 +859,34 @@ async function followBatch(batchId, io, opts = {}) {
     const halted = plans.find((plan) => plan.stop && plan.stop.kind === 'breaker');
     if (halted) return { exitCode: halted.stop.exitCode, reason: halted.stop.reason };
 
+    // An accepted reject that the worker has not applied for REJECT_WAIT_TICKS polls is named for a person.
+    for (const plan of plans) {
+      for (const key of plan.rejecting) {
+        const waited = (memory.rejected.get(key) || 0) + 1;
+        memory.rejected.set(key, waited);
+        if (waited >= REJECT_WAIT_TICKS) {
+          memory.rejectStuck.set(key, `a reject was accepted ${waited} polls ago and the run is still paused at the same attempt; look at it with hone run-report`);
+        }
+      }
+    }
+
     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 === 'reject') {
+          if (out.fatal) return { exitCode: EXIT.FATAL, reason: out.fatal };
+          const key = `${action.runId}#${action.attempt}`;
+          if (out.state === 'posted' || out.state === 'moved') memory.rejected.set(key, 0);
+          else if (out.state === 'stuck') memory.rejectStuck.set(key, out.note);
+          else if (out.countsRead) {
+            const n = (memory.rejectReads.get(key) || 0) + 1;
+            memory.rejectReads.set(key, n);
+            if (n >= 3) memory.rejectStuck.set(key, `step_4 attempt ${action.attempt} failed verification, but the rejects already used could not be read after ${n} polls; nothing was sent`);
+          }
+          for (const line of out.lines) say(line);
+          continue;
+        }
         if (action.kind === 'reserve') {
           if (!out.retry) {
             memory.reserved.set(action.storyId, { batchId: out.batchId, state: out.state });
@@ -697,4 +917,5 @@ module.exports = {
   EXIT, FORBIDDEN_FLAGS, NOT_A_GATE,
   breakerStop, isTerminal, priorVerdict, step4Action, buildArgs, buildReserveArgs, planTick, runTask, followBatch,
   currentStep4Attempt, verifiedStep4Attempt, draftBranch, reservedFrom, otherPause, stuckReason, gateEnforced, stepRank,
+  AUTO_REJECT_PREFIX, AUTO_REJECT_LIMIT, autoRejectCandidate, autoRejectDecision, autoRejectedAttempts,
 };

package/lib/block-grammar.js

@@ -74,6 +74,60 @@ function fencedSpans(text) {
   return { blocks, open: cur };
 }
 
+/**
+ * The inline code spans of ONE line, as ranges (HC-GF-341 rules, extracted by HC-GF-292 so there is ONE walker).
+ *
+ * CommonMark's rule, on a single line: a run of N backticks opens a span that closes at the next run of EXACTLY
+ * N backticks; a run with no equal-length closer on the line is literal text, masks nothing and does not stop the
+ * scan. OUTSIDE a span a backtick after an odd number of backslashes is escaped (it cannot open, nor be part of an
+ * opening run); INSIDE a span a backslash is only a character. A span never crosses a line break.
+ *
+ * LINEAR: the line is cut into backtick runs once, the runs of each length are listed in order, and an opener asks
+ * for the first later run of its length with a cursor that only moves forward. A backreference regex backtracks
+ * across every longer run and is quadratic on a line of mixed runs, and the line is agent-written text.
+ *
+ * `from`/`to` address `line`: [from, to) covers the delimiters too; the content is
+ * `line.slice(from + openLen, to - openLen)`.
+ *
+ * @returns {Array<{from:number, to:number, openLen:number}>} in ascending order, disjoint
+ */
+function inlineCodeSpans(line) {
+  const spans = [];
+  if (typeof line !== 'string' || line.indexOf('`') === -1) return spans;
+  const starts = [];
+  const lens = [];
+  for (let i = line.indexOf('`'); i !== -1;) {
+    let j = i + 1;
+    while (j < line.length && line.charCodeAt(j) === 96) j++;
+    starts.push(i);
+    lens.push(j - i);
+    i = line.indexOf('`', j);
+  }
+  const runsOfLength = new Map(); // length -> { at: ascending run indices, p: cursor }
+  for (let k = 0; k < starts.length; k++) {
+    let entry = runsOfLength.get(lens[k]);
+    if (!entry) { entry = { at: [], p: 0 }; runsOfLength.set(lens[k], entry); }
+    entry.at.push(k);
+  }
+  const closerFor = (width, after) => {
+    const entry = runsOfLength.get(width);
+    if (!entry) return -1;
+    while (entry.p < entry.at.length && entry.at[entry.p] <= after) entry.p++;
+    return entry.p < entry.at.length ? entry.at[entry.p] : -1;
+  };
+  for (let k = 0; k < starts.length;) {
+    let slashes = 0;
+    for (let q = starts[k] - 1; q >= 0 && line.charCodeAt(q) === 92; q--) slashes++;
+    const escaped = slashes & 1; // 1: the run's first backtick is a literal one
+    const width = lens[k] - escaped;
+    const closer = width > 0 ? closerFor(width, k) : -1;
+    if (closer === -1) { k++; continue; }
+    spans.push({ from: starts[k] + escaped, to: starts[closer] + lens[closer], openLen: width });
+    k = closer + 1;
+  }
+  return spans;
+}
+
 /**
  * A `file:` block as one regex: group 1 the fence, 2 the path, 3 the body.
  *
@@ -117,6 +171,7 @@ module.exports = {
   fenceWidth,
   closesFence,
   fencedSpans,
+  inlineCodeSpans,
   DIRECTIVE_RE,
   FILE_BLOCK_RE,
   EDIT_BLOCK_RE,