bareloop 0.29.0 → 0.31.0

package/src/userrun.js

@@ -30,6 +30,7 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync, spawn } from 'node:child_process';
 import { join, resolve, dirname } from 'node:path';
 import { runJob } from './run.js';
+import { moneyWithDraft } from './replay.js';
 import { jobSpecHash, resolveWorkerModel, validateJob } from './job.js';
 import { readShimArm } from './readshim.js';
 import { closeStagesOf } from './plan.js';
@@ -242,6 +243,15 @@ class ExitSignal extends Error {
  * @property {string|null} [model] the raw `--model` tier name (`sonnet`/`haiku`), or null for the default
  * @property {string|null} [readShim] the raw `--read-shim` arm name, or null for the default
  * @property {string|null} [scout] the raw `--scout` value (`on`/`off`), or null for the default
+ * @property {string|null} [draftSpentUsd] the raw `--draft-spent-usd` value (hamr's
+ *   ruling 2026-09-28, "one cap covers drafting + run"), or null when the job never
+ *   drafted through the panel/`bareloop author`. Parsed and validated in `execute`
+ *   (finite, >= 0, else refused) — never coerced silently, the same param-guard
+ *   class `--read-shim`/`--scout` already are.
+ * @property {boolean} [draftSpendIncomplete] the raw `--draft-spend-incomplete` presence-
+ *   flag (hamr's ruling 2026-09-28, 2nd addendum) — whether the drafting fold above was a
+ *   FLOOR, never an exact figure. A new field beside `draftSpentUsd`, same param-guard
+ *   class, no value to misread.
  * @property {string|null} [registry] a bridge registry directory
  * @property {string|null} [workflow] the registry's workflow name (defaults to `spec.job`)
  * @property {string|null} [approve] the spec hash being signed; omitted previews only
@@ -263,6 +273,8 @@ class ExitSignal extends Error {
  * @property {string|null} model
  * @property {string|null} readShim
  * @property {string|null} scout
+ * @property {string|null} draftSpentUsd
+ * @property {boolean} draftSpendIncomplete
  * @property {string|null} registry
  * @property {string|null} workflow
  * @property {string|null} approve
@@ -394,6 +406,39 @@ async function execute(ctx) {
    * so a resume never silently drops it and runs the default under the arm's label. */
   const SCOUT_TAIL = scoutArg !== null && !SCOUT ? ' --scout off' : '';
 
+  // --draft-spent-usd (hamr's ruling 2026-09-28, "one cap covers drafting +
+  // run") — runner territory exactly like --read-shim/--scout above: the
+  // spec's signed budgetUsd is unaffected, this only shrinks THIS leg's own
+  // enforced ceiling. Same param-guard class and the same reason: an
+  // unreadable value here would either silently widen the ceiling (garbage
+  // read as 0) or silently narrow it (garbage read as Infinity) — neither is
+  // acceptable, so this refuses at argv, before the approval gate, rather
+  // than coercing.
+  const draftSpentArg = ctx.draftSpentUsd ?? null;
+  let DRAFT_SPENT_USD = 0;
+  if (draftSpentArg !== null) {
+    const v = Number(draftSpentArg);
+    if (draftSpentArg.trim() === '' || !Number.isFinite(v) || v < 0) {
+      err(`--draft-spent-usd "${draftSpentArg}" is not a finite number >= 0 — refusing rather than coercing it into $0 (which would widen the ceiling) or letting a NaN poison the ceiling arithmetic`);
+      throw new ExitSignal(2);
+    }
+    DRAFT_SPENT_USD = v;
+  }
+  // --draft-spend-incomplete (hamr's ruling 2026-09-28, 2nd addendum) — a NEW
+  // field beside --draft-spent-usd, never a value inside it: whether the
+  // drafting fold above was EXACT. Boolean presence-flag, same class as
+  // --review-door above (no argument, no value to misread as 0/Infinity).
+  // Meaningless alone (no drafting fold to qualify) but never refused for
+  // being passed without --draft-spent-usd — a re-invocation tail that always
+  // pairs the two never needs a second guard to prove it did.
+  const DRAFT_SPEND_INCOMPLETE = ctx.draftSpendIncomplete === true;
+  /** every re-invocation this script PRINTS carries the drafting fold, the
+   * same SHIM_TAIL/SCOUT_TAIL rule: a resume that dropped it would silently
+   * WIDEN the ceiling back up by the drafting spend on its next leg (and
+   * dropping the incomplete flag would silently turn a floor into an exact
+   * figure on the next leg's own job-start). */
+  const DRAFT_TAIL = DRAFT_SPENT_USD > 0 ? ` --draft-spent-usd ${DRAFT_SPENT_USD}${DRAFT_SPEND_INCOMPLETE ? ' --draft-spend-incomplete' : ''}` : '';
+
   const WORKDIR = target.workdir;
   const SEED = target.seed;
   const specHash = jobSpecHash(spec);
@@ -1040,7 +1085,7 @@ async function execute(ctx) {
     // right key only by accident of the runner's own generic error message,
     // never from this hint. `providerEntry.envKey` is the same resolved name
     // the real key check at launch (`:1157-1158` below) reads.
-    const invoke = (/** @type {string} */ tail) => `  ${providerEntry.envKey}=... node scripts/run-u.mjs ${SELECTOR}${dead ? ` --resume ${RESUME}` : ''}${SHIM_TAIL}${SCOUT_TAIL}${tail} --approve ${specHash}`;
+    const invoke = (/** @type {string} */ tail) => `  ${providerEntry.envKey}=... node scripts/run-u.mjs ${SELECTOR}${dead ? ` --resume ${RESUME}` : ''}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL}${tail} --approve ${specHash}`;
     /** the door the operator has already picked, as flags — hoisted out of the else
      * below so the inhibitor line at the bottom can print the WHOLE command rather
      * than a shape the operator has to assemble. Empty on an ordinary run and on the
@@ -1205,8 +1250,8 @@ async function execute(ctx) {
     out(`\nPAUSED BY YOU — nothing was run and nothing was spent. The checkpoint stands exactly as it was: the work is on the run's own branch, the plan and the money are where the paused leg left them.`);
     out(`  keeps    ${PAUSE_TTL_MS / 86_400_000} days from the pause on the record — after that the checkpoint expires on its own, and nothing has to be decided today to let that happen`);
     out('  resume   the SAME runid, whenever you want, with the door you pick then:');
-    out(`           node scripts/run-u.mjs ${SELECTOR} --resume ${RESUME}${SHIM_TAIL}${SCOUT_TAIL} --decide accept --approve ${specHash}`);
-    out(`           node scripts/run-u.mjs ${SELECTOR} --resume ${RESUME}${SHIM_TAIL}${SCOUT_TAIL} --decide rerun --text "<what you want done differently>" --approve ${specHash}`);
+    out(`           node scripts/run-u.mjs ${SELECTOR} --resume ${RESUME}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL} --decide accept --approve ${specHash}`);
+    out(`           node scripts/run-u.mjs ${SELECTOR} --resume ${RESUME}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL} --decide rerun --text "<what you want done differently>" --approve ${specHash}`);
     out(`  read     the same command with no --decide re-prints the evidence package you just looked at`);
     throw new ExitSignal(0);
   }
@@ -1458,6 +1503,14 @@ async function execute(ctx) {
   // driver's plan is a row nobody can audit from its own log.
   out(`   ${READ_SHIM_LABEL}`);
   out(`   ${SCOUT_LABEL}`);
+  // hamr's ruling 2026-09-28 — advertised = enforced: the banner states the
+  // SIGNED cap above unconditionally (it never changes, same spec hash), and
+  // this line states the drafting fold whenever there is one, so the number
+  // this run actually enforces (Cap $ − drafting spent) is never a second,
+  // silent figure a reader has to compute themselves.
+  if (DRAFT_SPENT_USD > 0) {
+    out(`   drafting spent $${DRAFT_SPENT_USD.toFixed(4)} — this run's own enforced ceiling is $${(spec.budgetUsd - DRAFT_SPENT_USD).toFixed(4)} of the signed $${spec.budgetUsd}`);
+  }
 
   // F67 — the OUTSIDE watchdog, started before the run and sharing nothing with it.
   // Every guard bareloop had lived inside this process, and ms3197n8/ms3jh76q proved
@@ -1642,6 +1695,8 @@ async function execute(ctx) {
       closeDir: spineDir,
       readShim: READ_SHIM,
       scout: SCOUT,
+      draftSpentUsd: DRAFT_SPENT_USD,
+      draftSpendComplete: !DRAFT_SPEND_INCOMPLETE,
       // RESUME: the money and the wall the halted run already burned are FOLDED IN (so
       // the signed ceiling cannot widen by being re-invoked), and the checkpoint it
       // reached is handed over so the plan is reloaded rather than re-drafted and the
@@ -1731,7 +1786,15 @@ async function execute(ctx) {
   const writes = audit.filter((e) => e.decision === 'allow' && (e.action?.type === 'write' || e.action?.type === 'edit'));
 
   out(`\noutcome   ${outcome}`);
-  out(`spent     ${je?.spentUsd == null ? 'UNKNOWN' : `${je.spendComplete === false ? '≥' : ''}$${je.spentUsd.toFixed(4)}`} of $${spec.budgetUsd}`);
+  // hamr's ruling 2026-09-28 — the drafting share (this leg's own job-start
+  // record) rides beside the run's own spend via the ONE shared formatter,
+  // so this line never disagrees with the panel's Run tab/Runs list about
+  // what "$X of $Y" means for a job that drafted through the panel/author.
+  const jobStartRec = events.find((e) => e.type === 'job-start');
+  const legDraftSpentUsd = typeof jobStartRec?.draftSpentUsd === 'number' && jobStartRec.draftSpentUsd > 0 ? jobStartRec.draftSpentUsd : null;
+  const legDraftSpendComplete = legDraftSpentUsd === null ? null : jobStartRec.draftSpendComplete !== false;
+  const spendCore = je?.spentUsd == null ? 'UNKNOWN' : `${je.spendComplete === false ? '≥' : ''}$${je.spentUsd.toFixed(4)}`;
+  out(`spent     ${moneyWithDraft(spendCore, legDraftSpentUsd, spec.budgetUsd, legDraftSpendComplete)}`);
   // FOLDED, exactly like the money line above it: on a resume the cap governs both legs
   // together, and a leg-only wall next to a folded spend is two framings on one cap with
   // no label to tell them apart (F83). The leg stays on the line beside it.
@@ -1768,7 +1831,7 @@ async function execute(ctx) {
     out(`  trend   ${mh.trend} — ${mh.reading}`);
     out(`  lever   ${mh.lever}`);
     for (const o of mh.options ?? []) out(`          · ${o}`);
-    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL} --approve <the NEW hash after you edit budgetUsd>`);
+    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL} --approve <the NEW hash after you edit budgetUsd>`);
     out('          (the top-up is yours to sign — nothing in the run may widen its own budget)');
   }
   // A STALL is a checkpoint too (hamr's go, 2026-08-13). Its own escalation prints one
@@ -1778,7 +1841,7 @@ async function execute(ctx) {
   // the hash already approved is the hash that resumes.
   if (outcome === 'step-stalled') {
     out('\nSTALL HALT — the model stopped producing rounds and reissuing the call did not recover it. The tree, the plan and the steps already finished STAND.');
-    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL} --approve ${specHash}`);
+    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL} --approve ${specHash}`);
     out('          (no spec edit, so the hash is unchanged — this re-enters at the stalled step and re-pays for none of the ones before it)');
     out('          (if the allowance is what actually ran out underneath the stall, that preview says so and refuses — it is read there, not asserted here)');
   }
@@ -1799,7 +1862,7 @@ async function execute(ctx) {
     out(`  died    ${total === null ? 'before a plan was accepted — nothing paid is re-payable'
       : done >= total ? `at the close — all ${total} step(s) finished`
         : `in step ${done + 1} of ${total}`}`);
-    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL} --approve ${specHash}`);
+    out(`  resume  node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL} --approve ${specHash}`);
     out('          (no spec edit, so the hash is unchanged — this re-enters at the recorded step and re-pays for none of the ones before it)');
     out('          (if the allowance is what actually ran out underneath the transport fault, that preview says so and refuses — it is read there, not asserted here)');
   }
@@ -1820,7 +1883,7 @@ async function execute(ctx) {
     ]);
     out('  clock    STOPPED — the wall does not run while a person is reading (W-2), and this leg\'s elapsed is what folds into the resume');
     out('');
-    const answer = (/** @type {string} */ tail) => `node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${tail} --approve ${specHash}`;
+    const answer = (/** @type {string} */ tail) => `node scripts/run-u.mjs ${SELECTOR} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL}${tail} --approve ${specHash}`;
     for (const l of doorLines({
       rerun: answer(' --decide rerun --text "<what you want done differently>"'),
       accept: answer(' --decide accept'),
@@ -2057,6 +2120,8 @@ function buildCtx(mode, opts) {
     model: opts.model ?? null,
     readShim: opts.readShim ?? null,
     scout: opts.scout ?? null,
+    draftSpentUsd: opts.draftSpentUsd ?? null,
+    draftSpendIncomplete: opts.draftSpendIncomplete === true,
     registry: opts.registry ?? null,
     workflow: opts.workflow ?? null,
     approve: opts.approve ?? null,
@@ -2275,6 +2340,8 @@ export async function main(argv, deps = {}) {
       model: argFlag('model'),
       readShim: argFlag('read-shim'),
       scout: argFlag('scout'),
+      draftSpentUsd: argFlag('draft-spent-usd'),
+      draftSpendIncomplete: argv.includes('--draft-spend-incomplete'),
       registry: argFlag('registry'),
       workflow: argFlag('workflow'),
       approve: argFlag('approve'),

package/types/authorflow.d.ts

@@ -649,7 +649,10 @@ export function confirmPrompt({ answers, questions, labels, facts, listing, writ
  *   generate: Function, book: ReturnType<typeof makeCostBook>,
  *   ask: (step: {kind: string, [k: string]: any}) => Promise<string|null>,
  *   onPhase?: (phase: string, data?: any) => void, mode?: 'tool'|'text',
- *   worseThanBefore?: string}} o
+ *   worseThanBefore?: string}} o retired field (hamr's ruling 2026-09-28):
+ *   `worseThanBefore` is never asked any more and defaults to `''` — a
+ *   caller may still pass a string through (kept for a future, non-ask
+ *   source of the same constraint), it just never comes from an ask() step.
  * @returns {Promise<{ok: boolean,
  *   stop: null|'cap-halt'|'pricing-red'|'provider-red'|'artifact-red'|'confirm-abandoned'|'confirm-restart',
  *   rounds: number,
@@ -1013,26 +1016,6 @@ export const QUESTION_SETS: Record<string, {
  * @type {Record<string, string|null>}
  */
 export const CLASS_STATEMENTS: Record<string, string | null>;
-/**
- * Asked ONLY for a repo source (ruling 2 addendum's D7) — a plain folder or a
- * URL has no "before" a repo's own history gives it to compare against. This
- * is the OLD Q5 wording, verbatim ("What would make you say this came back
- * worse than before?"), which M3 piece 3's reshape folded into Guardrails —
- * it survives here as its OWN field because the confirm turn (ruling 5's
- * 2026-09-13 addendum) includes it as a constraint only when the person
- * actually gave one, and folding it silently into the Guardrails free-text
- * slot would lose that "present or absent" distinction. An empty answer is
- * "nothing beyond what Guardrails already said" and is not required — see
- * the frozen-wording test below: this phrase appears NOWHERE in
- * {@link questionsFor}'s own sets, so a caller cannot double-ask it by
- * reading the wrong table.
- */
-export const WORSE_THAN_BEFORE_FIELD: Readonly<{
-    id: "worseThanBefore";
-    kind: "mechanical";
-    label: "Worse than before";
-    prompt: "What would make you say this came back worse than before?";
-}>;
 /**
  * Asked ONLY when `src/detectlang.js`'s `detectLanguage` reports its
  * `ambiguous` outcome — two supported languages' manifests at the same

package/types/panel/authorroutes.d.ts

@@ -0,0 +1,65 @@
+/** @returns {string} a fresh per-process token — never persisted, never logged */
+export function mintToken(): string;
+/**
+ * `true` when a request may reach ANY route in this file — the token header
+ * plus an Origin/Host that names this exact bind address. `req.headers`
+ * lower-cases header names (node's own `http` behaviour), so this reads
+ * lower-case names throughout.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{token: string, port: number}} o
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function checkHumanGuard(req: import("node:http").IncomingMessage, { token, port }: {
+    token: string;
+    port: number;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Builds this file's own request handler, holding its session store in a
+ * closure (one per `createPanelServer` call, exactly like `handleRequest`'s
+ * own module holds none — this file owns the state `src/panel/server.js`
+ * deliberately has none of).
+ * @param {{ port: number, token: string, env?: Record<string,string|undefined>,
+ *   sessionsRoot?: string, spawnFn?: typeof realSpawn, bareloopBin?: string,
+ *   jobsDir?: string, fetchImpl?: typeof fetch }} opts
+ */
+export function createAuthorRoutes(opts: {
+    port: number;
+    token: string;
+    env?: Record<string, string | undefined>;
+    sessionsRoot?: string;
+    spawnFn?: typeof realSpawn;
+    bareloopBin?: string;
+    jobsDir?: string;
+    fetchImpl?: typeof fetch;
+}): {
+    handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
+    sessions: Map<string, any>;
+};
+/**
+ * THE ONLY function in this file (or anywhere in the panel) that spawns a
+ * run. Refuses unless the session is `prepared` AND the hash the request
+ * carried matches the session's OWN `signing.json` `specHash` exactly — the
+ * click carries the hash (per the mockup's own "the person never has to copy
+ * it to sign"), and this is where it is checked, not trusted.
+ * @param {ReturnType<typeof createSession>} session
+ * @param {string} claimedHash
+ * @param {{env: any, spawnFn: typeof realSpawn, bareloopBin: string, sessionsRoot?: string}} o
+ * @returns {{ok: boolean, error?: string, job?: string}}
+ */
+export function signRun(session: ReturnType<typeof createSession>, claimedHash: string, o: {
+    env: any;
+    spawnFn: typeof realSpawn;
+    bareloopBin: string;
+    sessionsRoot?: string;
+}): {
+    ok: boolean;
+    error?: string;
+    job?: string;
+};
+import { spawn as realSpawn } from 'node:child_process';
+import { createSession } from './authorsession.js';

package/types/panel/authorsession.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `true` when `jobs/<name>.json` already exists in the repo's own jobs/ dir
+ * (resolved from THIS module's own on-disk location, never `process.cwd()`,
+ * the same rule `src/panel/server.js`'s `jobsDir()` follows) — P3 is new-jobs-
+ * only (Q4=A), so a name collision refuses at $0 rather than silently
+ * overwriting or authoring a second spec under one name.
+ * @param {string} name
+ * @param {{jobsDir?: string}} [opts] test seam
+ * @returns {boolean}
+ */
+export function jobNameTaken(name: string, opts?: {
+    jobsDir?: string;
+}): boolean;
+/**
+ * `$0` validation of the job card fields the server must check BEFORE it
+ * creates a session or spends anything — never inside the async pipeline,
+ * so a bad card refuses synchronously, in the same HTTP response.
+ * @param {any} card
+ * @returns {{ok: true}|{ok: false, error: string}}
+ */
+export function validateJobCard(card: any): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * ONE session's engine — created already RUNNING (the caller awaits nothing;
+ * the pipeline drives itself, reporting through `state`). `state.pendingAsk`
+ * is the ONE thing a person answers next; `answer()`/`send()`/`revise()`/
+ * `signPrepare()` are the only ways in.
+ * @param {any} card the validated job card (see {@link validateJobCard})
+ * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, timeoutMs?: number,
+ *   scout?: any, generate?: Function, confirmGenerate?: Function, authorFn?: Function,
+ *   prepareSigningFn?: Function}} [deps] the last five are TEST SEAMS ONLY — see the note
+ *   just above where each is read, below.
+ * @returns {any} the session object
+ */
+export function createSession(card: any, deps?: {
+    env?: Record<string, string | undefined>;
+    sessionsRoot?: string;
+    timeoutMs?: number;
+    scout?: any;
+    generate?: Function;
+    confirmGenerate?: Function;
+    authorFn?: Function;
+    prepareSigningFn?: Function;
+}): any;
+/**
+ * The job card's "Model" select — a fixed, small, source-grounded mapping
+ * from a display id to the `{provider, baseUrl?}` pair `src/interviewrun.js`
+ * itself documents (that script's own `--provider openai-api --base-url
+ * https://api.deepseek.com/v1` usage line for DeepSeek): the panel builds no
+ * provider table of its own, this is a UI convenience over the SAME two
+ * provider identities the CLI already resolves through `resolveProvider`.
+ * @type {Readonly<Record<string, {provider: string, baseUrl?: string}>>}
+ */
+export const MODEL_OPTIONS: Readonly<Record<string, {
+    provider: string;
+    baseUrl?: string;
+}>>;

package/types/panel/server.d.ts

@@ -200,13 +200,24 @@ export function getRunJob(runid: string, opts?: {
  * separately from {@link createPanelServer} so tests can drive it without a
  * real listening socket where that is simpler (most path-safety/405 tests
  * still go through a real socket, per the build spec).
+ *
+ * PANEL-BUILD.md P3: this file's own GET/HEAD-only rule stands for every
+ * route it owns; `/api/author/*` is the ONE family of routes that may be
+ * POSTed to, and it is handled entirely by {@link createAuthorRoutes}
+ * (`src/panel/authorroutes.js`) — a separate module so this file's own
+ * "read-only, by construction" header comment stays true of everything else
+ * in it. `opts.authorRoutes` is absent on every P1/P2 caller (read-only
+ * tests, and the CLI's own `panelMain` when no author routes are wired) —
+ * only `createPanelServer` below always supplies one.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {{ home?: string, port: number }} opts
+ * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes> }} opts
  */
 export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
     home?: string;
     port: number;
+    token?: string;
+    authorRoutes?: ReturnType<typeof createAuthorRoutes>;
 }): void;
 /**
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
@@ -214,15 +225,33 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
  * header). Resolves once actually listening; rejects on a bind error
  * (including `EADDRINUSE`) with a `.port` field on the error for the
  * caller's message.
- * @param {{ port?: number, home?: string }} [opts]
- * @returns {Promise<{ server: import('node:http').Server, port: number, close: () => Promise<void> }>}
+ *
+ * PANEL-BUILD.md P3: a fresh {@link mintToken} token and one {@link
+ * createAuthorRoutes} instance are built here, ONCE per server start, and
+ * held for the server's lifetime — `opts.env`/`opts.sessionsRoot`/
+ * `opts.spawnFn`/`opts.bareloopBin` are test seams the author routes take
+ * (a real caller passes none of them and {@link createAuthorRoutes} defaults
+ * each one to the real environment/spawn/binary, this file itself touching
+ * none of them, and the real
+ * `~/.config/bareloop/panel-sessions`, the real `child_process.spawn`, and
+ * this package's own `bin/bareloop.mjs`).
+ * @param {{ port?: number, home?: string, env?: Record<string,string|undefined>,
+ *   sessionsRoot?: string, spawnFn?: (...a: any[]) => any, bareloopBin?: string,
+ *   fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, close: () => Promise<void> }>}
  */
 export function createPanelServer(opts?: {
     port?: number;
     home?: string;
+    env?: Record<string, string | undefined>;
+    sessionsRoot?: string;
+    spawnFn?: (...a: any[]) => any;
+    bareloopBin?: string;
+    fetchImpl?: typeof fetch;
 }): Promise<{
     server: import("node:http").Server;
     port: number;
+    token: string;
     close: () => Promise<void>;
 }>;
 /**
@@ -263,3 +292,4 @@ export const DIED_MTIME_MS: number;
  * 2026-09-25). */
 export const ROUNDS_PAGE_DEFAULT: 50;
 export const ROUNDS_PAGE_MAX: 200;
+import { createAuthorRoutes } from './authorroutes.js';

package/types/providers.d.ts

@@ -98,6 +98,40 @@ export function buildRunnerProviders({ providerName, apiKey, model, tierModels,
     providerFor: (tier: string) => any;
     judgeProvider: any;
 };
+/**
+ * $0 reachability check: a GET against `providerName`'s own models-list
+ * endpoint, server-side, with the key in a header — NEVER a completion
+ * request, so it never spends a token (PANEL-BUILD.md P3 build item 7: "the
+ * person must get feedback BEFORE drafting if the chosen model can't
+ * work"). Reused, unmodified, by the panel's model-readiness route today
+ * (`src/panel/authorroutes.js`) and by the future Settings providers
+ * table's own "test" column (PANEL-BUILD.md P4) — ONE function, not two
+ * hand-typed copies of the same probe.
+ *
+ * NEVER returns the key, never logs it — the key only ever appears in a
+ * request header sent straight to the provider's own host.
+ * @param {object} o
+ * @param {string} o.providerName
+ * @param {string} o.apiKey
+ * @param {string} [o.model] when given, the response is also checked for this model id
+ * @param {string} [o.baseUrl]
+ * @param {typeof fetch} [o.fetchImpl] TEST SEAM — defaults to the real global `fetch`
+ * @param {number} [o.timeoutMs] defaults to 4000 — a flaky endpoint must never hang the caller
+ * @returns {Promise<{reachable: boolean, modelListed: boolean|null, status: string, note: string|null}>}
+ */
+export function checkProviderReachable({ providerName, apiKey, model, baseUrl, fetchImpl, timeoutMs, }: {
+    providerName: string;
+    apiKey: string;
+    model?: string | undefined;
+    baseUrl?: string | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<{
+    reachable: boolean;
+    modelListed: boolean | null;
+    status: string;
+    note: string | null;
+}>;
 /**
  * The launch-time warning lines for an ADMITTED-PENDING-PROBE provider, or
  * `null` when the provider has paid for its own end-to-end probe (and for an

package/types/replay.d.ts

@@ -89,6 +89,8 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
     stopReason: string | null;
     spentUsd: any;
     spendComplete: boolean;
+    draftSpentUsd: any;
+    draftSpendComplete: boolean | null;
     floorReasons: string[];
     transportRetryCount: number;
     transportRetriesOutsideWindows: number;
@@ -239,6 +241,35 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
     memoryCache: any;
     skipped: number;
 };
+/**
+ * hamr's ruling 2026-09-28 ("one cap covers drafting + run") — the ONE
+ * spend display for a run that may carry a drafting share, so every surface
+ * that shows a run's money (the CLI's own `spent` line, the panel's Run tab
+ * summary/counters, the Runs list row, the Audit header, the Job tab) reads
+ * the same string rather than each hand-composing its own. `spendCore` is
+ * already-formatted text (`money(...)`, or a `died`/floor line's "at least
+ * $X") — this only decides whether to append the `(<draft> drafting)`
+ * clause and the `of $<cap>` tail, never re-derives the money itself.
+ * Unchanged (`spendCore` alone, or `spendCore of $cap`) when there is no
+ * drafting share — a run without one prints exactly what it always did.
+ *
+ * hamr's ruling 2026-09-28 (2nd addendum) — an INCOMPLETE drafting fold
+ * (`draftSpendComplete === false`) is a floor, not a total, and F6's rule
+ * ("unpriced is never free, a floor never dresses as exact") applies here
+ * exactly as it does to `spendCore` itself: the drafting clause reads `at
+ * least $X drafting`, and because a reader summing the two figures would
+ * otherwise take the LEADING number as exact too, `spendCore` itself also
+ * gains the `at least ` prefix — unless it already carries one (a `died`
+ * floor, or an already-prefixed caller), never doubled.
+ * @param {string} spendCore already-formatted spend text (e.g. `$3.71` or `at least $2.00`)
+ * @param {number|null} draftSpentUsd the drafting share, or null when there isn't one
+ * @param {number|null} [budgetUsd] the signed cap, appended as `of $X.XX` when given
+ * @param {boolean|null} [draftSpendComplete] whether the drafting fold above was EXACT;
+ *   `null`/`undefined`/`true` all read as exact (never a new enum value elsewhere) —
+ *   only an explicit `false` triggers the floor wording.
+ * @returns {string}
+ */
+export function moneyWithDraft(spendCore: string, draftSpentUsd: number | null, budgetUsd?: number | null, draftSpendComplete?: boolean | null): string;
 /**
  * Render a {@link replayRun} summary as one printable page: a header block
  * (goal/shape/signed/branch/outcome/spent), a timeline (steps or iterations,

package/types/replayio.d.ts

@@ -42,7 +42,8 @@ export function resolveSiblings(spinePath: string): {
  * Read one run's spine (+ its gate-audit sidecar, when present) off disk and
  * hand both to {@link replayRun}. Read-only, $0, mints no verdict.
  * @param {string} spinePath absolute or cwd-relative path to a `.jsonl` spine
- * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean}} [opts]
+ * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean,
+ *   auditPathOverride?: string|null}} [opts]
  *   `preParsedSpine`: avoids a second parse of the same file when the caller
  *   ({@link listSpines}) already read it once to run {@link looksLikeSpine}.
  *   `skipAudit` (PR #23 review item 5, 2026-08-26, carried over): a
@@ -50,6 +51,15 @@ export function resolveSiblings(spinePath: string): {
  *   `summarizeForAllLine` reads none of the fields that sidecar feeds inside
  *   `replayRun`, so reading every run's sidecar in a directory listing was
  *   pure unused I/O, multiplied by every spine found.
+ *   `auditPathOverride` (build item 7, 2026-09-28): when a caller has ALREADY
+ *   resolved the real audit path through the one shared resolver
+ *   (`src/panel/server.js`'s `resolveAuditPathForRow`, which also covers a
+ *   still-LIVE run's during-run sidecar location — this function's own
+ *   `resolveSiblings` call only ever finds the FINISHED-run convention), it
+ *   passes that path here (`null` included) instead of letting this
+ *   function re-derive a finished-only path on its own. `undefined` (the
+ *   default) keeps the original resolveSiblings-only behaviour — every
+ *   existing caller is unaffected.
  * @returns {ReturnType<typeof replayRun>}
  */
 export function replayOne(spinePath: string, opts?: {
@@ -58,6 +68,7 @@ export function replayOne(spinePath: string, opts?: {
         skipped: number;
     };
     skipAudit?: boolean;
+    auditPathOverride?: string | null;
 }): ReturnType<typeof replayRun>;
 /**
  * List every spine found directly in `dir` (not recursive — same as the

package/types/run.d.ts

@@ -73,6 +73,29 @@
  *   load gate refuses one: a refusal returns the distinct `recipe-stale` outcome with zero
  *   spend rather than silently drafting cold, because starting a paid run on a decision
  *   nobody made is the same class of error as widening a cap to manufacture a green.
+ * @param {number} [opts.draftSpentUsd=0] hamr's ruling 2026-09-28 ("one cap covers
+ *   drafting + run") — money the AUTHORING pipeline (`authorCloseForJob`/
+ *   `prepareSigning`, run under the SAME signed `budgetUsd` as its ceiling) already
+ *   spent on THIS job before it was ever signed. The signed `budgetUsd` stays the
+ *   one number in the spec hash; this shrinks the RUN's own enforced ceiling by
+ *   what drafting already took, so the two phases never spend more than the one
+ *   cap together. Deliberately NOT `priorSpentUsd` — that key means "a previous
+ *   ATTEMPT of this same run died and folded its spend forward" and is read by
+ *   `readResume`/`replay.js`'s `resumed` flag; a drafting spend is not a resume and
+ *   must never make an ordinary first run of a job read as one. It is also never
+ *   folded into `spentUsd` (the run's own ledger, cumulative-so-far and what a
+ *   resume's `priorSpentUsd` seeds) or into `engagementSpentUsd` — drafting is a
+ *   DIFFERENT phase's spend, reported beside the run's, never inside it. A garbage
+ *   value (non-finite, negative) is read as 0, belted exactly like `priorSpentUsd`.
+ * @param {boolean} [opts.draftSpendComplete=true] hamr's ruling 2026-09-28 — was the
+ *   `draftSpentUsd` fold above EXACT? The authoring pipeline's own metered-call list can
+ *   go unpriced (F6) exactly like a resumed attempt's can, and the unknown does not heal
+ *   by folding forward. A NEW field beside `draftSpentUsd`, never a new state inside
+ *   `spendComplete`/`priorSpendComplete` — those answer "is THIS run's own ledger exact,"
+ *   this answers "was the OTHER phase's ledger exact," and the two must never merge into
+ *   one flag or a floor drafting spend could read as an exact run. Read only when
+ *   `draftSpentUsd` itself is emitted; a garbage value is read as `true` (the same belt
+ *   `priorSpendComplete` gets — an unreadable flag never manufactures a false floor).
  * @param {number} [opts.priorSpentUsd=0] RESUME (module C) — money a PREVIOUS, killed
  *   attempt of this same try already spent. It seeds the ledger, so the restarted
  *   attempt runs under the REMAINDER of the signed `budgetUsd` and the terminal
@@ -181,7 +204,7 @@
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -201,6 +224,8 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     closeTimeoutMs?: number | undefined;
     closeDir?: string | null | undefined;
     bridge?: unknown;
+    draftSpentUsd?: number | undefined;
+    draftSpendComplete?: boolean | undefined;
     priorSpentUsd?: number | undefined;
     priorSpendComplete?: boolean | undefined;
     priorWallMs?: number | undefined;

package/types/userrun.d.ts

@@ -92,6 +92,21 @@ export type RunOpts = {
      * the raw `--scout` value (`on`/`off`), or null for the default
      */
     scout?: string | null | undefined;
+    /**
+     * the raw `--draft-spent-usd` value (hamr's
+     * ruling 2026-09-28, "one cap covers drafting + run"), or null when the job never
+     * drafted through the panel/`bareloop author`. Parsed and validated in `execute`
+     * (finite, >= 0, else refused) — never coerced silently, the same param-guard
+     * class `--read-shim`/`--scout` already are.
+     */
+    draftSpentUsd?: string | null | undefined;
+    /**
+     * the raw `--draft-spend-incomplete` presence-
+     * flag (hamr's ruling 2026-09-28, 2nd addendum) — whether the drafting fold above was a
+     * FLOOR, never an exact figure. A new field beside `draftSpentUsd`, same param-guard
+     * class, no value to misread.
+     */
+    draftSpendIncomplete?: boolean | undefined;
     /**
      * a bridge registry directory
      */
@@ -129,6 +144,8 @@ export type RunCtx = {
     model: string | null;
     readShim: string | null;
     scout: string | null;
+    draftSpentUsd: string | null;
+    draftSpendIncomplete: boolean;
     registry: string | null;
     workflow: string | null;
     approve: string | null;