bareloop 0.33.0 → 0.35.0

package/types/legs.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Split one spine's parsed records into its legs. Pure.
+ * @param {any[]} events one spine's parsed records, in file order
+ * @returns {Leg[]} always at least one leg for a non-empty list; `[]` for an empty one
+ */
+export function legsOf(events: any[]): Leg[];
+/**
+ * The legs' WORKING time, gap excluded (hamr 2026-10-02, 2A: only working time charges the wall). Each leg
+ * counts first record → last record; the quiet time between one leg's end and the next leg's marker is
+ * nobody's. `null` = unknown (no leg carries two parseable stamps) — never 0. A leg whose stamps are
+ * unreadable adds nothing, so the figure is a FLOOR, `complete: false`.
+ * @param {Leg[]} legs
+ * @returns {{ ms: number|null, complete: boolean }}
+ */
+export function legsWallMs(legs: Leg[]): {
+    ms: number | null;
+    complete: boolean;
+};
+/**
+ * Parse a spine's TEXT, tolerant exactly where the writer leaves damage. A kill mid-append leaves a torn
+ * line; a resume never edits it (the spine is append-only forever) — it writes one `\n` and starts a fresh
+ * line, so the torn bytes end up alone on their own line, immediately BEFORE a `leg-resume` marker. That
+ * line, and the file's own last two lines (the older tail rule: a kill mid-append of the file's final
+ * record), are tolerated and named. An unparseable line anywhere else is `corrupt`: a reconstruction from
+ * it would invent a history.
+ * @param {string} raw
+ * @returns {{ records: any[], tolerated: {line: number, why: 'tail'|'before-leg-resume'}[], corrupt: {line: number, message: string}|null }}
+ *   `line` is 1-based. Only the FIRST corrupt line is reported.
+ */
+export function parseSpineText(raw: string): {
+    records: any[];
+    tolerated: {
+        line: number;
+        why: "tail" | "before-leg-resume";
+    }[];
+    corrupt: {
+        line: number;
+        message: string;
+    } | null;
+};
+/**
+ * Where leg `leg`'s watchdog kill note lives. Leg 1 keeps the name every run has always had
+ * (`<spine>.watchdog.json`); a resumed leg's note sits beside it (`<spine>.leg<N>.watchdog.json`) so one
+ * leg never overwrites another's evidence of how it died.
+ * @param {string} spineFile
+ * @param {number} leg 1-based
+ * @returns {string}
+ */
+export function watchdogNotePath(spineFile: string, leg: number): string;
+/**
+ * P5 item 5 (Stop) — where a run's STOP REQUEST lives: a file beside its spine. The panel's stop route writes it;
+ * the engine reads it at the between-steps seam (src/planrun.js) and consumes it. One spelling, here, so the route
+ * and the engine can never name two files. A request belongs to ONE leg: the engine deletes it when it honours it,
+ * when the leg ends, and again at the start of the next leg (src/userrun.js).
+ * @param {string} spineFile
+ * @returns {string}
+ */
+export function stopFilePath(spineFile: string): string;
+/** The marker record's `type`. */
+export const LEG_RESUME: "leg-resume";
+export type Leg = {
+    /**
+     * 1-based position in file order (the marker's own `leg` field is never trusted over the order)
+     */
+    leg: number;
+    /**
+     * the leg's first record (the `leg-resume` marker for leg 2+; the file's first record for leg 1)
+     */
+    start: any | null;
+    /**
+     * the leg's last record
+     */
+    end: any | null;
+    /**
+     * every record of the leg, in file order, marker included
+     */
+    records: any[];
+    /**
+     * the leg's own `job-start` (null: it ended before runJob wrote one)
+     */
+    jobStart: any | null;
+    /**
+     * the leg's own LAST `job-end` (null: it died, or it is still running)
+     */
+    jobEnd: any | null;
+    /**
+     * the leg's terminal: its `job-end` outcome, else a `run-end` outcome (a $0 refusal), else null
+     */
+    outcome: string | null;
+    /**
+     * leg 1: null. Leg 2+: how the PREVIOUS leg ended, as the marker declares it
+     * (else derived from that leg's own terminal), `'died'` when it recorded none
+     */
+    after: string | null;
+    /**
+     * `Date.parse` of the start record's `ts`
+     */
+    startMs: number | null;
+    /**
+     * `Date.parse` of the end record's `ts`
+     */
+    endMs: number | null;
+};

