bareloop 0.42.0 → 0.43.0

package/types/panel/schedulestart.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The spec one fire runs: the signed schedule's spec; for a file cause, Inputs line 1 is the arriving file. Every other
+ * field must be deep-equal and the workflow key unchanged (F.4): the person signed the SCHEDULE, each fire's hash is
+ * derived by code. A clock fire's spec equals the signed spec byte for byte (same hash).
+ * @param {{spec: any, specHash: string, workflowKey: string}} schedule
+ * @param {{kind: 'clock'}|{kind: 'file', path: string}} cause
+ * @returns {{ok: true, spec: any, hash: string}|{ok: false, why: string}}
+ */
+export function perFireSpec(schedule: {
+    spec: any;
+    specHash: string;
+    workflowKey: string;
+}, cause: {
+    kind: "clock";
+} | {
+    kind: "file";
+    path: string;
+}): {
+    ok: true;
+    spec: any;
+    hash: string;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * @param {{
+ *   door: ReturnType<typeof import('./schedules.js').createScheduleDoor>,
+ *   startSession: ReturnType<typeof import('./authorroutes.js').createAuthorRoutes>['startSession'],
+ *   envNow: () => Record<string, string|undefined>,
+ *   spawnFn: Function, bareloopBin: string, sessionsRoot?: string, home?: string,
+ *   rowsFor: () => readonly import('../providerrows.js').KeyRow[],
+ *   startFrom: (runid: string) => any,
+ *   now?: () => number, prepareTimeoutMs?: number, pollMs?: number, childGraceMs?: number,
+ *   forgetSession?: (id: string) => void, ranSince?: (job: string, sinceMs: number) => boolean,
+ * }} deps
+ */
+export function createStarter(deps: {
+    door: ReturnType<typeof import("./schedules.js").createScheduleDoor>;
+    startSession: ReturnType<typeof import("./authorroutes.js").createAuthorRoutes>["startSession"];
+    envNow: () => Record<string, string | undefined>;
+    spawnFn: Function;
+    bareloopBin: string;
+    sessionsRoot?: string;
+    home?: string;
+    rowsFor: () => readonly import("../providerrows.js").KeyRow[];
+    startFrom: (runid: string) => any;
+    now?: () => number;
+    prepareTimeoutMs?: number;
+    pollMs?: number;
+    childGraceMs?: number;
+    forgetSession?: (id: string) => void;
+    ranSince?: (job: string, sinceMs: number) => boolean;
+}): {
+    /**
+     * Cheap, $0, no copy, no session. `{ok: true}` or `{ok: false, why}` (words).
+     * @param {string} job
+     * @param {{kind: 'clock'} | {kind: 'file', path: string, sha: string}} cause
+     * @returns {{ok: true}|{ok: false, why: string}}
+     */
+    wouldAccept(job: string, cause: {
+        kind: "clock";
+    } | {
+        kind: "file";
+        path: string;
+        sha: string;
+    }): {
+        ok: true;
+    } | {
+        ok: false;
+        why: string;
+    };
+    /**
+     * Start the run. Never throws. `consumed` says whether `beforeSpawn` ran, so the caller knows whether a `released` row is owed.
+     * @param {string} job
+     * @param {{kind: 'clock', slot: number, catchUp: boolean, missed: number} | {kind: 'file', path: string, sha: string}} cause
+     * @param {{beforeSpawn?: () => void}} [hooks]
+     * @returns {Promise<{ok: true, sessionId: string, specHash: string, consumed: true}|{ok: false, why: string, consumed: boolean, installNeeded?: true}>}
+     */
+    start(job: string, cause: {
+        kind: "clock";
+        slot: number;
+        catchUp: boolean;
+        missed: number;
+    } | {
+        kind: "file";
+        path: string;
+        sha: string;
+    }, hooks?: {
+        beforeSpawn?: () => void;
+    }): Promise<{
+        ok: true;
+        sessionId: string;
+        specHash: string;
+        consumed: true;
+    } | {
+        ok: false;
+        why: string;
+        consumed: boolean;
+        installNeeded?: true;
+    }>;
+};
+/** how long a headless session may take to reach `prepared` (copy, install, signing gates) */
+export const PREPARE_TIMEOUT_MS: number;
+/** how long the starter listens for a child that refuses at once (run-u checks its spec and approve hash first thing) */
+export const CHILD_GRACE_MS: 1500;

package/types/panel/server.d.ts

@@ -116,7 +116,7 @@ export function legDividersFor(spineRecords: any[], parts: any[]): {
  *
  * The table (outcome → reason / next / buttons) is PANEL-BUILD.md P5 item 1. The
  * Resume button appears only when `o.resume` says the engine would accept it; "Reuse workflow"
- * (replaces P5 item 3, 2026-10-03) is offered on green rows only, and starts a NEW run.
+ * (replaces P5 item 3, 2026-10-03; one door on every ending since 2026-10-15) starts a NEW run.
  * @param {{outcome: string|null, stopReason: string|null, spentUsd: number|null, budgetUsd: number|null, lastEscalation?: any}} summary
  * @param {{died: boolean, lastThing: string|null}} death
  * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean,
@@ -155,6 +155,28 @@ export function endedFor(summary: {
         label: string;
     }[];
 } | null;
+/**
+ * RULED 2026-10-15 (Remove from Needs you): the ONE place a run's Needs-you state is decided. `Accept` (a live door) is never removable and never ages out.
+ * A `Resume` tag leaves when the person removed it AFTER (or at) the stop it is for — a removal covers only the ending it was made on, so a later stop
+ * brings the run back — or after `needsYouDays`. `removedMs` is the newest removal that covers the current ending (or null), `expired` is true when only
+ * the age rule took a Resume run out.
+ * @param {{live: boolean, records: any[], resume: {ok?: boolean}|null|undefined, stoppedAt: string|null, nowMs: number, removedMs?: number}} f
+ * @returns {{needs: 'Accept'|'Resume'|null, removedMs: number|null, expired: boolean}}
+ */
+export function needsStateFor(f: {
+    live: boolean;
+    records: any[];
+    resume: {
+        ok?: boolean;
+    } | null | undefined;
+    stoppedAt: string | null;
+    nowMs: number;
+    removedMs?: number;
+}): {
+    needs: "Accept" | "Resume" | null;
+    removedMs: number | null;
+    expired: boolean;
+};
 /**
  * The Resume route's reader (P5 item 2): the listed row plus the resume plan, from the
  * ONE {@link resumePlanFor} the Ended block asks. `null` when the runid is not listed
@@ -184,6 +206,43 @@ export function getStopContext(runid: string, opts?: {
     live: boolean;
     spineExists: boolean;
 } | null;
+/**
+ * The Remove-from-Needs-you route's reader (RULED 2026-10-15): the listed row and the Needs-you tag the runs list shows for it right now
+ * (`summarizeRow`, the one rule). `null` when the runid is not listed.
+ * @param {string} runid
+ * @param {{ home?: string, now?: number }} [opts]
+ * @returns {{row: any, needs: 'Accept'|'Resume'|null}|null}
+ */
+export function getNeedsContext(runid: string, opts?: {
+    home?: string;
+    now?: number;
+}): {
+    row: any;
+    needs: "Accept" | "Resume" | null;
+} | null;
+/**
+ * The ONE rule for a run's Needs-you tag (P9 v2 E): `Resume` when the engine would accept a resume (the SAME `resumePlanFor` answer the Run
+ * tab's Resume card shows, already asked once per row by `endedForRow`), until the run has been stopped `needsYouDays` (exactly that old is out;
+ * no readable stop time stays in). `Accept` comes from {@link doorWaiting} (T Part 8), asked in `summarizeRow`, never here.
+ * @param {{ok?: boolean}|null|undefined} resume @param {string|null} stoppedAt @param {number} nowMs
+ * @returns {'Accept'|'Resume'|null}
+ */
+export function needsTag(resume: {
+    ok?: boolean;
+} | null | undefined, stoppedAt: string | null, nowMs: number): "Accept" | "Resume" | null;
+/**
+ * One entry per job, newest activity first: `headRunid` is the job's newest run BY TIME (never "the first row in server order"), `activityMs` the
+ * newest KNOWN time over its runs (`stoppedAt`, else `at`), `quiet` only when that time is known and older than the quiet limit. A job with a live
+ * run is never quiet; an unknown age is never guessed into quiet.
+ * @param {any[]} rows `listRuns` rows @param {number} nowMs
+ * @returns {{job: string, headRunid: string|null, quiet: boolean, activityMs: number|null}[]}
+ */
+export function summarizeJobs(rows: any[], nowMs: number): {
+    job: string;
+    headRunid: string | null;
+    quiet: boolean;
+    activityMs: number | null;
+}[];
 /**
  * `GET /api/runs` — every listed run, NEWEST FIRST BY `at` (never by file/
  * append order — a backfill scan appends rows in sorted-PATH order, which
@@ -197,12 +256,53 @@ export function getStopContext(runid: string, opts?: {
  * SAME payload by job client-side (`groupRunsByJob` in `index.html`) rather
  * than a second server-side endpoint, so the glyph/checkType mapping is
  * still computed in exactly one place.
- * @param {{ home?: string }} [opts]
+ * @param {{ home?: string, now?: number }} [opts] `now` (ms) is injectable for the Needs-you age rule
  * @returns {any[]}
  */
 export function listRuns(opts?: {
     home?: string;
+    now?: number;
 }): any[];
+/**
+ * `GET /api/runs` (P9 v2 F): `{runs, jobs, limits}`. The server decides every state the left list draws — `live`, `needs`, each job's head run and
+ * quiet flag, the limits — and the page works out nothing. `scheduled` is the triggers piece (PRD v1.99, T Part 7).
+ * @param {{ home?: string, now?: number, schedules?: ReturnType<typeof createScheduleDoor> }} [opts]
+ */
+export function runsListPayload(opts?: {
+    home?: string;
+    now?: number;
+    schedules?: ReturnType<typeof createScheduleDoor>;
+}): {
+    runs: any[];
+    jobs: {
+        job: string;
+        headRunid: string | null;
+        quiet: boolean;
+        activityMs: number | null;
+    }[];
+    scheduled: any[];
+    gaveUp: any[];
+    limits: Readonly<{
+        quietDays: 30;
+        olderRuns: 7;
+        needsYouDays: 7;
+    }>;
+};
+/**
+ * T Part 8 — what the Accept route needs: the run's row, whether its runner is alive, whether it waits at its review door
+ * ({@link doorWaiting}), and the signed spec it was judged by (the file and hash `run-u --door --approve` takes).
+ * @param {string} runid @param {{ home?: string }} opts
+ * @returns {{row: any, live: boolean, waiting: boolean, specPath: string|null, specHash: string|null}|null}
+ */
+export function getAcceptContext(runid: string, opts?: {
+    home?: string;
+}): {
+    row: any;
+    live: boolean;
+    waiting: boolean;
+    specPath: string | null;
+    specHash: string | null;
+} | null;
 /**
  * `GET /api/runs/:runid` — the full replay for the Run tab: steps (or
  * iterations), counters, summary-box fields. Looks `runid` up in the run
@@ -210,11 +310,12 @@ export function listRuns(opts?: {
  * header); `null` when the runid is not in the list at all (caller renders
  * 404).
  * @param {string} runid
- * @param {{ home?: string }} [opts]
+ * @param {{ home?: string, schedules?: ReturnType<typeof createScheduleDoor> }} [opts]
  * @returns {any|null}
  */
 export function getRunDetail(runid: string, opts?: {
     home?: string;
+    schedules?: ReturnType<typeof createScheduleDoor>;
 }): any | null;
 /**
  * `GET /api/runs/:runid/audit` — the Audit tab's rows, off the run's own
@@ -343,11 +444,12 @@ export function inputsTextFromSpec(spec: any, source: string): string;
  * from the resolved SPEC only (a) (b) (c) — a job-start record and `none()`
  * carry no close/writeScope/tools at all, so those stay `'not recorded'`.
  * @param {string} runid
- * @param {{ home?: string }} [opts]
+ * @param {{ home?: string, schedules?: ReturnType<typeof createScheduleDoor> }} [opts]
  * @returns {any|null}
  */
 export function getRunJob(runid: string, opts?: {
     home?: string;
+    schedules?: ReturnType<typeof createScheduleDoor>;
 }): any | null;
 /**
  * The track record of a WORKFLOW: every LISTED run whose signed spec (the one its latest leg ran under) has this
@@ -395,14 +497,14 @@ export function reuseLine(record: {
 } | null): string;
 /**
  * `start-from` (the route keeps its name) for one listed run: the card prefilled from the run's SIGNED job, which
- * boxes are locked and which are open, and the track record. Locked boxes carry the signed values, read by the
+ * the track record (v1.101: nothing is locked, every box is open). The job boxes carry the signed values, read by the
  * SAME readers the Job tab uses (`successFromSpec`/`guardrailsFromSpec`); the open four — Source, Destination, the
  * $ cap and the Time cap — start at what the run had. `ok:false` when the run's signed job is not on disk (nothing
  * to copy: change the job: Clear the card). `null` when the runid is not listed.
  * @param {string} runid
  * @param {{ home?: string, model?: string, provider?: string }} [opts] `model` = the Model box's current Name (the estimate counts only runs on that worker); absent = the card's own Model
  * @returns {{ok: true, origin: {runid: string, job: string}, outcome: string|null, card: Record<string, any>, from: 'signed job',
- *   locked: readonly string[], open: readonly string[], note: string|null,
+ *   note: string|null,
  *   specHash: string, workflowKey: string, spec: any, specPath: string, specNamesModel: boolean,
  *   specWorker: {provider: string, endpoint: string, label: string},
  *   trackRecord: ReturnType<typeof trackRecordFor>, line: string}|{ok: false, error: string}|null}
@@ -420,8 +522,6 @@ export function getStartFrom(runid: string, opts?: {
     outcome: string | null;
     card: Record<string, any>;
     from: "signed job";
-    locked: readonly string[];
-    open: readonly string[];
     note: string | null;
     specHash: string;
     workflowKey: string;
@@ -439,6 +539,21 @@ export function getStartFrom(runid: string, opts?: {
     ok: false;
     error: string;
 } | null;
+/**
+ * T Part 3: a job's listed runs, newest first, each with its signed spec (null when not on disk), its terminal outcome and
+ * its parsed spine. The schedule door's gate (`greenFor`) reads this; nothing here builds a run context.
+ * @param {string} job
+ * @param {{ home?: string }} [opts]
+ * @returns {{runid: string, outcome: string|null, spec: any, records: any[]}[]}
+ */
+export function jobRunsOf(job: string, opts?: {
+    home?: string;
+}): {
+    runid: string;
+    outcome: string | null;
+    spec: any;
+    records: any[];
+}[];
 /**
  * The Reuse workflow picker's list: one entry per JOB (same-job identity = `workflowKey`, the one `getStartFrom` uses)
  * that has at least one GREEN local run, newest green first. `runid` = that job's newest green run, so the page hands
@@ -469,7 +584,7 @@ export function listReuseJobs(opts?: {
  * @param {string} id
  * @param {{ home?: string, model?: string, provider?: string }} [opts] `model` as for {@link getStartFrom}
  * @returns {{ok: true, origin: {runid: null, job: string, importId: string}, card: Record<string, any>, from: 'imported job',
- *   locked: readonly string[], open: readonly string[], note: string|null, specHash: string, workflowKey: string, spec: any,
+ *   note: string|null, specHash: string, workflowKey: string, spec: any,
  *   specPath: null, trackRecord: ReturnType<typeof trackRecordFor>, line: string}|{ok: false, error: string}|null}
  */
 export function getStartFromImport(id: string, opts?: {
@@ -485,8 +600,6 @@ export function getStartFromImport(id: string, opts?: {
     };
     card: Record<string, any>;
     from: "imported job";
-    locked: readonly string[];
-    open: readonly string[];
     note: string | null;
     specHash: string;
     workflowKey: string;
@@ -514,7 +627,7 @@ export function getStartFromImport(id: string, opts?: {
  * only `createPanelServer` below always supplies one.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {{ home?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes> }} opts
+ * @param {{ home?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
  */
 export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
     home?: string;
@@ -525,6 +638,7 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
     settingsRoutes?: ReturnType<typeof createSettingsRoutes>;
     runRoutes?: ReturnType<typeof createRunRoutes>;
     importRoutes?: ReturnType<typeof createImportRoutes>;
+    schedules?: ReturnType<typeof createScheduleDoor>;
 }): void;
 /**
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
@@ -545,8 +659,9 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
  * @param {{ port?: number, home?: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: (...a: any[]) => any, bareloopBin?: string,
  *   fetchImpl?: typeof fetch, settleMs?: number, userHome?: string,
- *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string, packageJsonPath?: string }} [opts]
- * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, close: () => Promise<void> }>}
+ *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string, packageJsonPath?: string,
+ *   scheduleNow?: () => number, sessionDeps?: Record<string, any>, schedulerIntervalMs?: number, acceptWaitMs?: number }} [opts] `scheduleNow`, `sessionDeps` and `schedulerIntervalMs` are TEST SEAMS (the schedule clock; createSession's stubs; the scheduler's timer, 0 = none)
+ * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, schedules: ReturnType<typeof createScheduleDoor>, scheduler: ReturnType<typeof createScheduler>, close: () => Promise<void> }>}
  */
 export function createPanelServer(opts?: {
     port?: number;
@@ -561,10 +676,16 @@ export function createPanelServer(opts?: {
     openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
     platform?: string;
     packageJsonPath?: string;
+    scheduleNow?: () => number;
+    sessionDeps?: Record<string, any>;
+    schedulerIntervalMs?: number;
+    acceptWaitMs?: number;
 }): Promise<{
     server: import("node:http").Server;
     port: number;
     token: string;
+    schedules: ReturnType<typeof createScheduleDoor>;
+    scheduler: ReturnType<typeof createScheduler>;
     close: () => Promise<void>;
 }>;
 /**
@@ -604,13 +725,21 @@ export const DEFAULT_PORT: 4700;
  */
 export const SOFTGREEN_ADMITTED_ISO: "2026-08-18T00:00:00.000Z";
 export { DIED_MTIME_MS };
+/** The named limits of the runs list, in ONE place (P9 v2 D.13): quiet after 30 days, 7 older runs shown, a Resume tag ages out after 7 days. Sent in `GET /api/runs`; the page reads them from there. */
+export const RUNS_LIST_LIMITS: Readonly<{
+    quietDays: 30;
+    olderRuns: 7;
+    needsYouDays: 7;
+}>;
 /** The default/max page size for {@link getRunRounds} — tighten-only,
  * named so a future change is a deliberate, visible edit (item 5,
  * 2026-09-25). */
 export const ROUNDS_PAGE_DEFAULT: 50;
 export const ROUNDS_PAGE_MAX: 200;
+import { createScheduleDoor } from './schedules.js';
 import { createAuthorRoutes } from './authorroutes.js';
 import { createSettingsRoutes } from './settingsroutes.js';
 import { createRunRoutes } from './runroutes.js';
 import { createImportRoutes } from './importroutes.js';
+import { createScheduler } from './scheduler.js';
 import { DIED_MTIME_MS } from '../runlist.js';

package/types/planrun.d.ts

@@ -523,6 +523,8 @@ export const FORBIDDEN_WRITE_SEGMENT_PATTERN: RegExp;
 export const BOUND_REASON_MAX: 200;
 /** the recorded reason for a step attempt whose round was cut at the output cap (F122 2A b) */
 export const TRUNCATED_REASON: "output cut at the token limit (max_tokens)";
+/** the plain sentence for a replan answer cut off at its length limit (hamr 2026-10-16, run mv9gm796) */
+export const REPLAN_CUT_WORDS: "The replan answer was cut off at its length limit, so no new plan came back.";
 export type CategorizedError = Error & {
     category?: string;
     lib?: string;

package/types/providerrows.d.ts

@@ -251,8 +251,8 @@ export function judgeRowFor(rows: readonly KeyRow[], judge: {
  * the worker's own provider it calls the worker's endpoint, so a row on that endpoint with a line
  * NAMED for the judge's model prices it ({@link ratesFor}); a judge model that is absent or names
  * no line there keeps the worker's price (the worker's row, or none = the guess). A different
- * provider resolves with no endpoint. The judge's KEY is chosen elsewhere (`applyConfiguredKey`,
- * by the worker's model), so the two can come from different rows.
+ * provider resolves with no endpoint. The judge's KEY is chosen elsewhere (`judgeRowFor`:
+ * the worker's own row when the judge shares its provider), so the two can come from different rows.
  * @param {{ provider: string, model?: string|null }} judge
  * @param {string|null|undefined} workerProvider
  * @param {string|null|undefined} workerBaseUrl

package/types/reviewdoor.d.ts

@@ -4,6 +4,33 @@
  * @param {any[]} events the run's spine, parsed
  * @returns {any|null} */
 export function doorRecordOf(events: any[]): any | null;
+/**
+ * Was this run's door ACCEPTED, honoured? A `door-decision` record with `decision: 'accept'` and `honoured: true`
+ * (written by {@link answerReviewDoor}, whichever surface asked: the CLI, or the panel's Accept). Pure, off the
+ * run's spine. A refused accept (`honoured: false`) does not count.
+ * @param {any[]} events the run's spine, parsed
+ * @returns {boolean}
+ */
+export function doorAccepted(events: any[]): boolean;
+/**
+ * T D.2 — a SCHEDULED run's green is held until the person accepts it (T10): a run that carries a `trigger.json` (a scheduled
+ * start wrote it) and holds no honoured accept. One shared predicate: `getStartFrom` reads its outcome as `'green-held'` (so
+ * the Reuse start refuses it unchanged), `listReuseJobs` skips it, and the schedule gate does not count it. A hand run is never held.
+ * @param {any[]} events the run's spine, parsed @param {any} triggerRec the run's `trigger.json`, or null
+ * @returns {boolean}
+ */
+export function heldScheduled(events: any[], triggerRec: any): boolean;
+/**
+ * Is this run WAITING for the person's Accept? Its spine holds a door record, the door has not expired ({@link doorAgeGate}),
+ * and no honoured `accept` or `rerun` decision follows it (a `pause` keeps the same three doors open). One owner: the runs
+ * list's Needs-you `Accept` tag, the Run tab's Accept button and the scheduled NEXT line all read this.
+ * @param {any[]} events the run's spine, parsed
+ * @param {{now?: () => number}} [opts]
+ * @returns {boolean}
+ */
+export function doorWaiting(events: any[], opts?: {
+    now?: () => number;
+}): boolean;
 /**
  * IS THE DOOR STILL OPEN? The same 60-day TTL a hitl checkpoint keeps
  * (`PAUSE_TTL_MS`) and deliberately the same NUMBER — the door replaced `cancel`

package/types/runlist.d.ts

@@ -67,6 +67,26 @@ export function appendRun(row: RunRow, opts?: {
 export function appendRunEvent(event: RunEvent, opts?: {
     home?: string;
 }): void;
+/**
+ * RULED 2026-10-15 ("Remove from Needs you"): the person took a stopped run's card out of the Needs-you list. ONE row
+ * `{runid, type:'needs-removed', at}` appended beside the run rows; it is not a run, a claim or an event ({@link readRunList}
+ * ignores it, so the monthly limit, the run counter and the scheduler never see it). Nothing is rewritten.
+ * @param {string} runid
+ * @param {{ home?: string, now?: () => number }} [opts]
+ * @returns {string} the `at` written
+ */
+export function appendNeedsRemoved(runid: string, opts?: {
+    home?: string;
+    now?: () => number;
+}): string;
+/**
+ * The newest `needs-removed` time (ms) per run id. An absent file is an empty map; a row with no readable time is not a removal.
+ * @param {{ home?: string }} [opts]
+ * @returns {Map<string, number>}
+ */
+export function readNeedsRemovals(opts?: {
+    home?: string;
+}): Map<string, number>;
 /**
  * @typedef {{ type: 'leg-start', runid: string, leg: number, pid?: number, capUsd?: number, at: string }} LegStart
  * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row

package/types/schedulewords.d.ts

@@ -0,0 +1,135 @@
+/**
+ * What starts the job, in words. `null` (by hand) has no sentence.
+ * @param {Trigger|null|undefined} t @param {string} [home]
+ * @returns {string|null}
+ */
+export function scheduledWords(t: Trigger | null | undefined, home?: string): string | null;
+/** "Mon 13 Oct, 09:00" — local time, fixed English names (never the machine's locale). @param {number} ms */
+export function slotWords(ms: number): string;
+/**
+ * The Scheduled card's first line: "today 17:00", "tomorrow 09:00", else the date the NEXT line already says
+ * ("Tue 20 Oct, 09:05"). Local time, by calendar day. @param {number} ms the next run @param {number} now
+ */
+export function nextTimeWords(ms: number, now: number): string;
+/** "next in 20m" / "next in 3h" / "next in 3d" (whole units, rounded down, never "0m"). @param {number} ms @param {number} now */
+export function nextInWords(ms: number, now: number): string;
+/**
+ * NEXT of a scheduled job: one sentence, first match wins.
+ *  1. a run of this job is waiting for the person's Accept (the next scheduled run does NOT wait for it, T7);
+ *  2. the latest outcome this month is `monthly-exhausted` (amounts from the row), RED;
+ *  3. a clock kind with a next slot; 4. a file kind that is armed; 5. not armed yet.
+ * A last outcome of `refused` goes in front of 3-5, so a trigger that cannot start is never silent.
+ * `red` is the typed flag for "the person must act": the page paints it and never guesses from the text.
+ * @param {{trigger: Trigger, armed: boolean, nextSlotMs: number|null, lastOutcome: any, waitingRunNo: number|null, now: number, retryInMs?: number|null, gaveUp?: any}} f
+ *   `lastOutcome` = the newest outcome row of the CURRENT signing (`kind`, `at` in ms, `why`, `leftUsd`, `needUsd`, `atLeast`)
+ * @returns {{text: string, red: boolean}}
+ */
+export function scheduledNextFor(f: {
+    trigger: Trigger;
+    armed: boolean;
+    nextSlotMs: number | null;
+    lastOutcome: any;
+    waitingRunNo: number | null;
+    now: number;
+    retryInMs?: number | null;
+    gaveUp?: any;
+}): {
+    text: string;
+    red: boolean;
+};
+/** Is `atMs` in the same local calendar month as `nowMs`? A non-number is never. @param {unknown} atMs @param {number} nowMs */
+export function sameMonthAs(atMs: unknown, nowMs: number): boolean;
+/** RULED 2026-10-15: the red NEXT of a schedule that gave up. @param {unknown} why the refusal's own words */
+export function gaveUpNextWords(why: unknown): string;
+/** The give-up date on the Needs-you card, local `MM/DD HH:MM`. @param {number} ms */
+export function gaveUpDateWords(ms: number): string;
+/** RULED 2026-10-15: after an install-needed refusal, the wait that is left, in whole minutes rounded up; '' when no wait. @param {number|null|undefined} ms */
+export function retryWords(ms: number | null | undefined): string;
+/** The fixed catch-up sentence from a run's `trigger.json`. @param {any} rec */
+export function catchUpWords(rec: any): "This run was a catch-up: it started more than 2 minutes after its set time (the panel was off)." | null;
+/**
+ * A spawn error AFTER the consuming row: `tries` releases so far, `max` the bound. Under the bound it will be tried again;
+ * at the bound it stays consumed and says so. @param {string} why @param {number} tries @param {number} max
+ */
+export function lateRefusalWords(why: string, tries: number, max: number): string;
+/** "Thu 10/16 08:15" — local time, fixed English day names. @param {number} ms */
+export function nextSlotShort(ms: number): string;
+/**
+ * Job tab, "Started": how the run began, then its local start time. `rec` = the run's `trigger.json` (null on a hand run).
+ * @param {any} rec @param {number|null} atMs the run's start
+ */
+export function startedWords(rec: any, atMs: number | null): string;
+/**
+ * Audit, first row of a run a schedule started. @param {any} rec `trigger.json` @param {number|null} originNo the origin run's number
+ */
+export function startedAuditWords(rec: any, originNo: number | null): string;
+/**
+ * A fire that started nothing, in plain words. `short` = the SCHEDULE row's `last` reason; else the Audit group's line.
+ * @param {any} row a ledger row (`busy` | `monthly-exhausted` | `refused` | `gave-up`) @param {boolean} [short]
+ */
+export function skippedWords(row: any, short?: boolean): string;
+/**
+ * Job tab, "Schedule": the job's schedule NOW and what it is bound to. The first part IS the Run tab's line ({@link scheduledWords}),
+ * first letter lowered, so the two can never disagree.
+ * @param {{trigger: Trigger|null, originNo: number|null, model: string|null, destination: string|null, home?: string}} f
+ */
+export function jobScheduleWords(f: {
+    trigger: Trigger | null;
+    originNo: number | null;
+    model: string | null;
+    destination: string | null;
+    home?: string;
+}): string;
+/** RULED 2026-10-15: the SCHEDULE row's `next` while an install-needed refusal is waiting to be tried again. @param {number} ms */
+export function retryNextWords(ms: number): string;
+/**
+ * RULED 2026-10-15: the sign on the head of the Audit's `schedule` section. ONE small rule (hamr may still adjust it): [▶] only while a
+ * run of the job is running (as everywhere in the panel), [✗] when the SCHEDULE row is red, else [·] (on, waiting).
+ * @param {{running: boolean, red: boolean}} f @returns {{sign: string}}
+ */
+export function scheduleSignFor(f: {
+    running: boolean;
+    red: boolean;
+}): {
+    sign: string;
+};
+/** Audit schedule section, the `this run` words of a run the schedule started (the head already says which schedule and from where). @param {any} rec `trigger.json` */
+export function sectionThisRunWords(rec: any): string;
+/** Audit schedule section, folded tail: `1 try started nothing` / `N tries started nothing`; '' for none. @param {number} n */
+export function triesTailWords(n: number): string;
+/**
+ * Every schedule button/word the page shows lives here, so a reword is ONE edit (hamr will reword on his walk).
+ * The server sends this table with the run detail and the schedule card; the page reads every label from it.
+ */
+export const SCHEDULE_WORDS: Readonly<{
+    byHand: "By hand";
+    cancelSchedule: "Cancel schedule";
+    cancelWords: "Cancel schedule";
+    scheduleRun: "Schedule run";
+    cancelModify: "Cancel / modify schedule";
+    signSchedule: "Sign schedule";
+    nothingChanged: "Nothing changed yet. This card only sets or adjusts the schedule; it never runs the job.";
+    confirmPrefix: "Confirm: ";
+    whenLabel: "When";
+    nowPrefix: "Now: ";
+    scheduledLabel: "SCHEDULE";
+    nextLabel: "NEXT";
+    options: Readonly<{
+        hand: "By hand";
+        daily: "Every day at HH:MM";
+        weekdays: "Weekdays at HH:MM";
+        weekly: "Every <day> at HH:MM";
+        'file-updated': "When <file> is updated";
+        'new-file': "When a new file arrives in <folder>";
+    }>;
+    gaveUpPill: "Check";
+    problemNext: "next: fix it in Cancel / modify schedule";
+    monthNext: "next: raise the limit in Settings, or it starts on the 1st";
+    acceptWaiting: "waiting for your Accept (the next run does not wait)";
+    scheduleGroup: "schedule";
+    notGreen: "This job has not had a good run yet. Run it by hand and get it right first; then you can set when it runs. A rubric job also needs your Accept once. Nothing was changed.";
+    stale: "What you were shown is not what is on the card now. Nothing was signed. Look again, then sign.";
+}>;
+export function dateTimeWords(ms: number): string;
+export function lowerFirst(s: string): string;
+export type Trigger = import("./trigger.js").Trigger;

package/types/trigger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The only way a trigger enters the system. Returns the typed trigger, or says what to fix (and which field).
+ * @param {unknown} t
+ * @returns {{ok: true, trigger: Trigger} | {ok: false, say: string, code: 'invalid-value'|'unknown-field', path: string}}
+ */
+export function validateTrigger(t: unknown): {
+    ok: true;
+    trigger: Trigger;
+} | {
+    ok: false;
+    say: string;
+    code: "invalid-value" | "unknown-field";
+    path: string;
+};
+/** @typedef {import('./triggerclock.js').Schedule | {kind:'new-file', folder:string} | {kind:'file-updated', path:string}} Trigger */
+export const TRIGGER_KINDS: readonly string[];
+export const CLOCK_KINDS: readonly string[];
+export const FILE_KINDS: readonly string[];
+export function isClockTrigger(t: unknown): t is {
+    kind: "daily" | "weekdays" | "weekly";
+    hour: number;
+    minute: number;
+};
+export function isFileTrigger(t: unknown): t is {
+    kind: "new-file";
+    folder: string;
+} | {
+    kind: "file-updated";
+    path: string;
+};
+export type Trigger = import("./triggerclock.js").Schedule | {
+    kind: "new-file";
+    folder: string;
+} | {
+    kind: "file-updated";
+    path: string;
+};