bareloop 0.10.0 → 0.11.0

package/types/declaredclose.d.ts

@@ -97,7 +97,8 @@ export function guardNames(closeDecl: any, verdictType: string): string[];
  * @param {any[]} stages declared stage descriptors, already validated
  * @param {(s: string) => string} [redact] the scrub, applied at THIS boundary
  * @param {{timeoutMs?: number, cwd?: string, seedRef?: string,
- *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree'}} [opts]
+ *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
+ *   humanRuling?: {decision: string, text?: string|null}|null}} [opts]
  * @returns {Promise<any>}
  */
 export function runDeclaredStages(stages: any[], redact?: (s: string) => string, opts?: {
@@ -108,6 +109,10 @@ export function runDeclaredStages(stages: any[], redact?: (s: string) => string,
     gapCap?: number;
     maxBuffer?: number;
     baselineMode?: "auto" | "worktree";
+    humanRuling?: {
+        decision: string;
+        text?: string | null;
+    } | null;
 }): Promise<any>;
 /**
  * The trend reader's input for ONE close verdict, whichever executor produced
@@ -160,11 +165,64 @@ export const DECLARED_GAP_PREFIX: "close: ";
  * it; because every declared line carries the prefix, it designates the stage's
  * whole judged output rather than a hand-picked slice of it. */
 export const DECLARED_GAP_KEEP: string;
-/** The verdict class a DECLARED close may claim. Hard, and by CONSTRUCTION
- * rather than by assertion: every live kind is a mechanical command whose
- * measurement is the truth, and the two judgment kinds are locked out at the
- * catalogue (M2) and absent from the executor (M1). Named as data so the job
- * validator reads one hierarchy table rather than hard-coding a class. */
+/**
+ * The close verdict word for a run WAITING on a person (N4 §1.3/§1.4). A
+ * literal, exported, because three readers key on it — the runner's pause
+ * branch, the ledger's excluded set, and the trend reader's blind rule — and
+ * three hand-spelled copies of one terminal is how they come to disagree.
+ *
+ * It is not in `CLOSE_FAULTS` and must never be added: a fault says the close
+ * could not render a verdict, and this says the close is not FINISHED rendering
+ * one. The first escalates; the second is a checkpoint the operator returns to.
+ */
+export const HUMAN_PAUSE: "human-pause";
+/**
+ * The RUN-level terminal names the hitl class mints one layer up from
+ * `HUMAN_PAUSE` (N4 §1.3–§1.5): the checkpoint, and the honest refusal of the
+ * operator's rerun input. Spelled once here, beside the close-verdict word they
+ * translate, for the same reason `HUMAN_PAUSE` is — the emitters (`planrun.js`),
+ * the ledger's excluded set, the resume reader (`reuse.js`), and the runner
+ * script all key on them, and hand-spelled copies of one terminal is how they
+ * come to disagree.
+ *
+ * There were three (2026-08-17): `hitl-cancel` was the signer's own terminal and
+ * is DELETED with the door it belonged to. A person who does not want to carry on
+ * now PAUSES — the same checkpoint, resumable, retired by the TTL if nobody comes
+ * back — so nothing in this tree mints that name any more. The ledger keeps the
+ * bare string in its excluded set so a spine written before this change still
+ * reads as governance rather than as a capability gap; that is a READER's
+ * backward compatibility, and deliberately not a constant a writer could reach.
+ */
+export const HITL_PAUSE: "hitl-pause";
+export const HITL_DECISION_RED: "hitl-decision-red";
+/**
+ * The terminals above that leave the run WAITING ON A PERSON — as a list, minted
+ * beside the names it holds so a reader keys on membership rather than on a
+ * spelling, and a rename here travels to every reader for free.
+ *
+ * It is deliberately NOT `reuse.js`'s `CHECKPOINT_OUTCOMES`, which is the wider
+ * RESUME list: every stop that left work on disk and an allowance unspent, money
+ * and time included. Those are governance stops the reuse loop is meant to try
+ * again under its remaining tries; this is the half no further attempt can
+ * change, because the allowance still unspent is a human answer. `CHECKPOINT_OUTCOMES`
+ * is composed FROM this list so the two can never disagree about which is which.
+ *
+ * `HITL_DECISION_RED` is not here: it is a verdict already rendered on the operator's
+ * own input, not a question still open.
+ */
+export const HUMAN_CHECKPOINTS: readonly string[];
+/** The verdict classes a DECLARED close may claim. Named as data so the job
+ * validator reads one hierarchy table rather than hard-coding a class.
+ *
+ * `hard` is by CONSTRUCTION: every mechanical kind is a command whose measurement
+ * is the truth. `hitl` joined it at N4 slice 1, and only because `human-confirms`
+ * is genuinely LIVE — the widening and the kind go in one commit, or this table
+ * admits a class the executor cannot render. The `soft` class is still absent:
+ * `judged-floor` is locked, so no declaration can reach above hitl.
+ *
+ * The direction that matters is unchanged. This says which class a declaration
+ * MAY claim; `closeCeiling` says which class its stages actually NEED. A pick
+ * below the ceiling is still the silent upgrade `class-ceiling` refuses. */
 export const DECLARED_CLOSE_CLASSES: readonly string[];
 export type Red = {
     code: string;

package/types/index.d.ts

@@ -8,13 +8,13 @@ export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEP
 export { snapshotScope, evalExits } from "./exits.js";
 export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists } from "./bridges.js";
 export { renderListing, selectionPrompt } from "./selection.js";
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate } from "./reuse.js";
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate } from "./reuse.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";
 export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from "./workbranch.js";
