bareloop 0.42.0 → 0.44.0

package/src/panel/jobplan.js

@@ -11,7 +11,7 @@
 // `cls` is 'machine check' | 'judge' | null (null = not known yet: the confirm card's checks are the model's plan, the
 // stage kinds exist only after drafting). Pure; no file IO.
 import { KIND_CATALOGUE } from '../authoring.js';
-import { checksOfClose, proseNotChecked, lineRules } from '../rubricstep.js';
+import { checksOfClose, proseNotChecked, lineRules, confirmedGoalOf } from '../rubricstep.js';
 
 /** @typedef {{name: string, cls: 'machine check'|'judge'|null}} PlanCheck */
 /** @typedef {{n: number, text: string, rule: string, rules: string[], checks: PlanCheck[], refused: string[]}} PlanLine */
@@ -100,7 +100,9 @@ export function planFromSpec(spec) {
     if (line && typeof r.reason === 'string') line.refused.push(ruleText ? `"${ruleText}" — ${r.reason}` : r.reason);
   }
   // the model's signed goal sentence rides along: the page draws it as the "AI's summary" row (an older job shows it as line 1 instead)
-  return { lines, loose, notChecked: notes, alwaysOn, older: false, ...(typeof spec?.goal === 'string' && spec.goal ? { goal: spec.goal } : {}) };
+  // (a rubric job's signed goal is the whole worker brief: only the sentence the person confirmed is the summary)
+  const summary = typeof spec?.goal === 'string' && spec.goal ? confirmedGoalOf(spec.goal) : null;
+  return { lines, loose, notChecked: notes, alwaysOn, older: false, ...(summary ? { goal: summary } : {}) };
 }
 
 /**

package/src/panel/runroutes.js

@@ -16,12 +16,16 @@ import {
   openSync, closeSync, writeFileSync, readFileSync, readdirSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { checkHumanGuard } from './authorroutes.js';
+import {
+  checkHumanGuard, OLD_JOB_ACCEPT_WORDS, OLD_JOB_RESUME_WORDS, OLD_JOB_RERUN_WORDS, OLD_JOB_PAUSE_WORDS,
+} from './authorroutes.js';
 import { checkMonthlyRoom, monthlyRefusalText } from '../monthly.js';
 import { ConfigError } from '../config.js';
 import { keysForDoor } from '../keysfile.js';
-import { jobSpecHash } from '../job.js';
+import { jobSpecHash, validateJob } from '../job.js';
 import { stopFilePath } from '../legs.js';
+import { panelMoney2 } from '../panelmoney.js';
+import { appendNeedsRemoved } from '../runlist.js';
 
 /** the tail of an engine log shown to the person when the engine refuses at start (bytes) */
 const LOG_TAIL_BYTES = 4000;
@@ -29,6 +33,9 @@ const LOG_TAIL_BYTES = 4000;
 /** how long a resume waits for an early engine exit before reporting "started" (ms) */
 export const DEFAULT_SETTLE_MS = 6000;
 