package/types/monthly.d.ts

@@ -1,18 +1,8 @@
-/**
- * One run's own spend, off its spine records: this LEG's figure (never the chain fold),
- * plus the drafting spend the run was signed with (counted once — on the first leg only).
- * @param {any[]} records
- * @returns {{ usd: number, complete: boolean }}
- */
-export function legSpend(records: any[]): {
-    usd: number;
-    complete: boolean;
-};
 /**
  * One run's wall time off its spine: job-start -> job-end when the run ended (exact), else the
  * first -> last record floor (the SAME floor a died / still-running run's "at least" wall uses,
  * `floorsFromRecords`). `ms` null = unknown — never 0.
- * @param {any[]} records
+ * @param {any[]} records one spine's records (one leg or several)
  * @returns {{ ms: number|null, complete: boolean }}
  */
 export function legWall(records: any[]): {
@@ -29,20 +19,23 @@ export function legTokens(records: any[]): number;
 /**
  * Every listed run as one {@link Leg}. The ONE reader the month total, the all-time total
  * and the per-provider figures share.
- * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `now` = the clock for the no-pid in-flight test; `aboveRunid` = read only the runs listed EARLIER in the file than that run (a claim yields to the claims above it, never below)
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string, thisMonthOnly?: boolean }} [opts] `sessionsRoot` = where the panel's sessions live (default `<home>/panel-sessions`); `now` = the clock for the no-pid in-flight test; `aboveRunid` = read only the runs listed EARLIER in the file than that run (a claim yields to the claims above it, never below); `thisMonthOnly` = do not parse the spine of a run listed in another local month (the refusal check drops it anyway) unless its claim is still held
  * @returns {Leg[]}
  */
 export function readLegs(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
+    thisMonthOnly?: boolean;
 }): Leg[];
 /**
- * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`: see {@link readLegs}
- * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's)
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`, `sessionsRoot`: see {@link readLegs}
+ * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number, heldUsd: number, heldRuns: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's); `heldUsd` = what in-progress runs set aside beyond what they have spent (`reservedUsd - usd`), over `heldRuns` runs
  */
 export function monthSpend(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
 }): {
@@ -50,18 +43,21 @@ export function monthSpend(opts?: {
     atLeast: boolean;
     runs: number;
     reservedUsd: number;
+    heldUsd: number;
+    heldRuns: number;
 };
 /**
  * The Money tab's figures: all-time and this-month spend, and per-provider breakdown
  * (rows from `rowIdFor`; a run on no known row lands under its own provider name, never
  * pooled into another row). Any leg with unknown spend makes the figure it belongs to
  * an "at least".
- * @param {{ home?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
  * @returns {{ tokensByRow: Record<string, number>, total: {usd: number, atLeast: boolean, tokens: number}, month: {usd: number, atLeast: boolean, tokens: number},
  *   byProvider: Record<string, {label: string, monthUsd: number, monthAtLeast: boolean, totalUsd: number, totalAtLeast: boolean, tokens: number, vouchedRounds: number, otherRounds: number, monthWallMs: number|null, monthWallAtLeast: boolean, totalWallMs: number|null, totalWallAtLeast: boolean}> }}
  */
 export function spendSummary(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     rows?: readonly import("./providerrows.js").KeyRow[];
 }): {
@@ -97,6 +93,8 @@ export function spendSummary(opts?: {
  * @property {number|null} leftUsd what is left this month (null = no limit set)
  * @property {number|null} limitUsd the person's monthly limit (null = none)
  * @property {boolean} atLeast the month's spend is a floor, so `leftUsd` is a ceiling
+ * @property {number} [heldUsd] what run(s) in progress have set aside beyond their spend so far (present when a limit is set)
+ * @property {number} [heldRuns] how many runs hold it
  */
 /**
  * The person's monthly limit off a parsed config.json: key absent (or null) = no limit (null);
@@ -112,17 +110,19 @@ export function monthlyLimitOf(config: Record<string, any>, home?: string): numb
  * number above 0 throws `ConfigError`.
  * Compared in whole cents. Also throws `ConfigError` when config.json is unreadable — a gate
  * whose own instrument is broken refuses; it never silently runs with no limit.
- * @param {{ capUsd: number, home?: string, now?: () => number, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
+ * @param {{ capUsd: number, home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
  * @returns {MonthlyRoom}
  */
-export function checkMonthlyRoom({ capUsd, home, now, aboveRunid }: {
+export function checkMonthlyRoom({ capUsd, home, now, aboveRunid, sessionsRoot }: {
     capUsd: number;
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
 }): MonthlyRoom;
 /**
- * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal).
+ * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal). When run(s) in progress hold
+ * part of the limit, the same line says how much.
  * @param {MonthlyRoom} room
  * @returns {string|null} null when the run fits
  */
@@ -148,19 +148,21 @@ export function settleDeadClaims({ home, by, aboveRunid }: {
  * it appends `{type:'released', reason:'refused'}` and reports the refusal, nothing spent. No limit set =
  * no claim (`claimed: false`; the caller lists the run as it always did). An unreadable config, or a row
  * that cannot be written, throws `ConfigError` — the gate refuses, never reads "no limit".
- * @param {{ row: import('./runlist.js').RunRow, capUsd: number, home?: string, now?: () => number }} args
+ * A RESUMED leg (`leg` 2+, P5-R) claims the same way but appends a `leg-start` beside the run's one row
+ * (the row itself is added only when the list has none), and a refusal gives back THAT leg's claim.
+ * @param {{ row: import('./runlist.js').RunRow, capUsd: number, home?: string, now?: () => number, leg?: number }} args
  * @returns {{ room: MonthlyRoom, claimed: boolean }}
  */
-export function claimRun({ row, capUsd, home, now }: {
+export function claimRun({ row, capUsd, home, now, leg }: {
     row: import("./runlist.js").RunRow;
     capUsd: number;
     home?: string;
     now?: () => number;
+    leg?: number;
 }): {
     room: MonthlyRoom;
     claimed: boolean;
 };
-export { isLiveRunner };
 export type Leg = {
     /**
      * when the run was listed
@@ -208,6 +210,10 @@ export type Leg = {
      * the spine was missing/unreadable or the listed date was bad (spend unknown)
      */
     unreadable: boolean;
+    /**
+     * drafting spend of a panel session that never became a run (src/draftspend.js) — not a run: no wall, not counted in `runs`
+     */
+    draft?: boolean | undefined;
 };
 export type MonthlyRoom = {
     ok: boolean;
@@ -223,5 +229,16 @@ export type MonthlyRoom = {
      * the month's spend is a floor, so `leftUsd` is a ceiling
      */
     atLeast: boolean;
+    /**
+     * what run(s) in progress have set aside beyond their spend so far (present when a limit is set)
+     */
+    heldUsd?: number | undefined;
+    /**
+     * how many runs hold it
+     */
+    heldRuns?: number | undefined;
 };
-import { isLiveRunner } from './runlist.js';
+import { legSpend } from './ledger.js';
+import { runSpend } from './ledger.js';
+import { chainSpend } from './ledger.js';
+export { legSpend, runSpend, chainSpend };

package/types/panel/authorroutes.d.ts

@@ -1,5 +1,20 @@
 /** @returns {string} a fresh per-process token — never persisted, never logged */
 export function mintToken(): string;
+/**
+ * The ONE Host check: the request names this panel's own bind address. A page on another
+ * origin reaching the panel through a rebound DNS name sends that name as Host, so it fails here.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{port: number}} o
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function checkHostGuard(req: import("node:http").IncomingMessage, { port }: {
+    port: number;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: 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`
@@ -25,7 +40,8 @@ export function checkHumanGuard(req: import("node:http").IncomingMessage, { toke
  * 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, home?: string }} opts
+ *   jobsDir?: string, fetchImpl?: typeof fetch, home?: string,
+ *   startFrom?: {get: (runid: string, o?: {model?: string}) => any, getImport: (id: string, o?: {model?: string}) => any} }} opts
  */
 export function createAuthorRoutes(opts: {
     port: number;
@@ -37,10 +53,31 @@ export function createAuthorRoutes(opts: {
     jobsDir?: string;
     fetchImpl?: typeof fetch;
     home?: string;
+    startFrom?: {
+        get: (runid: string, o?: {
+            model?: string;
+        }) => any;
+        getImport: (id: string, o?: {
+            model?: string;
+        }) => any;
+    };
 }): {
     handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
     sessions: Map<string, any>;
 };
+/**
+ * The panel's OWN 2-decimal money render for a chat line — hamr's ruling
+ * 2026-09-28 (2nd addendum, panel money 2-decimals): a positive amount below
+ * a cent reads `<$0.01`, never `$0.00` (a real cost must never read as
+ * free). This is the server-side (Node, chat-text) sibling of
+ * `src/panel/index.html`'s own inline `panelMoney` — the two can't share
+ * code (one runs in the browser as inlined script, the other in Node), the
+ * same duplication `src/replay.js`'s `money()`/`index.html`'s `money()`
+ * already carry, so both apply the identical rule rather than drift.
+ * @param {number} n a non-negative dollar amount
+ * @returns {string}
+ */
+export function panelMoney2(n: number): string;
 /**
  * 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

package/types/panel/authorsession.d.ts

@@ -1,3 +1,14 @@
+/** @typedef {{id: string, label: string, status: 'running'|'done'|'failed', detail: string}} StepLine */
+/** @param {StepLine[]} steps @param {string} id the LATEST line carrying this id (the list is a time-ordered log; an id can repeat) */
+export function latestStep(steps: StepLine[], id: string): StepLine | undefined;
+/**
+ * The progress list is a chronological log of segments (hamr 2026-10-05): starting a different step closes the running
+ * line; a step that already has a line and starts again AFTER other steps gets a NEW line appended at the end (the
+ * earlier line keeps its status and detail). Existing lines are never moved. Re-starting the step that is still the
+ * LAST line just resumes that line.
+ * @param {StepLine[]} steps @param {string} id @param {string} [detail] (absent = keep what the line has)
+ */
+export function advanceSteps(steps: StepLine[], id: string, detail?: string): void;
 /**
  * `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()`,
@@ -11,6 +22,67 @@
 export function jobNameTaken(name: string, opts?: {
     jobsDir?: string;
 }): boolean;
+/**
+ * Only the form's own fields, nothing else a request body might carry (`startFrom`, stray keys).
+ * @param {any} card
+ * @returns {Record<string, any>}
+ */
+export function cardFields(card: any): Record<string, any>;
+/**
+ * The first LOCKED box on `card` that differs from what the signed workflow prefilled (`origin`), or `null` when
+ * every locked box is untouched. Blank and absent read alike; whitespace is not compared.
+ * @param {Record<string, any>} card the form as it was submitted
+ * @param {Record<string, any>} origin the form as the server prefilled it
+ * @returns {string|null} the offending field's label
+ */
+export function lockedFieldChanged(card: Record<string, any>, origin: Record<string, any>): string | null;
+/**
+ * The spec a reuse signs: a COPY of the origin's signed spec with ONLY the open fields set from the card —
+ * `writeScope` from Destination, `budgetUsd` from the $ cap, `maxWallMs` from the Time cap (absent when blank), and the
+ * worker (`provider`/`baseUrl`/`model`) from the Model Name chosen in Settings > Providers, spelled exactly as normal
+ * authoring spells it (`baseUrl` only when the row has one; `model` only when the Name is not the provider's default
+ * tier). A RUBRIC (soft-green) origin with no explicit `judge` first has its judge pinned to the ORIGIN's resolved judge
+ * identity — the judge must not change because the worker did (`resolveJobJudge`, the one spelling); an explicit
+ * `judge` is kept; a deterministic job has no judge to move. Source is not in a spec (it lives beside the run). The copy
+ * hashes to a NEW `jobSpecHash` and the SAME `workflowKey` — the caller checks the second after building.
+ * @param {any} originSpec
+ * @param {Record<string, any>} card
+ * @param {readonly import('../providerrows.js').KeyRow[]} [rows] the Settings rows; without them (or without `card.model`) the worker is left as signed
+ * @returns {any}
+ */
+export function buildReuseSpec(originSpec: any, card: Record<string, any>, rows?: readonly import("../providerrows.js").KeyRow[]): any;
+/**
+ * `$0` validation for a REUSE start: the signed job carries the goal, checks and guardrails, so those boxes are not
+ * required here — only what the new session itself needs: a Source, a Destination, a Model that is a Settings Name,
+ * and the cap. (The spec built from the open boxes is validated by the route with `validateJob`.)
+ * @param {any} card
+ * @param {{rows?: readonly import('../providerrows.js').KeyRow[]}} [opts]
+ * @returns {{ok: true}|{ok: false, error: string}}
+ */
+export function validateReuseCard(card: any, opts?: {
+    rows?: readonly import("../providerrows.js").KeyRow[];
+}): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The $0 refusal for a non-repo source, worded by the kind the source door recorded (`prep.manifest.kind`) — a single
+ * file is not a "folder", and Source must be the repo folder with the file named in Destination (hamr 2026-10-05).
+ * @param {string} kind `prep.manifest.kind`: 'file' | 'folder' | 'url' (a 'repo' never reaches this)
+ * @returns {string}
+ */
+export function nonRepoSourceMessage(kind: string): string;
+/**
+ * The ONE Destination rule for a REPO source (fresh card and Reuse card alike): there Destination is the write fence,
+ * relative to the repo, so an absolute path is refused — at $0, before any copy or model call. A FOLDER source (or a
+ * source that does not peek as a repo) keeps today's behaviour: its Destination is an absolute output directory.
+ * @param {string} destination
+ * @param {boolean} isRepoLike `looksLikeRepoSource(card.source)`
+ * @returns {string|null} the plain refusal, or null when the Destination is fine
+ */
+export function repoDestinationProblem(destination: string, isRepoLike: boolean): string | null;
 /**
  * `$0` validation of the job card fields the server must check BEFORE it
  * creates a session or spends anything — never inside the async pipeline,
@@ -36,8 +108,9 @@ export function validateJobCard(card: any, opts?: {
  * @param {any} card the validated job card (see {@link validateJobCard})
  * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: 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.
+ *   prepareSigningFn?: Function, reuse?: {spec: any, workflowKey: string}}} [deps] `scout`..`prepareSigningFn` are
+ *   TEST SEAMS ONLY — see the note just above where each is read, below. `reuse` (Reuse workflow) is NOT a seam: the
+ *   caller (`/api/author/start`) sets it only when the server's own same-job rule held.
  * @returns {any} the session object
  */
 export function createSession(card: any, deps?: {
@@ -50,4 +123,38 @@ export function createSession(card: any, deps?: {
     confirmGenerate?: Function;
     authorFn?: Function;
     prepareSigningFn?: Function;
+    reuse?: {
+        spec: any;
+        workflowKey: string;
+    };
 }): any;
+/**
+ * THE PROGRESS LIST's one table (hamr 2026-10-04, "one place showing all"): every pipeline step the left Chat panel
+ * lists, in the order they first appear, each with a stable id and a plain code-owned label. A step is one line that
+ * updates in place (running -> done or failed with its reason); the thread carries only chat turns.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const STEP_LABELS: Readonly<Record<string, string>>;
+/**
+ * The library's own `onPhase(name, ...)` calls (`src/authorjob.js`/`src/authorflow.js`) -> the step each one advances.
+ * A phase with no entry leaves the current step as it was.
+ * @type {Readonly<Record<string, keyof typeof STEP_LABELS>>}
+ */
+export const PHASE_STEP: Readonly<Record<string, keyof typeof STEP_LABELS>>;
+/** the form's fields, in card order — what `card.json` stores, verbatim (P5 item 3) */
+export const CARD_FIELDS: readonly string[];
+/**
+ * REUSE WORKFLOW (hamr 2026-10-03, replaces P5 item 3's same-job rule; Model opened 2026-10-04): a reuse card has exactly
+ * FIVE open boxes — Source, Destination, Model, $ cap, Time cap — and every other box is the signed workflow, shown greyed and never
+ * editable. The page greys them; THIS is what refuses (the server never trusts the page). Changing any locked box
+ * is a different job: Clear the card, which drafts.
+ */
+export const REUSE_OPEN_FIELDS: readonly string[];
+/** every card field that is NOT open on a reuse card, in card order */
+export const REUSE_LOCKED_FIELDS: readonly string[];
+export type StepLine = {
+    id: string;
+    label: string;
+    status: "running" | "done" | "failed";
+    detail: string;
+};

package/types/panel/importroutes.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Expand, normalise and `realpath` a requested folder. Never throws.
+ * @param {unknown} input the raw `path` (absent/blank = the person's home folder)
+ * @param {string} userHome the home folder (`~`)
+ * @returns {{ok: true, requested: string, path: string}|{ok: false, error: string}}
+ */
+export function resolveFsPath(input: unknown, userHome: string): {
+    ok: true;
+    requested: string;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The exported job bundles below `dir` (a `realpath` already), searched DOWN at most SEARCH_DEPTH levels. Symlinks are
+ * never followed, `node_modules`, `.git` and every dot-folder are skipped, a bundle is never descended into, an
+ * unreadable folder is skipped silently, and the search is capped (folders visited, results). Only names are read.
+ * @param {string} dir
+ * @returns {{entries: {name: string, path: string, bundle: true}[], visited: number, stopped: boolean, truncated: boolean}}
+ */
+export function findBundles(dir: string): {
+    entries: {
+        name: string;
+        path: string;
+        bundle: true;
+    }[];
+    visited: number;
+    stopped: boolean;
+    truncated: boolean;
+};
+/** @param {string} [home] @returns {string} `<home>/imports.jsonl` */
+export function importsPath(home?: string): string;
+/** the stable id of an imported folder (its real path, hashed — never the path itself in a URL) */
+export function importId(dir: string): string;
+/**
+ * Record one import: ONE row per real folder. Any earlier row for the same folder is dropped and the new one is
+ * written, so re-importing updates the entry instead of adding a second. The rewrite goes through a temp file + rename.
+ * @param {string|undefined} home
+ * @param {{at: string, dir: string, job: string, bundleHash: string}} row
+ */
+export function recordImport(home: string | undefined, row: {
+    at: string;
+    dir: string;
+    job: string;
+    bundleHash: string;
+}): void;
+/**
+ * The imported list: the LATEST row per folder (a re-import supersedes), newest first. A malformed line is skipped.
+ * @param {string} [home]
+ * @returns {{at: string, dir: string, job: string, bundleHash: string, id: string}[]}
+ */
+export function readImports(home?: string): {
+    at: string;
+    dir: string;
+    job: string;
+    bundleHash: string;
+    id: string;
+}[];
+/**
+ * Re-read one imported folder NOW and say how it stands against the import: `ok`, `changed` (the bundle's own
+ * hash, a tampered file or an unreadable part differ from what was imported — shown red as "changed since
+ * import"), or `missing` (the folder is gone). Never throws.
+ * @param {{dir: string, bundleHash: string}} row
+ * @returns {{status: 'ok'|'changed'|'missing', statusText: string|null, reds: string[], bundle: ReturnType<typeof readBundle>}}
+ */
+export function bundleStatus(row: {
+    dir: string;
+    bundleHash: string;
+}): {
+    status: "ok" | "changed" | "missing";
+    statusText: string | null;
+    reds: string[];
+    bundle: ReturnType<typeof readBundle>;
+};
+/**
+ * The `bundle` half of an import view: the exported history (the registry rows the bundle shipped), the approval
+ * on THIS machine (`blessing.json`, written by the first green run here), nothing about the folder's other files.
+ * @param {ReturnType<typeof readBundle>} bundle
+ */
+export function bundleHistoryAndApproval(bundle: ReturnType<typeof readBundle>): {
+    history: {
+        greens: number;
+        reds: number;
+        total: number;
+        recent: {
+            at: any;
+            runid: any;
+            outcome: any;
+            costUsd: any;
+        }[];
+    };
+    approved: boolean;
+    approvedText: string;
+};
+/**
+ * The import routes' handler. `describeSpec(spec)` is the server's own spec reader (the SAME fact-readers the Job
+ * tab uses, so an imported job and a run read alike): `{checkType, goal, success, guardrails, model, budgetUsd,
+ * maxWallMs}`.
+ * @param {{ port: number, token: string, home?: string, userHome?: string,
+ *   describeSpec: (spec: any) => any }} opts
+ */
+export function createImportRoutes(opts: {
+    port: number;
+    token: string;
+    home?: string;
+    userHome?: string;
+    describeSpec: (spec: any) => any;
+}): {
+    handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
+    viewOf: (row: {
+        id: string;
+        at: string;
+        dir: string;
+        job: string;
+        bundleHash: string;
+    }) => any;
+};
+/** the longest path the routes will look at (bytes) */
+export const MAX_PATH_LEN: 4096;
+/** how many levels below the current folder the bundle search looks */
+export const SEARCH_DEPTH: 3;
+/** the most folders one search visits; past it `stopped: true` */
+export const MAX_VISITED: 5000;
+/** the most bundles one search returns; past it `truncated: true` */
+export const MAX_RESULTS: 200;
+/** The ONE spelling of the plain-words line for a changed import (Run tab, reuse refusal). The list tag stays the short statusText. */
+export const IMPORT_CHANGED_LINE: "files changed since you imported it \u2014 Reuse is off. Import it again if the change was yours.";
+import { readBundle } from '../bundle.js';

package/types/panel/importrun.d.ts

@@ -0,0 +1,77 @@
+/** the id an imported run has in `/api/runs/<id>` @param {string} importId @param {string} runid */
+export function importedRunId(importId: string, runid: string): string;
+/** @param {string} id @returns {{importId: string, runid: string}|null} */
+export function parseImportedRunId(id: string): {
+    importId: string;
+    runid: string;
+} | null;
+/**
+ * The spine path of `<dir>/runs/<runid>`, or null when it is not a plain, bounded file in plain folders: `runs/` and
+ * the run folder must be real directories (a link is refused), the spine a regular file under the size bound, and a
+ * tool log beside it (either spelling the replay reader looks for) must not be a link or oversize either.
+ * @param {string} dir the bundle folder
+ * @param {string} runid
+ * @returns {string|null}
+ */
+export function safeSpinePath(dir: string, runid: string): string | null;
+/**
+ * The run folders of a bundle that hold a readable spine, newest spine first (bounded).
+ * @param {string} dir
+ * @returns {{runid: string, spine: string, mtimeMs: number}[]}
+ */
+export function bundleRuns(dir: string): {
+    runid: string;
+    spine: string;
+    mtimeMs: number;
+}[];
+/**
+ * When the run started: its `job-start` record's `ts`, else the spine file's mtime (an ISO string). Never throws.
+ * @param {string} spine
+ * @returns {string}
+ */
+export function spineStartedAt(spine: string): string;
+/**
+ * The newest run in the bundle whose spine ended green (`green` / `already-green`, the same two the run page's Ended
+ * block calls green). A spine that cannot be read is skipped, never fatal.
+ * @param {string} dir
+ * @returns {{runid: string, spine: string, at: string}|null}
+ */
+export function latestGreenRun(dir: string): {
+    runid: string;
+    spine: string;
+    at: string;
+} | null;
+/**
+ * The newest green version across a bundle's bridges (by `greenAt`), with the history row of the same run (it
+ * carries whether the spend figure is complete). A malformed bridge or version is skipped.
+ * @param {any[]} bridges
+ * @returns {{bridge: any, version: any, historyRow: any|null}|null}
+ */
+export function latestBridgeGreen(bridges: any[]): {
+    bridge: any;
+    version: any;
+    historyRow: any | null;
+} | null;
+/**
+ * The run detail of the bridge's green version, in the SAME shape `getRunDetail` returns (so the page's one run
+ * renderer paints it), plus `fromBridge: true`. Only what the bridge carries is filled; every other field is null
+ * ("not recorded" on the page), never 0: no tool counts, no cache, no per-step figures, no close stages' numbers.
+ * @param {{bridge: any, version: any, historyRow: any|null}} g
+ * @param {{job: string, checkType: string, checkTypeTitle: string|null, model: string|null, budgetUsd: number|null}} facts
+ * @returns {any}
+ */
+export function bridgeRunDetail(g: {
+    bridge: any;
+    version: any;
+    historyRow: any | null;
+}, facts: {
+    job: string;
+    checkType: string;
+    checkTypeTitle: string | null;
+    model: string | null;
+    budgetUsd: number | null;
+}): any;
+/** the most run folders one bundle is searched through (newest first) */
+export const MAX_RUN_DIRS: 40;
+/** the biggest spine / tool-log file that is read (bytes) */
+export const MAX_RUN_FILE_BYTES: number;