bareloop 0.8.0 → 0.10.0

package/types/planrun.d.ts

@@ -78,6 +78,42 @@
  * @returns {string} the labelled block, or '' when there is nothing to show
  */
 export function closeGapBlock(gap: string | null | undefined): string;
+/**
+ * What the NEXT attempt is told about the bound that cut the previous one.
+ *
+ * Two different bounds used to set the same bare `attemptBounded = roundIteration`
+ * and therefore render the same sentence. For a round-bound cutoff that sentence is
+ * true. For BA-11's deny streak it is false twice over — the rounds did NOT run out
+ * (the fence short-circuited the attempt with budget left), and the count it quotes
+ * is the cap, not what was spent — and it aims the worker at the READ BUDGET when the
+ * thing that stopped it was the FENCE. The reason was already recorded on the spine;
+ * nothing carried it to the one reader who could act on it.
+ *
+ * The denial note is MECHANICAL in the strict sense: it quotes the terminal the
+ * provider actually returned and names which bound fired. It invents nothing —
+ * no streak count and no denied path, because bare-agent's return (`error:
+ * 'denied:<tool>'`, loop.js) carries neither, and a number nobody measured is a
+ * bug with a confident voice. Every other cause keeps the frozen wording byte for
+ * byte: a wall-bounded attempt reads as a round bound exactly as it did before
+ * (and is unreachable anyway — the step head refuses to fund an attempt past the
+ * deadline, W-2), so this change can only ever speak where it has something true
+ * to add.
+ *
+ * The reason arrives ALREADY SCRUBBED (the capture seam in `mkWorker` runs it
+ * through the one `SECRET_PATTERNS` inventory), so this renderer only bounds it —
+ * and announces the trim with the repo's ONE marker rather than a second spelling
+ * of "this text was cut" (F90.2).
+ *
+ * @param {{iteration?: number|string|undefined, cause: string, reason: string|null}|null|undefined} bounded
+ *   the previous attempt's bound state, or nullish when it was not bounded
+ * @param {number} rounds the step's round bound, as quoted by the frozen sentence
+ * @returns {string|null} the note, or null when there is nothing to say
+ */
+export function boundedNote(bounded: {
+    iteration?: number | string | undefined;
+    cause: string;
+    reason: string | null;
+} | null | undefined, rounds: number): string | null;
 /**
  * The plan-drafting prompt: a schema DESCRIPTION built from the live validator
  * menus — never a copyable example (the drafter must author, not echo; the
@@ -252,12 +288,18 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   default; a caller supplies this to drive time deterministically (the same seam `createClock`
  *   already exposes — a run's terminal cannot otherwise be exercised without waiting out a cap
  *   whose floor is one close timeout).
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed leg
+ *   recorded on its own spine (`readResume`'s `restart.branch`, off the `work-branch`
+ *   event). With it the resume returns to the branch its own work is sitting on; without
+ *   it the deterministic name would collide with that very branch and the collision walk
+ *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
+ *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
- *   'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' |
- *   `step-red:<id>`
+ *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
+ *   'step-stalled' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -289,7 +331,15 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     } | null | undefined;
     spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
+    resumeBranch?: string | null | undefined;
 }): Promise<string>;
+/**
+ * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a
+ * provider string (`denied:<tool>` today, ~20 bytes), not a gap, so this is a
+ * backstop against a future terminal that arrives long — never an envelope the
+ * shipped path routinely rides through.
+ */
+export const BOUND_REASON_MAX: 200;
 export type CategorizedError = Error & {
     category?: string;
     lib?: string;

package/types/ralph.d.ts

@@ -272,6 +272,7 @@ export const CLOSE_ENV_DENY: Readonly<{
     prefixes: readonly string[];
     shape: RegExp;
 }>;
+export function stageGap(name: string, gap: string): string;
 export const GAP_KEEP_TRIM_MARKER: "more elided by the";
 /**
  * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the

package/types/reuse.d.ts

@@ -221,7 +221,7 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
  *   which is later and better evidence than the last event). Defaults to the last
  *   event's own timestamp — the last sign of life there is.
  * @returns {any} `{ started, approvalHash, specHash, patient, job, bridgeTries,
- *   perTryBudgetUsd, perTryWallMs, ended, endOutcome, greened, completed, tried,
+ *   perTryBudgetUsd, perTryWallMs, ended, endOutcome, wallDerivedHalt, greened, completed, tried,
  *   selectionCostUsd, selectionComplete, strayRounds, r1Missing, restart, deathAtKnown,
  *   spentUsd, spendComplete, carrySpentUsd, carrySpendComplete }`
  */

package/types/run.d.ts

@@ -83,6 +83,13 @@
  *   RUN's ("unlimited replanning launders thrash as adaptation"). It also rides onto this
  *   run's `job-start` as `priorReplans`, the declared-fold precedent `priorSpentUsd`
  *   already sets, so a resume OF a resume folds once. Absent is the cold path.
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed attempt
+ *   created and recorded on its own spine (`readResume`'s `restart.branch`). The branch
+ *   name is DERIVED from the signed spec and is therefore identical on every leg, so
+ *   without this the restart would collide with its own predecessor's branch and the
+ *   collision walk would mint a `-2` beside the work the resume exists to continue. The
+ *   fold's precedent exactly: the chain's state is DECLARED, never re-derived. Forwarded
+ *   verbatim to the plan flow; absent is the cold path.
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -92,10 +99,10 @@
  *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
- *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' | 'provider-red' |
+ *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -124,6 +131,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         count?: number;
         grantUsed?: boolean;
     } | null | undefined;
+    resumeBranch?: string | null | undefined;
     layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {

package/types/text.d.ts

@@ -33,3 +33,154 @@ export function priceOf(r: any): {
     costUsd: number | null;
     unpricedRounds: number;
 };
+/**
+ * The F6 tally over a list of PRICED CALLS — `priceOf`'s per-call read, summed.
+ *
+ * `knownUsd` carries the priced half explicitly and `costUsd` is the honest
+ * total: null the moment anything went unpriced, never the priced half wearing a
+ * complete coat. An EMPTY list is a complete $0 and not an unknown — nothing
+ * spent is a number somebody can act on.
+ * @param {{costUsd: number|null, unpricedRounds?: number}[]|null|undefined} entries
+ * @returns {{costUsd: number|null, knownUsd: number, spendComplete: boolean,
+ *   nullCostCalls: number, unpricedRounds: number}}
+ */
+export function tallyCalls(entries: {
+    costUsd: number | null;
+    unpricedRounds?: number;
+}[] | null | undefined): {
+    costUsd: number | null;
+    knownUsd: number;
+    spendComplete: boolean;
+    nullCostCalls: number;
+    unpricedRounds: number;
+};
+/**
+ * THE ONE MONEY-CEILING PREDICATE, for the same reason `priceOf` above is one:
+ * the authoring pipeline meters two populations of paid call in two different
+ * accumulators (the survey's `calls[]`, the declaration loop's cost book), and
+ * two hand-spelled answers to "am I over the ceiling?" is two instruments.
+ *
+ * It is asked BETWEEN metered calls and never inside one. A cap that binds
+ * mid-call kills the row before it can be graded — F45 measured that as 3 of 7
+ * launches lost and $5.82 unreadable.
+ *
+ * Three answers, and the order between the last two is load-bearing:
+ *   - NO CEILING → null, always. An absent cap is UNBOUNDED, and unbounded is a
+ *     visible operator choice, never a defaulted number nobody set (the
+ *     `maxWallMs` precedent). There is nothing to enforce, so unpriced spend
+ *     here is merely reported.
+ *   - KNOWN SPEND AT OR OVER THE CEILING → `cap-halt`, even when the total is
+ *     unknown. The breach is CERTAIN on the priced half alone — whatever the
+ *     unpriced remainder turns out to be, it can only be larger — so naming this
+ *     `pricing-red` would send the operator to fix a meter when the fact is that
+ *     the money is gone. At-or-over rather than over: the next call is the one
+ *     that breaches, and it is the one being decided.
+ *   - SPEND THAT CANNOT BE KNOWN → `pricing-red`. `?? 0` launders unknown into
+ *     $0 (F6) and a ceiling enforced against a laundered floor is not enforced
+ *     at all. If the spend cannot be seen the cap cannot govern it, and that is
+ *     its own stop rather than a silent pass.
+ *
+ * A MALFORMED ceiling is the one input it refuses rather than answers: `null` and
+ * an absent field mean UNBOUNDED, and they are the ONLY way to get there. Anything
+ * else that is not a finite number (`'2.50'`, `NaN`, `Infinity`) reading as
+ * unbounded would be F6's laundering in its ceiling form — a caller who set a cap
+ * getting a paid pipeline with nothing enforcing it, which is the exact collapse
+ * the ceiling exists to prevent, wearing the caller's own typo (PRD v1.62). The
+ * CLI's `parseCeiling` guards the FLAG; this guards the LIBRARY, and `authorClose`
+ * / `runAuthorScout` / `authorCloseForJob` are documented adopter seams. It THROWS
+ * rather than clamping, unlike the attempt caps beside it, because those axes have
+ * a safe direction to clamp toward and this one does not: every candidate default
+ * is either a number nobody set or the unbounded run the caller just declined.
+ * @param {{ceilingUsd: number|null|undefined, knownUsd: number, spendComplete: boolean}} o
+ * @returns {'cap-halt'|'pricing-red'|null}
+ * @throws {Error} when the ceiling is neither absent nor a finite number
+ */
+export function capStop({ ceilingUsd, knownUsd, spendComplete }: {
+    ceilingUsd: number | null | undefined;
+    knownUsd: number;
+    spendComplete: boolean;
+}): "cap-halt" | "pricing-red" | null;
+/**
+ * ONE raw model emission, ready to persist.
+ *
+ * Three things happen here and NONE of them is optional at a call site:
+ *   - the text goes through the ONE redactor (`redactSecrets`, over the ONE
+ *     `SECRET_PATTERNS` inventory). A raw is the single most likely record in
+ *     this system to carry a live credential: it is whatever a model read out
+ *     of a repository, verbatim, and it lands in a file that outlives the run;
+ *   - it is BOUNDED, and the bound ANNOUNCES itself with the full size (F28 —
+ *     a bound eats detail, never evidence). The cut is decoded rather than
+ *     sliced so a multi-byte character is never split in half;
+ *   - it carries its own address: which call produced it (`label`, the same
+ *     spelling the cost book meters under) and which attempt (`attempt`), plus
+ *     the typed failure that describes it when there is one.
+ *
+ * `cause`/`reason` are `null` when the emission was fine — an ABSENT failure is
+ * absent, never an empty string that reads like a diagnosis nobody wrote.
+ * @param {{label: string, attempt: number, text: unknown, cause?: string|null,
+ *   reason?: string|null, cap?: number}} o
+ * @returns {{label: string, attempt: number, bytes: number, trimmed: boolean,
+ *   text: string, cause: string|null, reason: string|null}}
+ */
+export function scrubRaw({ label, attempt, text, cause, reason, cap }: {
+    label: string;
+    attempt: number;
+    text: unknown;
+    cause?: string | null;
+    reason?: string | null;
+    cap?: number;
+}): {
+    label: string;
+    attempt: number;
+    bytes: number;
+    trimmed: boolean;
+    text: string;
+    cause: string | null;
+    reason: string | null;
+};
+/**
+ * Stamp a persisted raw with the verdict that DESCRIBES it — through the same
+ * boundary the raw's own text rode.
+ *
+ * It exists because the verdict is not known when the raw is created: a writer
+ * records the emission the moment the call returns (so a metered call can never
+ * be missing its output), and only classifies it afterwards. The obvious
+ * shape — assigning `cause`/`reason` onto the stored object at that later
+ * point — writes an UNSCRUBBED string into a record that is already past the
+ * one redactor, and `reason` is the worst field to do it to: it quotes the
+ * transport's own error prose, which nobody in this repo wrote and nobody
+ * bounds. So the stamp is a function, not an assignment, and `scrubRaw` renders
+ * its own two fields through it: ONE place decides how a diagnosis becomes
+ * persistable, exactly as ONE place decides it for the text.
+ *
+ * `cause` is enumerated (`SURVEY_CAUSES`) and passes through untouched; a mask
+ * over a closed set would only hide a bug in the set.
+ * @template {{cause: string|null, reason: string|null}} T
+ * @param {T} raw @param {{cause?: string|null, reason?: string|null}} o @returns {T}
+ */
+export function stampRaw<T extends {
+    cause: string | null;
+    reason: string | null;
+}>(raw: T, { cause, reason }: {
+    cause?: string | null;
+    reason?: string | null;
+}): T;
+/**
+ * The ceiling on ONE persisted raw. Sized to the survey's own prompt-ingredient
+ * cap (`AUTHOR_SCOUT_BLOB_MAX`, 8000) rather than picked: the largest raw this
+ * repository produces is a survey, the archive's real surveys ran 5991-8056
+ * bytes, and a record that cannot hold one whole specimen cannot answer the
+ * question it exists for. The two constants are deliberately independent
+ * numbers — one bounds a PROMPT, this one bounds a RECORD.
+ */
+export const RAW_PERSIST_MAX: 8000;
+/**
+ * The announced-trim marker for a persisted raw. A NEW spelling rather than a
+ * reuse of `GAP_TRIM_MARKER` ('gap trimmed:'), and that is a decision, not
+ * decoration: `src/root.js` READS `GAP_TRIM_MARKER` to mean *this gap was cut,
+ * so Layer R must not compare it*, so a second producer of those bytes in a
+ * different population is exactly the F90 hazard — a reader must know every
+ * producer of its marker. Nothing reads this one yet; it exists so the trim
+ * announces itself (F28) and so a future reader has an unambiguous key.
+ */
+export const RAW_TRIM_MARKER: "raw trimmed:";

package/types/validate.d.ts

@@ -86,16 +86,40 @@ export function sweepSecretLiterals(root: any, red: (code: string, path: string,
  * 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
@@ -106,10 +130,51 @@ export function sweepSecretLiterals(root: any, red: (code: string, path: string,
  *     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: string): boolean;
+/**
+ * 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: any, red: (code: string, path: string, detail?: string) => void): void;
 export const SECRET_PATTERNS: RegExp[];

package/types/workbranch.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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: any): string;
+/**
+ * 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 function prepareWorkBranch(workdir: string, { name, resume }: {
+    name: string;
+    resume?: string | null | undefined;
+}): Promise<{
+    stop: string;
+    branch: null;
+} | {
+    stop: null;
+    branch: string;
+    created: boolean;
+    resumed: boolean;
+    from: string | null;
+    base: string | null;
+    repo: string;
+    collided: number;
+}>;
+/** 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: RegExp;
+/** 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;