bareloop 0.34.0 → 0.36.0

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, npmCiFn?: 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,39 @@ export function createSession(card: any, deps?: {
     confirmGenerate?: Function;
     authorFn?: Function;
     prepareSigningFn?: Function;
+    npmCiFn?: 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;

package/types/panel/runroutes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The run routes' handler. `getResumeContext(runid)` is the server's own reader (the same
+ * `resumePlanFor` the Ended block uses, so the page never offers what this refuses):
+ * `null` = no such run, else `{row, plan}`.
+ * @param {{ port: number, token: string, env?: Record<string,string|undefined>, home?: string,
+ *   spawnFn?: typeof realSpawn, bareloopBin?: string, settleMs?: number,
+ *   getResumeContext: (runid: string) => ({row: any, plan: any}|null),
+ *   getStopContext?: (runid: string) => ({row: any, live: boolean, spineExists: boolean}|null) }} opts
+ */
+export function createRunRoutes(opts: {
+    port: number;
+    token: string;
+    env?: Record<string, string | undefined>;
+    home?: string;
+    spawnFn?: typeof realSpawn;
+    bareloopBin?: string;
+    settleMs?: number;
+    getResumeContext: (runid: string) => ({
+        row: any;
+        plan: any;
+    } | null);
+    getStopContext?: (runid: string) => ({
+        row: any;
+        live: boolean;
+        spineExists: boolean;
+    } | null);
+}): {
+    handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
+};
+/** how long a resume waits for an early engine exit before reporting "started" (ms) */
+export const DEFAULT_SETTLE_MS: 6000;
+import { spawn as realSpawn } from 'node:child_process';