-export { runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees, LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP } from "./kinds.js";
-export { validateDeclaration, normalizeDeclaration, KIND_CATALOGUE, CATALOGUE_KINDS, CATALOGUE_LIVE_KINDS, LOCKED_KINDS, TYPES_GENRE, TYPES_GENRE_TEMPLATE, GENRE_LANGUAGES, genreEnv, genreOwnedEnvNames, genreInstruments, DIRECTIONS, BASELINES, MAX_STAGES, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, closeCeiling } from "./authoring.js";
+export { runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees, LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP, HUMAN_DECISIONS, SEED_EXEMPT_KINDS, normalizeHumanRuling } from "./kinds.js";
+export { validateDeclaration, normalizeDeclaration, KIND_CATALOGUE, CATALOGUE_KINDS, CATALOGUE_LIVE_KINDS, LOCKED_KINDS, TYPES_GENRE, TYPES_GENRE_TEMPLATE, GENRE_LANGUAGES, genreEnv, genreOwnedEnvNames, genreInstruments, DIRECTIONS, BASELINES, MAX_STAGES, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, closeCeiling, NEVER_OFFERED_KINDS } from "./authoring.js";
 export { runAuthorScout, buildSeedListing, seedFileList, classifySurvey, AUTHOR_SCOUT_VERBS, SCOUT_ATTEMPTS, SURVEY_CAUSES, SCOUT_RETRY_CAUSES } from "./authorscout.js";
 export { scrubRaw, RAW_PERSIST_MAX, RAW_TRIM_MARKER } from "./text.js";
 export { authorClose, authorPrompt, declarationSchema, makeLoopGenerate, MAX_REVISIONS, QUESTION_SETS, GREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor } from "./authorflow.js";
-export { validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade, DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS } from "./declaredclose.js";
+export { validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade, DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS, HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS } from "./declaredclose.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";

package/types/job.d.ts

@@ -158,6 +158,11 @@ export const LOCKED_TOOLS: readonly string[];
  * pattern: disclosure ≠ admission), so the ledger counts the demand and the
  * non-code rung later fills a declared slot instead of reshaping the schema. */
 export const VERDICT_TYPES: readonly string[];
