bareloop 0.8.0 → 0.10.0

package/src/validate.js

@@ -177,6 +177,69 @@ function unboundedQuantLen(src, i) {
   return len;
 }
 
+/** How many characters of `(`-prologue sit at `src[i]` before the group's BODY:
+ * 1 for a plain or capturing group, 3 for `(?:` `(?=` `(?!`, 4 for `(?<=` `(?<!`,
+ * and past the `>` of a named group `(?<name>`. The body is read back when the
+ * group closes, and a prologue counted as body text would make `(?:a|aa)` split
+ * as `?:a` / `aa` — no prefix relation, and the hazard read as safe.
+ * @param {string} src @param {number} i index of the `(` */
+function groupPrologueLen(src, i) {
+  if (src[i + 1] !== '?') return 1;
+  const c = src[i + 2];
+  if (c === ':' || c === '=' || c === '!') return 3;
+  if (c === '<') {
+    if (src[i + 3] === '=' || src[i + 3] === '!') return 4;   // lookbehind
+    const close = src.indexOf('>', i + 3);                    // named group
+    return close === -1 ? 3 : close - i + 1;
+  }
+  return 1;                                                    // modifier groups etc — read the lot as body (fail-safe)
+}
+
+/**
+ * Do a group body's TOP-LEVEL alternation branches overlap — is one a prefix of
+ * another, equality included? That is the practical detectable core of the
+ * overlapping-alternation blowup (`(a|aa)`, `(a|a)`, `(\d|\d\d)`, `(a|a?)`):
+ * two branches that can consume the same text give the engine two ways to reach
+ * the same position, and an unbounded repeat multiplies them.
+ *
+ * The comparison is over the branches' SOURCE TEXT, which is what makes it
+ * conservative rather than exact — `(ab|abc)+` carries the prefix relation and
+ * did not blow up on the body measured. Exactness needs the real regex engine
+ * F49 declined to take as a dependency, and guessing it wrong would ADMIT an
+ * exponential pattern, so the over-rejection stands as a named limit.
+ *
+ * Splitting respects escapes, character classes and nested groups: a `|` inside
+ * `[a|b]` or inside `(x|y)` is not this group's alternation, and treating it as
+ * one would invent branches nobody wrote.
+ * @param {string} body the text between a group's prologue and its `)`
+ * @returns {boolean}
+ */
+function altBranchesOverlap(body) {
+  /** @type {string[]} */
+  const branches = [];
+  let start = 0;
+  let depth = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '\\') { i++; continue; }
+    if (c === '[') { i++; if (body[i] === '^') i++; while (i < body.length && body[i] !== ']') { if (body[i] === '\\') i++; i++; } continue; }
+    if (c === '(') { depth++; continue; }
+    if (c === ')') { depth--; continue; }
+    if (c === '|' && depth === 0) { branches.push(body.slice(start, i)); start = i + 1; }
+  }
+  if (branches.length === 0) return false;                    // no top-level alternation at all
+  branches.push(body.slice(start));
+  for (let i = 0; i < branches.length; i++) {
+    for (let j = 0; j < branches.length; j++) {
+      // `startsWith` covers EQUALITY, which is the 2ⁿ case: `(a|a)+$` took 52.3s
+      // on a 27-character body. Skipping i===j is what keeps that from being
+      // every pattern's own reflexive match.
+      if (i !== j && branches[j].startsWith(branches[i])) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * F49 — a heuristic reject for the catastrophic-backtracking footgun: an
  * unbounded quantifier applied to a group whose body itself repeats unboundedly
@@ -201,16 +264,40 @@ function unboundedQuantLen(src, i) {
  * So the reject targets the dominant exponential class and fails it as a
  * mechanical gap at the validation gate, before any tokens burn. A full ReDoS
  * analyzer needs a real regex engine (an external native dep we do not take for
- * a LOW issue); exotic overlapping-alternation blowup is out of scope by
- * decision (PARKED to the close-authoring rung — PRD v1.55).
+ * a LOW issue).
+ *
+ * SECOND CLASS, added 2026-08-12 — OVERLAPPING ALTERNATION under an unbounded
+ * repeat (`(a|aa)+`, `(a|a)+`, `(\d|\d\d)*`). F49 recorded this as a genuine
+ * false NEGATIVE of the shape approach and PARKED the widening, because changing
+ * the detector changes which SIGNED specs are admissible. It is closed here on
+ * measurement, one fresh process per point (a hot RegExp tiers up out of the V8
+ * interpreter, and a single-process sweep read a LONGER body as faster —
+ * backwards for an exponential, and the harness rather than the regex).
+ * `(a|aa)+$` against a run of `a` with one non-matching tail character:
+ *
+ *     27ch 218ms · 31ch 1,879ms · 35ch 12,082ms · 39ch 52,563ms · 41ch 189,420ms
+ *
+ * ~6.8× per 4 characters — the Fibonacci decomposition count, φ⁴. `(a|a)+$` (the
+ * 2ⁿ equal-branch case) took 52,256ms on 27ch, and `((a|aa))+$` — the redundant
+ * wrapper the `((a+))+` entry above exists for — 15,426ms on 35ch, which is why
+ * the overlap propagates up through a wrapper exactly as the inner repeat does.
+ * Input-bounding is theater here for F49's own reason: tens of characters suffice.
+ *
+ * The detected core is the PREFIX RELATION between top-level branches (one branch
+ * a prefix of another, equality included — `(a|a)+` is the 2ⁿ case). Whether a
+ * given prefix overlap can actually be DRIVEN exponentially depends on what
+ * follows the group, and deciding that needs the real engine this file declined
+ * to take as a dependency — so the reject is conservative by construction, which
+ * is the fail-safe direction.
+ *
+ * MONOTONIC, and that is the rule this change lives under: it only ever ADDS
+ * rejections. Nothing above is narrowed, and no previously-rejected shape became
+ * admissible (asserted over the whole corpus in tests/plan.test.js). F49's
+ * "never sharpen the detector" bars chasing false POSITIVES; closing a false
+ * NEGATIVE by adding rejections is the opposite, allowed direction — distinct
+ * rules, not in tension (the `((a+))+` widening set the precedent).
  *
  * SCOPE IS ASYMMETRIC, both directions named on purpose:
- *   - false NEGATIVE: overlapping-alternation blowup (`(a|ab)+`-class) is not
- *     detected — there is no inner QUANTIFIER to find, so the shape scan cannot
- *     see it; the blowup comes from overlapping alternation BRANCHES under a
- *     repeat. A genuine limit of the approach, not a bug in it. Widening the
- *     detector changes which SIGNED specs are admissible, which is
- *     arbiter-adjacent — parked, not chased (PRD v1.55).
  *   - false POSITIVE: a group whose repetitions are disambiguated by a literal
  *     anchor/delimiter (`(?:^- .+$\n?)+`, `(?:CHANGELOG:.+\n)+`) is FLAGGED even
  *     though a real engine runs it linearly — the scan sees the nested-quantifier
@@ -221,13 +308,28 @@ function unboundedQuantLen(src, i) {
  *     and guessing it wrong would ADMIT an exponential pattern — so the shape
  *     reject stands, and the over-rejection is a named, accepted limitation.
  *
+ *     The alternation class has its OWN instance of the same limit, measured and
+ *     locked in `REDOS_OVERREJECTED_ALT`: `(ab|abc)+$`, `(x|xy|xyz)+$` and
+ *     `(x(a|aa))+$` carry the prefix relation and did NOT blow up on the bodies
+ *     measured (0.3–0.4ms at 41–91 characters). "Did not blow up on the body
+ *     measured" is the honest claim — no adversarial search was run for a worse
+ *     input — and rejecting them is again the direction that never admits an
+ *     exponential pattern.
+ *
  * The input is guaranteed to compile as a RegExp (checked first by the caller),
  * so this scan assumes valid, balanced JS regex syntax.
  * @param {string} src a compiled regex source string
- * @returns {boolean} true iff a nested unbounded quantifier is present
+ * @returns {boolean} true iff a nested unbounded quantifier, or an unboundedly
+ *   repeated group with overlapping alternation branches, is present
  */
 export function hasNestedQuantifier(src) {
-  /** @type {{ quant: boolean }[]} */
+  /** `quant`: the body repeats unboundedly. `alt`: the body (or a group beneath
+   * it) carries overlapping alternation branches. `at`: where the body starts,
+   * so the branches can be read back when the group closes. The two hazard flags
+   * are tracked separately and propagate separately — merging them would let a
+   * plain nested repeat be reported as an alternation overlap and vice versa,
+   * and the two are different rewrites for the author. */
+  /** @type {{ quant: boolean, alt: boolean, at: number }[]} */
   const stack = [];
   for (let i = 0; i < src.length; i++) {
     const c = src[i];
@@ -254,11 +356,19 @@ export function hasNestedQuantifier(src) {
       while (i < src.length && src[i] !== ']') { if (src[i] === '\\') i++; i++; }
       continue;
     }
-    if (c === '(') { stack.push({ quant: false }); continue; }
+    if (c === '(') { stack.push({ quant: false, alt: false, at: i + groupPrologueLen(src, i) }); continue; }
     if (c === ')') {
       const g = stack.pop();
       const qlen = unboundedQuantLen(src, i + 1);
       if (g && g.quant && qlen) return true;    // group repeats unboundedly AND its body did too
+      // …and the SECOND class: the body's own top-level branches overlap, so the
+      // engine has more than one way to consume the same text and an unbounded
+      // repeat multiplies those ways (MEASURED: `(a|aa)+$` 12.1s on a 35-char
+      // body). `g.alt` carries an overlap found in a group BENEATH this one, for
+      // the redundant-wrapper reason one comment down.
+      const overlap = !!g && (g.alt || altBranchesOverlap(src.slice(g.at, i)));
+      if (overlap && qlen) return true;
+      if (overlap && stack.length) stack[stack.length - 1].alt = true;
       // The group is an unbounded-repeated atom of its parent when it is directly
       // re-quantified (qlen) OR its own body already repeats unboundedly (g.quant):
       // a redundant wrapper — ((a+))+ , (?:(a+))* , (((\d*)))+ — is the SAME
@@ -276,3 +386,50 @@ export function hasNestedQuantifier(src) {
   }
   return false;
 }
+
+/**
+ * The catastrophic-backtracking reject, applied to a WHOLE signed document by
+ * tree walk — `sweepSecretLiterals`'s twin, and for its reason: some signed
+ * documents carry their regexes at a depth no per-field check enumerates.
+ *
+ * WHY IT EXISTS (PRD v1.60 §1, an OPEN GAP now closed). v1.55 took F49's reject
+ * to the operator's own regex fields, and the admissibility sweep that backed it
+ * walked `jobs/*.json`. That is not the population of signed specs: a REGISTRY
+ * BRIDGE is signed the same way, ships its plans VERBATIM (reuse stores the
+ * whole plan, never a template), and lives outside `jobs/`, so a pathological
+ * pattern arriving through a bridge was never swept. Nothing had decided
+ * bridge-borne patterns were safe — the sweep was written against the directory
+ * that held every spec at the time and was never re-aimed.
+ *
+ * WHAT is rejected is UNCHANGED: `hasNestedQuantifier`, one inventory, shared
+ * with job.js and plan.js. Only WHERE it looks is wider. Widening the DETECTOR
+ * is arbiter-adjacent and stays parked (F49); widening the POPULATION is this.
+ *
+ * KEY-SCOPED, deliberately. `pattern` and `gapKeep` are the exactly-three regex
+ * fields F49 names (`artifact-written.pattern`, `judged.pattern`, `gapKeep`);
+ * every other string in a signed document is prose, a path or a command, and
+ * running a regex-shape scan over prose would red goals for containing `(a+)+`
+ * in a sentence. A field carrying a regex under a NEW key is not swept until
+ * this list names it — stated so the limit is read rather than rediscovered.
+ *
+ * COMPILE-FIRST, like both per-field callers: the scan's contract is that its
+ * input is valid regex syntax, and a string that does not compile is the OTHER
+ * validator's red. Two reds on one string bury the real one.
+ * @param {any} root
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+export function sweepNestedQuantifiers(root, red) {
+  (/** @type {(node: any, at: string, key: string) => void} */
+  function sweep(node, at, key) {
+    if (typeof node === 'string') {
+      if (key !== 'pattern' && key !== 'gapKeep') return;
+      try { new RegExp(node, 'm'); } catch { return; }
+      if (hasNestedQuantifier(node)) {
+        red('invalid-value', at, `catastrophic-backtracking risk: a nested unbounded quantifier (${node}) can hang the untimed evaluator on the MAIN event loop, where the in-process stall fuse cannot fire (F49). Rewrite the pattern — drop the outer repeat, or match once.`);
+      }
+      return;
+    }
+    if (Array.isArray(node)) node.forEach((v, i) => sweep(v, `${at}.${i}`, key));
+    else if (isObj(node)) for (const [k, v] of Object.entries(node)) sweep(v, at ? `${at}.${k}` : k, k);
+  })(root, '', '');
+}

package/src/workbranch.js

@@ -0,0 +1,261 @@
+// THE WORK BRANCH — runner mechanics, arbiter side. PRD Addendum v1.57 §3,
+// hamr's ruling verbatim:
+//
+//   "The agent creates a NEW BRANCH before it touches any code — a HARD RULE, no
+//    exceptions. Not a default, not a preference: no job edits the branch it was
+//    handed, and none edits `main`. Blast radius is bounded by where the work
+//    lands, not only by what the fence allows. Named with a meaningful slug —
+//    tool and problem, human-readable, of the form `bareloop-typecheck-fix`. A
+//    human scanning `git branch` must be able to tell what the run was for
+//    without opening the spec, which a run-id slug does not give them."
+//
+// WHAT IT IS AND IS NOT, stated here rather than left to be inferred (v1.57's own
+// known-limitations discipline). bareloop never commits: the run leaves its work
+// in the tree. So the guarantee this module actually delivers is precise —
+//
+//   * the run's tree is standing on a branch NOBODY handed it, from the first
+//     moment a write-capable worker can exist to the end of the run, and
+//   * the handed ref (`main`, or whatever was checked out) is never moved,
+//     never written through, and never the thing a later commit attaches to.
+//
+// It is NOT containment: v1.41's local-trust model stands untouched, and a close
+// or worker child can still reach anything the operator's OS user can reach. The
+// branch bounds where the work LANDS. That is the whole claim.
+//
+// THE NAME IS OURS, NEVER THE MODEL'S. A branch name is arbiter bookkeeping: it
+// says which history a run's blast radius belongs to. A model-authored one would
+// be the agent authoring the arbiter's own books, so the name is DERIVED,
+// mechanically and deterministically, from the SIGNED spec's own `job` field
+// (see `workBranchName`).
+//
+// WHY THIS FILE OWNS ITS OWN git SEAM. `src/kinds.js` has one too, and its
+// docstring says what it is: "git, read-only, in a repository" — the CLOSE's
+// measuring instrument, whose faults are close faults. This one MUTATES the
+// repository (it creates and checks out a ref) and its faults are runner
+// instrument stops before a single token is bought. Two verbs, two failure
+// vocabularies, two owners; the read-only one is not exported and could not be
+// shared without widening it into a write seam.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/** Every work branch carries it. It is what makes `main`, `master` and every
+ * branch a human could plausibly have handed the run INEXPRESSIBLE as a work
+ * branch name — a structural guarantee rather than a denylist somebody has to
+ * keep current. */
+export const WORK_BRANCH_PREFIX = 'bareloop-';
+
+/** The full legal shape of a work branch. Deliberately narrower than git's own
+ * `check-ref-format`: the kebab alphabet the job validator already holds every
+ * spec slug to (`src/job.js` SLUG_RE), plus the prefix. Everything git forbids —
+ * `..`, `@{`, a trailing `.lock`, a leading `-`, a `/` component, control
+ * characters — is unreachable inside it, so ref-safety is a property of the
+ * alphabet and never a sanitiser somebody has to remember to call. */
+export const WORK_BRANCH_RE = /^bareloop-[a-z0-9][a-z0-9-]*$/;
+
+/** The slug's ceiling, before any collision suffix. A ref component has a
+ * filesystem-length limit and a human scanning `git branch` has a much smaller
+ * one; 60 characters is longer than every job slug in `jobs/` and short enough
+ * to read in a column. */
+export const MAX_SLUG_LEN = 60;
+
+/** How far the collision walk goes before it STOPS and says so. A run that
+ * cannot find a free name in this many attempts is looking at a patient nobody
+ * has swept in a very long time, and silently walking to `-500` would be the
+ * runner papering over an operator problem. */
+export const MAX_BRANCH_COLLISIONS = 50;
+
+/** git, in a repository, WRITE-CLASS. A non-zero exit is a value, never a throw:
+ * every caller here decides for itself whether git refusing is a stop.
+ * @param {string} cwd @param {string[]} args
+ * @returns {Promise<{ok: boolean, out: string, err: string}>}
+ */
+async function git(cwd, args) {
+  try {
+    const { stdout, stderr } = await exec('git', args, {
+      cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 1024 * 1024,
+    });
+    return { ok: true, out: String(stdout ?? ''), err: String(stderr ?? '') };
+  } catch (e) {
+    const err = /** @type {any} */ (e);
+    // A spawn failure (no git on PATH, cwd does not exist) has no streams at all;
+    // its `message` is the only thing there is to report, and reporting nothing
+    // would turn "git is not installed" into a mysterious silent refusal.
+    const detail = String(err?.stderr ?? '').trim() || String(err?.message ?? err).trim();
+    return { ok: false, out: String(err?.stdout ?? ''), err: detail };
+  }
+}
+
+/**
+ * The spec's own words, reduced to the kebab alphabet. Lossy on purpose: the
+ * output alphabet IS the ref-safety guarantee, so anything outside it collapses
+ * to a separator rather than being escaped into something clever.
+ * @param {unknown} s
+ * @returns {string} `''` when nothing usable survives
+ */
+function slugify(s) {
+  return String(s ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+/, '')
+    .slice(0, MAX_SLUG_LEN)
+    .replace(/-+$/, '');
+}
+
+/**
+ * The branch name a job's run works on, DERIVED from the signed spec.
+ *
+ * **The source is `spec.job`, and the choice is load-bearing.** It is the one
+ * human-authored, REQUIRED, kebab-case name the spec carries; it is inside the
+ * spec hash, so the branch name cannot drift from what the operator signed; and
+ * it is stable across a resume and across a cold re-run of the same spec, which
+ * is precisely why the collision walk below has to exist. In practice it already
+ * reads as tool-and-problem (`bareagent-u-types`, `litectx-u-types`), which is
+ * the shape hamr's ruling asks for.
+ *
+ * **The goal prose was REJECTED as a source**, and not for tidiness: a goal is
+ * long, is edited freely between runs without changing what the job IS, and
+ * opens on boilerplate ("An existing pytest test suite for the SOAR
+ * orchestrator…"). Deriving from it would make the branch name unstable under
+ * edits that change nothing, and unreadable when it was stable. A run id was
+ * rejected by the ruling itself.
+ *
+ * Deterministic, pure, and total: any input yields a name matching
+ * `WORK_BRANCH_RE`, so a caller never has to check.
+ * @param {any} spec a job-v1 spec (validated or raw)
+ * @returns {string}
+ */
+export function workBranchName(spec) {
+  const slug = slugify(spec?.job);
+  // `job` is REQUIRED and kebab-validated by `validateJob`, which runs before the
+  // runner ever reaches here — so the fallback is unreachable through `runJob`.
+  // It exists because this function is exported and total: a name is the wrong
+  // thing to throw about, and `bareloop-job` is honest ("a bareloop job") rather
+  // than invented.
+  return `${WORK_BRANCH_PREFIX}${slug || 'job'}`;
+}
+
+/** does a local branch of this name exist? @param {string} cwd @param {string} name */
+async function branchExists(cwd, name) {
+  const r = await git(cwd, ['show-ref', '--verify', '--quiet', `refs/heads/${name}`]);
+  return r.ok;
+}
+
+/**
+ * Put the run on its OWN branch, before it can touch any code.
+ *
+ * The three shapes, and each one's honest answer:
+ *
+ *  - **Cold.** `name` is free → create it at HEAD and switch. The handed branch
+ *    keeps its ref and its history; a new branch at HEAD moves no commit, so this
+ *    costs the patient nothing and changes nothing it can measure (the declared
+ *    close's seed is HEAD either way).
+ *  - **Cold, and the name is taken.** Suffix `-2`, `-3`… until one is free.
+ *    Deterministic given the repository, and it NEVER reuses another run's
+ *    branch — a second run of the same spec is a second blast radius.
+ *  - **Resume.** `resume` names the branch the killed leg recorded on its own
+ *    spine. It is checked out, never re-created and never suffixed: the work the
+ *    operator already paid for is sitting on it, and minting `-2` beside it would
+ *    strand exactly the progress a resume exists to keep. A `resume` branch that
+ *    is GONE is a STOP, never a silent fresh start — the run would be grading a
+ *    tree whose history it does not own.
+ *
+ * **Every failure is a stop with a name.** Not a git repository, no git on PATH,
+ * a checkout git refuses, a crowded namespace, a resume branch a human deleted:
+ * each comes back as `stop` and `branch: null`. There is no fallback to "just
+ * work on whatever was handed to us" anywhere in this function, because that
+ * fallback IS the thing the hard rule forbids.
+ *
+ * A DETACHED head is not a failure. Creating a branch from it is exactly the
+ * bounding the rule asks for (and it attaches a head that was floating), so it
+ * succeeds with `from: null` — there was no branch to be handed, and the record
+ * says so rather than inventing one.
+ *
+ * @param {string} workdir the patient (the fence's root)
+ * @param {object} o
+ * @param {string} o.name the derived name (`workBranchName`); refused unless it
+ *   matches `WORK_BRANCH_RE`, which is what makes `main` unreachable even from a
+ *   hand-passed argument
+ * @param {string|null} [o.resume] RESUME — the branch this run already owns
+ * @returns {Promise<{stop: string, branch: null}
+ *   | {stop: null, branch: string, created: boolean, resumed: boolean, from: string|null, base: string|null,
+ *      repo: string, collided: number}>}
+ */
+export async function prepareWorkBranch(workdir, { name, resume = null }) {
+  const wanted = String(name ?? '');
+  if (!WORK_BRANCH_RE.test(wanted)) {
+    return { stop: `the work branch name ${JSON.stringify(wanted)} is not a bareloop work branch (${WORK_BRANCH_RE.source}) — a run never works on a branch it was handed`, branch: null };
+  }
+
+  // Is there a repository at all? Asked FIRST and by its own question, so "this
+  // patient is not a git checkout" reads as itself instead of arriving later
+  // disguised as a checkout failure.
+  //
+  // `--show-toplevel` rather than `--git-dir`, and the answer is REPORTED: git
+  // resolves upwards, so a workdir that is a SUBDIRECTORY of a repository gets a
+  // branch in that enclosing repository — a blast radius wider than the operator
+  // handed over. That is the pre-existing semantics of every other git read in
+  // the flow (`seedAtHead`, `changedSet`), so it is not changed here; what it must
+  // not be is invisible, and the record names the repository that got the branch.
+  const inside = await git(workdir, ['rev-parse', '--show-toplevel']);
+  if (!inside.ok) {
+    return { stop: `the work branch cannot be created in ${workdir}: ${inside.err || 'not a git repository'}`, branch: null };
+  }
+  const repo = inside.out.trim().split('\n')[0].trim() || workdir;
+
+  // WHERE the run was handed. A symbolic HEAD names the handed branch; a detached
+  // one names nothing, and `null` is the honest reading of that (never the string
+  // "HEAD", which a reader cannot tell from a branch called HEAD).
+  const sym = await git(workdir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const from = sym.ok ? sym.out.trim() || null : null;
+  const rev = await git(workdir, ['rev-parse', 'HEAD']);
+  const base = rev.ok ? (rev.out.trim().split('\n')[0].trim() || null) : null;
+
+  if (resume !== null && resume !== undefined) {
+    const own = String(resume);
+    if (!WORK_BRANCH_RE.test(own)) {
+      return { stop: `the recorded work branch ${JSON.stringify(own)} is not a bareloop work branch (${WORK_BRANCH_RE.source}) — this resume would continue on a branch the run does not own`, branch: null };
+    }
+    if (!await branchExists(workdir, own)) {
+      return { stop: `the work branch ${JSON.stringify(own)} this run was killed on no longer exists in ${workdir} — the resume stops rather than starting a new branch beside work it cannot see`, branch: null };
+    }
+    // Already standing on it (the ordinary case — a kill leaves the tree where it
+    // was) is a NO-OP, deliberately: `git checkout` onto the current branch is
+    // harmless today, and not running it at all is what keeps a dirty in-flight
+    // tree out of git's hands entirely.
+    if (from !== own) {
+      const co = await git(workdir, ['checkout', own]);
+      if (!co.ok) return { stop: `could not return to the work branch ${JSON.stringify(own)} in ${workdir}: ${co.err}`, branch: null };
+    }
+    return { stop: null, branch: own, created: false, resumed: true, from, base, repo, collided: 0 };
+  }
+
+  // The collision walk. `-2` is the first suffix rather than `-1`, so the branch a
+  // human reads without a number is the first run and the numbers count runs the
+  // way a person does.
+  //
+  // CHECK-THEN-ACT, named rather than fixed: another process can create the
+  // candidate between the `branchExists` read and the `checkout -b` below. It is
+  // documented instead of closed because git already fails CLOSED on it — `git
+  // checkout -b` REFUSES an existing branch, so the race ends in the named stop
+  // right beneath this loop, never in two runs sharing one blast radius. Closing
+  // it properly means atomic ref creation, which is a wider change than the
+  // failure it would prevent.
+  let collided = 0;
+  let candidate = wanted;
+  while (await branchExists(workdir, candidate)) {
+    collided += 1;
+    if (collided >= MAX_BRANCH_COLLISIONS) {
+      return { stop: `every work-branch name from ${JSON.stringify(wanted)} through ${JSON.stringify(`${wanted}-${MAX_BRANCH_COLLISIONS}`)} is already taken in ${workdir} — sweep the patient's old work branches rather than letting the runner walk further`, branch: null };
+    }
+    candidate = `${wanted}-${collided + 1}`;
+  }
+
+  const co = await git(workdir, ['checkout', '-b', candidate]);
+  if (!co.ok) {
+    return { stop: `could not create the work branch ${JSON.stringify(candidate)} in ${workdir}: ${co.err}`, branch: null };
+  }
+  return { stop: null, branch: candidate, created: true, resumed: false, from, base, repo, collided };
+}