+/** how long an Accept waits for the engine's answer (it re-runs the mechanical close stages) before saying it is still checking (ms) */
+export const DEFAULT_ACCEPT_WAIT_MS = 5 * 60_000;
+
 /**
  * The next free `resolved-spec-r<k>.json` name in `dir` (k from 1) — never an existing one.
  * @param {string} dir
@@ -55,6 +62,59 @@ function readLogTail(file) {
   } catch { return ''; }
 }
 
+/**
+ * RULED 2026-10-16: the person never sees raw engine output. Of the engine's log tail, only a line it
+ * owns as a plain sentence passes through (a `Nothing spent.` / `Nothing was spent.` refusal, `DOOR REFUSED (...) — nothing was
+ * recorded...`, `CHECKPOINT EXPIRED — ...`); anything else (validator reds, exit statuses, stack traces, argv) becomes ONE fixed
+ * sentence naming the log. The one owner for the Resume and Accept routes.
+ * @param {string} tail the log tail
+ * @param {'resume'|'accept'|'rerun'|'pause'} kind
+ * @param {string} logFile
+ * @param {(stage: string) => string|null} [questionOf] stage name to the panel's plain question (`null` = none)
+ * @returns {string}
+ */
+export function engineRefusalWords(tail, kind, logFile, questionOf = () => null) {
+  const known = /(?:\bNothing (?:was )?spent\.|^DOOR REFUSED \(.*\) — nothing was recorded|^CHECKPOINT EXPIRED — )/;
+  const raw = /validateJob|red\(s\)|exit status|node-\d|\bat \S+:\d+|\s--[a-z]|^\s*at |Error:/;
+  for (const line of String(tail ?? '').split('\n').map((l) => l.trim())) {
+    if (line !== '' && known.test(line) && !raw.test(line)) {
+      // RULED 2026-10-16 (A): a refused Accept names each failed check by the panel's own plain question
+      const asked = kind === 'accept' ? doorRedStages(tail).map((n) => questionOf(n)).filter((q) => typeof q === 'string' && q !== '') : [];
+      if (asked.length > 0) {
+        const shown = asked.slice(0, 3).map((q) => `"${q}"`).join('; ');
+        const more = asked.length > 3 ? ` and ${asked.length - 3} more` : '';
+        return `Accept did not go through: the check ${shown}${more} said no. Nothing was recorded.`;
+      }
+      return line;
+    }
+  }
+  if (kind === 'resume') return `Resume did not start. Nothing was spent on it. The details are in ${logFile}.`;
+  if (kind === 'rerun') return `Rerun did not start. Nothing was spent on it. The details are in ${logFile}.`;
+  if (kind === 'pause') return `Pause did not go through. Nothing was recorded. The details are in ${logFile}.`;
+  return `Accept did not go through. Nothing was recorded. The details are in ${logFile}.`;
+}
+
+/**
+ * The stage names a door-accept-red refusal failed on, read from the engine's own refusal lines (src/userrun.js):
+ * the `door-accept-red:stage.<name> — ...` line and the `<name>  <verdict>` lines of "the mechanical re-run, stage by stage"
+ * whose verdict is not `satisfied`. Names only — the caller maps them to the panel's plain questions.
+ * @param {string} tail
+ * @returns {string[]}
+ */
+function doorRedStages(tail) {
+  /** @type {string[]} */
+  const names = [];
+  let inList = false;
+  for (const line of String(tail ?? '').split('\n')) {
+    const red = /^\s*door-accept-red:stage\.(.+?) — /.exec(line);
+    if (red) { names.push(red[1]); continue; }
+    if (/^\s*the mechanical re-run, stage by stage:/.test(line)) { inList = true; continue; }
+    const row = inList ? /^\s{4}(\S.*?)\s{2,}(\S+)\s*$/.exec(line) : null;
+    if (row && row[2] !== 'satisfied') names.push(row[1]);
+  }
+  return [...new Set(names)];
+}
+
 /**
  * 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):
@@ -62,7 +122,11 @@ function readLogTail(file) {
  * @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
+ *   getStopContext?: (runid: string) => ({row: any, live: boolean, spineExists: boolean}|null),
+ *   getNeedsContext?: (runid: string) => ({row: any, needs: 'Accept'|'Resume'|null}|null),
+ *   getAcceptContext?: (runid: string) => ({row: any, live: boolean, waiting: boolean, specPath: string|null, specHash: string|null}|null),
+ *   stageQuestionsOfSpec?: (spec: any) => Map<string, string|null>,
+ *   acceptWaitMs?: number }} opts
  */
 export function createRunRoutes(opts) {
   const envNow = () => keysForDoor({ env: opts.env, keysHome: opts.home }).env;
@@ -98,6 +162,109 @@ export function createRunRoutes(opts) {
     return true;
   }
 
+  /**
+   * T Part 8 + PRD v1.107 Part 6 — the person's answer to a run waiting at its REVIEW DOOR: `accept`, `rerun` (with their words) or `pause`, recorded through
+   * the library's own door path and nothing else: `run-u --spec <signed spec> --door <runid> --decide <accept|rerun|pause> [--text …] --approve <hash>`
+   * (src/userrun.js, `answerReviewDoor`, src/reviewdoor.js). The panel invents no verdict path: the engine re-runs the MECHANICAL
+   * stages against the tree as it stands for an accept (a red there is `door-accept-red` and refuses), and only then is the disposition written
+   * to the run's own spine. The verdict the run minted is untouched. The engine's own words are what the page shows.
+   * An accept and a pause end when the engine does; a RERUN launches a fresh engagement (a paid run), so it answers like Resume: started, or the engine's refusal.
+   * @param {import('node:http').IncomingMessage} req
+   * @param {(code: number, obj: any) => void} send
+   * @param {string} runid
+   * @param {'accept'|'rerun'|'pause'} decide
+   * @param {any} body the request body (`text` for a rerun)
+   * @returns {boolean}
+   */
+  function handleDoor(req, send, runid, decide, body) {
+    const guard = checkHumanGuard(req, { token: opts.token, port: opts.port });
+    if (!guard.ok) { send(403, { ok: false, error: `refused — ${guard.reason}` }); return true; }
+    if (req.method !== 'POST') { send(405, { ok: false, error: 'POST only' }); return true; }
+    const ctx = opts.getAcceptContext ? opts.getAcceptContext(runid) : null;
+    if (!ctx) { send(404, { ok: false, error: 'no such run' }); return true; }
+    if (ctx.live) { send(409, { ok: false, error: decide === 'accept' ? 'This run is still running, so there is nothing to accept yet.' : `This run is still running, so there is nothing to ${decide} yet.` }); return true; }
+    if (!ctx.waiting) { send(409, { ok: false, error: decide === 'accept' ? 'This run is not waiting for your Accept (it opened no review door, the door was already answered, or it has expired).' : `This run is not waiting for your answer, so it cannot be ${decide === 'rerun' ? 'rerun' : 'paused'} (it opened no review door, the door was already answered, or it has expired).` }); return true; }
+    // a rerun's words ARE the gap the worker is given: empty words are refused here in plain words (the engine refuses them too, src/kinds.js normalizeHumanRuling)
+    const text = decide === 'rerun' && typeof body?.text === 'string' ? body.text.trim() : '';
+    if (decide === 'rerun' && text === '') { send(400, { ok: false, error: 'Write what you want done differently, then press Rerun. Your words are what the next attempt is given.' }); return true; }
+    if (!ctx.specPath || !ctx.specHash) { send(409, { ok: false, error: "The signed job this run was judged by cannot be found on disk, so its door cannot be answered from here. Nothing was recorded." }); return true; }
+    // RULED 2026-10-15: an old run whose saved job fails today's checks is refused at $0 in plain words, before any spawn
+    /** @type {any} */
+    let signed = null;
+    try { signed = JSON.parse(readFileSync(ctx.specPath, 'utf8')); } catch { signed = null; }
+    if (signed !== null) {
+      let jv;
+      try { jv = validateJob(signed, { shellCapUsd: signed.budgetUsd }); } catch { jv = { ok: false, reds: [] }; }
+      if (!jv.ok) {
+        const words = decide === 'accept' ? OLD_JOB_ACCEPT_WORDS : (decide === 'rerun' ? OLD_JOB_RERUN_WORDS : OLD_JOB_PAUSE_WORDS);
+        send(409, { ok: false, error: words, reds: jv.reds.map((r) => `${r.code} at ${r.path}`) });
+        return true;
+      }
+    }
+    const questionOf = (/** @type {string} */ n) => (signed !== null && opts.stageQuestionsOfSpec ? opts.stageQuestionsOfSpec(signed).get(n) ?? null : null);
+    const dir = dirname(ctx.specPath);
+    const logFile = join(dir, `${decide}-${runid}-${Date.now()}.log`);
+    const args = [
+      '--wait', 'systemd-inhibit', `--why=bareloop panel ${decide}`,
+      process.execPath, bareloopBin,
+      'run-u', '--spec', ctx.specPath, '--door', runid, '--decide', decide, '--approve', ctx.specHash,
+      // last, so no flag lookup in the engine can land on the person's words
+      ...(decide === 'rerun' ? ['--text', text] : []),
+    ];
+    /** @type {number|null} */
+    let logFd = null;
+    try { logFd = openSync(logFile, 'a'); } catch { logFd = null; }
+    const child = spawnFn('setsid', args, { detached: true, stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'], env: envNow() });
+    if (logFd !== null) { try { closeSync(logFd); } catch { /* the child holds its own copy */ } }
+    if (typeof child?.unref === 'function') child.unref();
+    let done = false;
+    const finish = (/** @type {number} */ code, /** @type {any} */ obj) => { if (!done) { done = true; send(code, obj); } };
+    const answered = { accept: { accepted: true }, rerun: { rerunning: true }, pause: { paused: true } }[decide];
+    // an accept that outlasts the wait is still going: say so (202), never claim it passed. A rerun is a run: it is "started" once it outlives the settle window.
+    const timer = setTimeout(
+      () => (decide === 'rerun' ? finish(200, { ok: true, ...answered, runid, log: logFile }) : finish(202, { ok: true, pending: true, runid, log: logFile })),
+      decide === 'rerun' ? settleMs : (opts.acceptWaitMs ?? DEFAULT_ACCEPT_WAIT_MS),
+    );
+    if (typeof timer.unref === 'function') timer.unref();
+    if (typeof child?.once === 'function') {
+      child.once('exit', (/** @type {number|null} */ code) => {
+        clearTimeout(timer);
+        if (code === 0) finish(200, { ok: true, ...answered, runid, log: logFile });
+        else finish(409, { ok: false, error: engineRefusalWords(readLogTail(logFile), decide, logFile, questionOf), log: logFile });
+      });
+      child.once('error', (/** @type {Error} */ e) => {
+        clearTimeout(timer);
+        finish(500, { ok: false, error: `could not start the engine: ${e.message}` });
+      });
+    }
+    return true;
+  }
+
+  /**
+   * RULED 2026-10-15 — `POST /api/runs/:runid/needs-remove`. Takes a stopped run's card out of Needs you and does nothing else: ONE
+   * `needs-removed` row appended to runs.jsonl (status, the run's row, Resume and Reuse workflow are untouched). Refused (409) unless the run
+   * is in Needs you with the Resume tag right now; a run waiting for the person's Accept is never removable. A second click finds it already out.
+   * @param {import('node:http').IncomingMessage} req
+   * @param {(code: number, obj: any) => void} send
+   * @param {string} runid
+   * @returns {boolean}
+   */
+  function handleNeedsRemove(req, send, runid) {
+    const guard = checkHumanGuard(req, { token: opts.token, port: opts.port });
+    if (!guard.ok) { send(403, { ok: false, error: `refused — ${guard.reason}` }); return true; }
+    if (req.method !== 'POST') { send(405, { ok: false, error: 'POST only' }); return true; }
+    const ctx = opts.getNeedsContext ? opts.getNeedsContext(runid) : null;
+    if (!ctx) { send(404, { ok: false, error: 'no such run' }); return true; }
+    if (ctx.needs === 'Accept') { send(409, { ok: false, error: 'This run is waiting for your Accept, so it stays in Needs you until you answer it.' }); return true; }
+    if (ctx.needs !== 'Resume') { send(409, { ok: false, error: 'This run is not in Needs you, so there is nothing to remove.' }); return true; }
+    try { appendNeedsRemoved(runid, { home: opts.home }); } catch (e) {
+      send(500, { ok: false, error: `could not record it: ${/** @type {Error} */ (e).message}` });
+      return true;
+    }
+    send(200, { ok: true, runid, removed: true });
+    return true;
+  }
+
   /**
    * @param {import('node:http').IncomingMessage} req
    * @param {import('node:http').ServerResponse} res
@@ -108,13 +275,21 @@ export function createRunRoutes(opts) {
   function handle(req, res, pathname, body) {
     const stopM = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/stop$/.exec(pathname);
     const m = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/resume$/.exec(pathname);
-    if (!m && !stopM) return false;
+    const acceptM = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/accept$/.exec(pathname);
+    const rerunM = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/rerun$/.exec(pathname);
+    const pauseM = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/pause$/.exec(pathname);
+    const needsM = /^\/api\/runs\/([A-Za-z0-9._~-]+)\/needs-remove$/.exec(pathname);
+    if (!m && !stopM && !acceptM && !needsM && !rerunM && !pauseM) return false;
     const send = (/** @type {number} */ code, /** @type {any} */ obj) => {
       const text = JSON.stringify(obj);
       res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
       res.end(text);
     };
     if (stopM) return handleStop(req, send, stopM[1]);
+    if (acceptM) return handleDoor(req, send, acceptM[1], 'accept', body);
+    if (rerunM) return handleDoor(req, send, rerunM[1], 'rerun', body);
+    if (pauseM) return handleDoor(req, send, pauseM[1], 'pause', body);
+    if (needsM) return handleNeedsRemove(req, send, needsM[1]);
     if (!m) return false;
     const guard = checkHumanGuard(req, { token: opts.token, port: opts.port });
     if (!guard.ok) { send(403, { ok: false, error: `refused — ${guard.reason}` }); return true; }
@@ -125,6 +300,13 @@ export function createRunRoutes(opts) {
     const { plan } = ctx;
     if (!plan.ok) { send(409, { ok: false, error: `Resume is not available for this run (${plan.why}).` }); return true; }
 
+    // RULED 2026-10-16: like Accept, an old run whose saved job fails today's checks is refused at $0 in plain words, before any spawn
+    {
+      let jv;
+      try { jv = validateJob(plan.spec, { shellCapUsd: plan.spec.budgetUsd }); } catch { jv = { ok: false, reds: [] }; }
+      if (!jv.ok) { send(409, { ok: false, error: OLD_JOB_RESUME_WORDS, reds: jv.reds.map((r) => `${r.code} at ${r.path}`) }); return true; }
+    }
+
     // the caps: blank/absent = the signed ones. A raised (or lowered) cap is a new spec.
     /** @type {any} */
     const spec = { ...plan.spec };
@@ -142,7 +324,7 @@ export function createRunRoutes(opts) {
     // tighten-only: a cap at or below what the run has ALREADY used buys an immediate re-halt
     // (the engine only warns), so it is refused here at $0, before anything is written or spawned
     if (typeof plan.spentUsd === 'number' && spec.budgetUsd <= plan.spentUsd) {
-      send(400, { ok: false, error: `The money cap must be above what is already spent (${plan.spendComplete ? '' : 'at least '}$${plan.spentUsd.toFixed(2)}) — raise it, then Resume.` });
+      send(400, { ok: false, error: `The money cap must be above what is already spent (${plan.spendComplete ? '' : 'at least '}${panelMoney2(plan.spentUsd)}) — raise it, then Resume.` });
       return true;
     }
     if (typeof plan.wallUsedMs === 'number' && typeof spec.maxWallMs === 'number' && spec.maxWallMs <= plan.wallUsedMs) {
@@ -207,7 +389,7 @@ export function createRunRoutes(opts) {
             ok: true, runid: m[1], specHash, capsChanged: changed, log: logFile,
           });
         } else {
-          finish(409, { ok: false, error: readLogTail(logFile) || `the engine refused to resume (exit ${code}) and left no message`, log: logFile });
+          finish(409, { ok: false, error: engineRefusalWords(readLogTail(logFile), 'resume', logFile), log: logFile });
         }
       });
       child.once('error', (/** @type {Error} */ e) => {

package/src/panel/scheduler.js

@@ -0,0 +1,156 @@
+// T Part 5 (PANEL-BUILD.md T addendum, C.5): the panel's scheduler. The panel server runs the clock and the folder watch
+// while it is up; with the panel off nothing fires (T6), and slots missed collapse to ONE catch-up when it comes back.
+//
+// ONE `tick()` does the sync work; the tests call it by hand with an injected clock and await what it returns (the fires
+// it started). The real timer only calls it.
+//   - 500 ms: the folder watch needs a file's size and mtime to hold for STABLE_POLLS (2) polls, so a drop is seen about
+//     1.5 s after it stops changing. Poll only, never fs.watch (EMFILE on hamr's machine, and it misses atomic renames).
+//   - the timer is unref'd, `start`/`stop` are idempotent, the server's close calls `stop`.
+//   - with no schedule on disk a tick is one readdir and nothing else (no runs.jsonl read).
+// What a tick does for one job with a signed schedule:
+//   1. arm it if it is not armed under this signing (a crash between the sign and the arm);
+//   2. clock kinds: `due`; a due slot goes to `door.fire` and is NOT consumed up front: the starter's `beforeSpawn` writes
+//      the `fire` row only after busy, monthly, wouldAccept and the session all said yes, so a refused slot retries;
+//   3. file kinds: `poll`; each file taken is recorded `arrived` (THIS is the only writer of `arrived` rows), then the
+//      queue runs: busy tells each queued file once and waits; free, the head is looked at again (deleted or changed is
+//      dropped with a reason, the next head is tried) and goes through `door.fire`; `ran` is written by `beforeSpawn` only.
+// One job's exception is written once as a `refused` row and never stops the others (fwd scheduler.js:94-110).
+// BUSY IS CHEAP (T19): the run list is read at most ONCE per tick, and only when a fire or a queued head needs it.
+// Rewritten from fwdloop src/panel/scheduler.js.
+import { due } from '../triggerclock.js';
+import { isClockTrigger, isFileTrigger } from '../trigger.js';
+import { appendRow, readLedger } from '../triggerledger.js';
+import {
+  createFileTrigger, queueOf, readSeen, recheck, recordArrived, recordDropped, recordRan,
+} from '../triggerfiles.js';
+import { recordFire } from '../triggerclock.js';
+
+/**
+ * @param {{ door: ReturnType<typeof import('./schedules.js').createScheduleDoor>, now?: () => number, intervalMs?: number }} opts
+ *   `intervalMs` 0 = no timer (a test drives `tick`).
+ */
+export function createScheduler(opts) {
+  const { door, now = Date.now, intervalMs = 500 } = opts;
+  /** @type {Map<string, ReturnType<typeof createFileTrigger>>} */
+  const watchers = new Map();
+  /** `job|sig` keys already armed this process @type {Set<string>} */
+  const armedKeys = new Set();
+  /** jobs with a fire still awaiting its start (a headless prepare can take minutes): never fired a second time meanwhile @type {Set<string>} */
+  const inflight = new Set();
+  /** @type {ReturnType<typeof setInterval>|null} */
+  let timer = null;
+
+  /**
+   * The queue of a file trigger (arrived minus ran minus dropped, oldest first).
+   * @param {string} job @param {string} ledger @param {string} sig @param {number} nowMs @param {() => boolean} isBusy @param {Promise<unknown>[]} pending
+   */
+  function runQueue(job, ledger, sig, nowMs, isBusy, pending) {
+    let queue = queueOf(readSeen(ledger));
+    if (queue.length === 0 || inflight.has(job)) return;
+    const busy = isBusy();
+    if (busy) {
+      // every queued file is told ONCE (`busy`, once per sha) and waits
+      for (const q of queue) pending.push(door.fire(job, { kind: 'file', path: q.path, sha: q.sha, size: q.size }, { busy: true }));
+      return;
+    }
+    while (queue.length > 0) {
+      const q = queue[0];
+      const seen = recheck(q);
+      if (seen.state !== 'ok') {
+        const why = seen.state === 'deleted' ? 'deleted' : 'changed';
+        recordDropped(ledger, q, why, nowMs, sig);
+        appendRow(ledger, {
+          kind: why, sig, at: nowMs, sha: q.sha, file: q.path,
+          say: seen.state === 'deleted' ? `${q.name} did not run: ${seen.say}.` : `${q.name} did not run: it changed before its turn; the new version arrives again.`,
+        });
+        queue = queue.slice(1);
+        continue;
+      }
+      const item = { path: seen.path, sha: seen.sha, size: seen.size };
+      pending.push(startFire(job, { kind: 'file', ...item }, { busy: false, beforeSpawn: () => { recordRan(ledger, item, nowMs, sig); } }, sig));
+      return;
+    }
+  }
+
+  /**
+   * Fire and remember it is in flight until it settles. A throw is written once and never escapes.
+   * @param {string} job @param {Parameters<ReturnType<typeof import('./schedules.js').createScheduleDoor>['fire']>[1]} cause
+   * @param {{busy?: boolean, beforeSpawn?: () => void}} hooks @param {string} sig
+   */
+  function startFire(job, cause, hooks, sig) {
+    inflight.add(job);
+    return door.fire(job, cause, hooks)
+      .catch((e) => { door.tellOnce(job, sig, `fire|${/** @type {Error} */ (e).message}`, `The run could not start: ${/** @type {Error} */ (e).message}`); })
+      .finally(() => { inflight.delete(job); });
+  }
+
+  /** @returns {Promise<void>} resolves when every fire this tick started has settled */
+  function tick() {
+    const jobs = door.scan();
+    if (jobs.length === 0) { watchers.clear(); armedKeys.clear(); return Promise.resolve(); }
+    const nowMs = now();
+    /** @type {Promise<unknown>[]} */
+    const pending = [];
+    /** the ONE read of the run list this tick, taken the first time a job needs it @type {Map<string, boolean>} */
+    const busyMemo = new Map();
+    const live = new Set();
+    for (const { job, schedule } of jobs) {
+      const sig = schedule.specHash;
+      const key = `${job}|${sig}`;
+      live.add(key);
+      const isBusy = () => {
+        if (!busyMemo.has(job)) busyMemo.set(job, door.busy(job));
+        return /** @type {boolean} */ (busyMemo.get(job));
+      };
+      try {
+        if (!armedKeys.has(key)) { door.armFor(job, schedule); armedKeys.add(key); }
+        const ledger = door.ledgerOf(job);
+        const { trigger } = schedule;
+        if (isFileTrigger(trigger)) {
+          let w = watchers.get(key);
+          if (!w) {
+            w = createFileTrigger({
+              mode: trigger.kind === 'new-file' ? 'new' : 'updated', target: trigger.kind === 'new-file' ? trigger.folder : trigger.path, ledger, sig, now,
+            });
+            watchers.set(key, w);
+          }
+          const { arrived, refused } = w.poll();
+          for (const r of refused) door.tellOnce(job, sig, `refused|${r.path}|${r.why}`, `${r.path}: ${r.why}`);
+          // THE writer of `arrived`: the arrival time is this clock, never the file's mtime
+          for (const f of arrived) recordArrived(ledger, f, nowMs, sig);
+          // RULED 2026-10-15: a schedule that gave up is paused (read from the ledger): files still queue as `arrived`, none runs
+          if (!door.paused(job)) runQueue(job, ledger, sig, nowMs, isBusy, pending);
+        } else if (isClockTrigger(trigger)) {
+          if (inflight.has(job) || door.paused(job)) continue;
+          const d = due(trigger, readLedger(ledger).rows, nowMs);
+          if (d.fire) {
+            pending.push(startFire(job, { kind: 'clock', slot: /** @type {number} */ (d.slot), catchUp: d.catchUp, missed: d.missed },
+              { busy: isBusy(), beforeSpawn: () => { recordFire(ledger, d, nowMs, sig); } }, sig));
+          }
+        }
+      } catch (e) {
+        const why = /** @type {Error} */ (e).message;
+        try { door.tellOnce(job, sig, `tick|${why}`, why); } catch { /* the ledger itself is unwritable: nothing more to do for this job */ }
+      }
+    }
+    for (const k of [...watchers.keys()]) if (!live.has(k)) watchers.delete(k);
+    for (const k of [...armedKeys]) if (!live.has(k)) armedKeys.delete(k);
+    return Promise.all(pending).then(() => undefined);
+  }
+
+  return {
+    tick,
+    /** Start the real timer (idempotent). */
+    start() {
+      if (intervalMs <= 0 || timer !== null) return;
+      timer = setInterval(() => { tick().catch(() => { /* one bad tick never stops the next */ }); }, intervalMs);
+      timer.unref();
+    },
+    /** Stop it (idempotent). The server's close calls this. */
+    stop() {
+      if (timer !== null) { clearInterval(timer); timer = null; }
+    },
+    /** whether the real timer is running (a test reads this) */
+    get running() { return timer !== null; },
+  };
+}