+/** N4 slice 1: `hitl` is ADMITTED — the class whose *done* needs a person runs
+ * through the same signed spec, the same agent-authored plan and the same
+ * arbiter as a green job (the nine rulings, 2026-08-07; the three-button surface,
+ * 2026-08-12). `soft-green` stays declared-but-locked until its judged floor is
+ * built and proven (slice 2): a wobbly ruler must not mint anything. */
 export const LOCKED_VERDICTS: readonly string[];
 export const CADENCE_UNITS: readonly string[];
 /** SP-2: API-first; local deferred (PRD §5/§8). `clipipe-subscription` (F42,

package/types/kinds.d.ts

@@ -211,6 +211,30 @@ export function parseValue(output: string, terms: any[], { scope, workdir }?: {
  * @returns {SeedTrees}
  */
 export function makeSeedTrees(): SeedTrees;
+/**
+ * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
+ * of the three-button gate (2026-08-12 §1).
+ *
+ * `null` is not a refusal: no ruling at all IS the pause path, which is how every
+ * ordinary run and every first leg of a hitl run arrives here. What is refused is
+ * an answer that is not one of the three doors, and — the case the POC's negative
+ * control measured — a `rerun` with no text. Ruling 3 makes the human's words the
+ * gap the worker converts from; an empty one launches a fix worker that re-runs
+ * as though nothing had been said, which is the failure this refusal exists for.
+ *
+ * It never throws and never repairs: a decision that cannot be read is handed
+ * back as a refusal with its reason, and the caller decides what to do about it.
+ * @param {any} ruling
+ * @returns {{ok: boolean, ruling: {decision: string, text: string|null}|null, why: string|null}}
+ */
+export function normalizeHumanRuling(ruling: any): {
+    ok: boolean;
+    ruling: {
+        decision: string;
+        text: string | null;
+    } | null;
+    why: string | null;
+};
 /**
  * Run ONE declared stage against a workdir at a seed.
  *
@@ -254,13 +278,14 @@ export function seedRead(declaration: any, ctx: Ctx): Promise<StageResult[]>;
  * room would break a documented adopter contract for nothing; the new name says
  * exactly what differs. `src/declaredclose.js` is what bridges the two shapes.
  * @param {any} declaration @param {Ctx} ctx
- * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop', exitCode: number, judged: boolean, firstRed: string|null, stages: StageResult[]}>}
+ * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop'|'pause', exitCode: number|null, judged: boolean, firstRed: string|null, pausedAt: string|null, stages: StageResult[]}>}
  */
 export function runDeclaredClose(declaration: any, ctx: Ctx): Promise<{
-    verdict: "green" | "red" | "instrument-stop";
-    exitCode: number;
+    verdict: "green" | "red" | "instrument-stop" | "pause";
+    exitCode: number | null;
     judged: boolean;
     firstRed: string | null;
+    pausedAt: string | null;
     stages: StageResult[];
 }>;
 /** the close's two judgment exits — a stage's verdict, in the shape the
@@ -330,6 +355,28 @@ export const SIGNS: readonly number[];
  * counted demand (the request-red path), and reaching one at runtime is a
  * stop — never a red, and never a silent pass. */
 export const LIVE_KINDS: readonly string[];
+/** RULING 8 — the stages the seed-verdict read (D12) must NOT run. A judged
+ * number at seed is unstable and a person at seed is an interview, not a
+ * measurement; their bar comes from calibration (soft-green) or from the person
+ * themselves (hitl), never from the seed. The skip is RECORDED by name rather
+ * than taken in silence (F59: absent is not empty), so `seedRead` still returns
+ * one row per declared stage. */
+export const SEED_EXEMPT_KINDS: readonly string[];
+/** the one kind a PERSON renders — named once, because the runner keys three
+ * decisions on it (is there a door to answer, which stage paused, whose ruling
+ * this is) and three literals is how they come to disagree */
+export const HUMAN_KIND: "human-confirms";
+/** the three doors the signer is offered at a hitl pause (2026-08-12 §1, doors
+ * re-cut 2026-08-17). No fourth door, and no free-text-only variant: a red that
+ * is not one of these two is not a ruling the run can act on.
+ *
+ * `cancel` was the third door and is DELETED as a concept (hamr: *"what's the
+ * point of cancel anyways? pause can resume — that would be more honest"*). The
+ * case it served — a person who looks and does not want to carry on — is a pause
+ * nobody returns to, which the 60-day checkpoint TTL retires on its own. Nothing
+ * here forces a forever-decision at the one moment the person has least reason
+ * to make one. */
+export const HUMAN_DECISIONS: readonly string[];
 /**
  * The arbiter's book NAMES, one home. F98's mechanism was exactly this list
  * living as independent literals: the fence deny arrays (src/planrun.js,
@@ -356,6 +403,13 @@ export type Red = {
 /**
  * The arbiter's half of a stage run. Every field here is operator/runner
  * territory: a declaration parameterises kinds, never the contracts.
+ * `humanRuling` is the SIGNER's answer at a hitl pause, carried in from the
+ * runner — never authored, never defaulted, and absent on every ordinary run.
+ * `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
+ * toolchain per stage (a suite is the slow one) and a whole read is one opaque
+ * await, so the shell gets told as each stage lands. It decides nothing, it is
+ * never consulted, and no verdict depends on it — the house pattern is
+ * `runJob`'s `emit` (the library reports, the shell prints).
  */
 export type Ctx = {
     workdir: string;
@@ -366,9 +420,27 @@ export type Ctx = {
     gapCap?: number;
     maxBuffer?: number;
     seedTrees?: SeedTrees;
+    humanRuling?: {
+        decision: string;
+        text?: string | null;
+    } | null;
+    onStage?: (row: {
+        stage: string | null;
+        kind: string | null;
+        verdict: string;
+        durationMs: number;
+    }) => void;
 };
+/**
+ * Six outcomes, and only two of them are verdicts. `pause` is N4's fifth: the
+ * close reached a stage a machine cannot render and is WAITING on a person —
+ * neither green nor red, and never graded (the F17 forbidden-zone rule applied
+ * to a non-verdict). `skipped` is the sixth and says a stage was deliberately
+ * not run at THIS reading (ruling 8's seed exemption), which is a different
+ * fact from `not-reached` (an earlier stage decided first).
+ */
 export type StageResult = {
-    verdict: "green" | "red" | "instrument-stop" | "not-reached";
+    verdict: "green" | "red" | "instrument-stop" | "not-reached" | "pause" | "skipped";
     exitCode: number | null;
     value: number | null;
     baseline: number | null;

package/types/planrun.d.ts

@@ -294,12 +294,24 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   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.
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
+ *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
+ *   on the leg that pauses; it is never authored, never defaulted, and never inferred.
+ *
+ *   It is spent ONCE, on this leg's close readings up to the moment the fix loop opens:
+ *   `accept` greens the human stage on fresh evidence (OPEN-3 — the mechanical stages
+ *   re-run first, because the tree can change while a run is paused), `rerun` reds it
+ *   with the human's own words as the gap, and `pause` keeps the checkpoint exactly as it
+ *   is, before anything is read at all. After the fix loop opens the ruling is gone, so once the mechanical
+ *   stages pass again the run PAUSES for a second review rather than converting the same
+ *   sentence forever.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
- *   'step-stalled' | `step-red:<id>`
+ *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `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, resumeBranch }: {
+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, humanRuling }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -332,6 +344,10 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
     resumeBranch?: string | null | undefined;
+    humanRuling?: {
+        decision: string;
+        text?: string;
+    } | null | undefined;
 }): Promise<string>;
 /**
  * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a

package/types/reuse.d.ts

@@ -230,6 +230,43 @@ export function readResume(events: any[], { deathAt, direct, resumableOutcomes }
     direct?: boolean;
     resumableOutcomes?: string[];
 }): any;
+/**
+ * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it
+ * asks the other question a 60-day-old checkpoint raises. The tree gate asks
+ * *is this still the tree the run left?*; this asks *is this still a decision
+ * anyone is waiting on?*
+ *
+ * THREE things it deliberately does NOT do:
+ *
+ *  - it does not widen any other resume rule. The 2026-08-12 ruling is about a
+ *    person deciding, so `applies: false` on every other terminal: a cap-halt
+ *    checkpoint is a different stop under a different allowance, and quietly
+ *    ageing it out would be a governance change nobody ruled.
+ *  - it does not treat an unreadable stamp as young (F6). A checkpoint that
+ *    cannot say WHEN it paused has an unknown age, and unknown is refused rather
+ *    than rounded down to fresh — the direction that fails safe.
+ *  - it does not skip silently. An expired checkpoint comes back as a refusal
+ *    that NAMES the age and the TTL, because the operator's next move (start
+ *    fresh) depends on knowing which of the two it hit.
+ *
+ * The clock is injected for the same reason `runPlan`'s is: a rule measured in
+ * months cannot otherwise be tested at all.
+ *
+ * @param {any[]} events the paused run's own spine, parsed, in file order
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, applies: boolean, ageMs: number|null, ttlMs: number, pausedAt: string|null, detail: string|null}}
+ */
+export function checkpointAgeGate(events: any[], { now, ttlMs }?: {
+    now?: () => number;
+    ttlMs?: number;
+}): {
+    ok: boolean;
+    applies: boolean;
+    ageMs: number | null;
+    ttlMs: number;
+    pausedAt: string | null;
+    detail: string | null;
+};
 /**
  * The PATIENT gate for a resume, which is deliberately NOT the fresh-launch one.
  *
@@ -384,6 +421,43 @@ export function runReuse(opts: {
  *    started.
  */
 export const REUSE_GRADED_RED: readonly string[];
+/**
+ * WHICH TERMINALS ARE A CHECKPOINT — the list a runner hands `readResume` as
+ * `resumableOutcomes`, minted HERE rather than in whichever script happens to
+ * launch a run.
+ *
+ * `readResume` deliberately takes it as a parameter and defaults to empty, and
+ * that stays true: the reuse loop's own semantics depend on the empty default.
+ * What did not exist was a canonical ANSWER, so `scripts/run-u.mjs` kept its own
+ * copy — and the exported bundle (PRD v1.44 §2: a thin runner with bareloop as a
+ * dependency) would have had to keep a third. The same reasoning that put the
+ * pause TTL in the library (OPEN-2, hamr, 2026-08-13) puts this here.
+ *
+ * Every entry is a stop that left WORK ON DISK and an allowance unspent — money,
+ * time, a self-healed stall, and now a person who has not answered yet. A verdict
+ * already rendered is never on this list: `green`/`escalated` are graded rows, and
+ * re-buying one would pay twice for an answer already in hand. (The signer's own
+ * `hitl-cancel` terminal used to be the other example; the door was deleted on
+ * 2026-08-17 — a person who does not want to carry on pauses, and the checkpoint
+ * they keep is retired by the TTL rather than by a terminal.)
+ *
+ * The human half is SPLICED IN from `declaredclose.js` rather than spelled again,
+ * because the try loop below reads the two halves differently and a second copy is
+ * how they would come to disagree about which member is which: the first three are
+ * allowances the loop's remaining tries are meant to spend against, and the human
+ * ones are the stop no further try can change (see `hardStop`).
+ */
+export const CHECKPOINT_OUTCOMES: readonly string[];
+/**
+ * THE PAUSE TTL (2026-08-12 §2): a hitl checkpoint is kept for 60 days.
+ *
+ * OPEN-2, RULED (hamr, in-turn, 2026-08-13): **the TTL lives in the LIBRARY**, so
+ * the exported bundle (a headless runner with bareloop as a dependency, PRD v1.44
+ * §2) inherits it instead of every runner re-implementing it. A script-only TTL
+ * would vanish on export — the one place the rule is most needed and least
+ * likely to be re-typed.
+ */
+export const PAUSE_TTL_MS: number;
 export type Red = {
     code: string;
     path: string;

package/types/run.d.ts

@@ -97,12 +97,18 @@
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
+ *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
+ *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
+ *   done?" is the rubber-stamp the class exists to prevent, 2026-08-12 §4).
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'hitl-pause' | 'hitl-decision-red' | `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, resumeBranch }: {
+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, humanRuling }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -133,6 +139,10 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     } | null | undefined;
     resumeBranch?: string | null | undefined;
     layerRoot?: boolean | undefined;
+    humanRuling?: {
+        decision: string;
+        text?: string;
+    } | null | undefined;
 }): Promise<string>;
 export type Red = {
     code: string;