bareloop 0.42.0 → 0.43.0

package/src/planrun.js

@@ -541,6 +541,10 @@ 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 red fed to the redraft when the first replan answer was cut off (plain words, from code) */
+const REPLAN_CUT_RED = 'Your previous answer was cut off at its length limit before the plan was complete. Answer again with a shorter plan that fits.';
+/** 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.';
 
 /**
  * What the NEXT attempt is told about the bound that cut the previous one.
@@ -2232,7 +2236,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * denied, the wallet as its budget), granted tools only (the menu IS the
    * grant), per-attempt round bound via loop.stop() (F20), every round metered
    * with a phase label (F12).
-   * @param {{granted: string[], phase: string, attemptRounds: number, attempts: number|null, writable: boolean, root?: ReturnType<typeof createRoot>|null, fence?: string[]|null, workerProvider?: any}} o
+   * @param {{granted: string[], phase: string, attemptRounds: number, attempts: number|null, writable: boolean, root?: ReturnType<typeof createRoot>|null, fence?: string[]|null, workerProvider?: any, truncatedBounded?: boolean}} o
    *   `root` (Layer R): when present, the worker's write-class actions are teed
    *   for the within-run ratchet — staged before the gate decides, discarded on
    *   deny/halt, settled to landed-or-not after execution (the two axes, F43/F7).
@@ -2242,7 +2246,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    *   STRIKE LADDER (src/ladder.js), where that count does not exist by design — see
    *   the turn-allowance note below.
    */
-  async function mkWorker({ granted, phase, attemptRounds, attempts, writable, root = null, fence = null, workerProvider = null }) {
+  async function mkWorker({ granted, phase, attemptRounds, attempts, writable, root = null, fence = null, workerProvider = null, truncatedBounded = false }) {
     // THE HARD RULE, ENFORCED STRUCTURALLY (PRD v1.57 §3). This is the ONE seam
     // that grants write-class verbs — `writeScope` is empty for every other
     // worker, so a read-only phase cannot reach a file whatever it intends — and
@@ -2825,8 +2829,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // cut round's output is discarded (bare-agent already dropped it), its spend is booked
       // by the per-round meter, the tree is judged as it stands, and the step's strike
       // ladder (or the fix governor) applies unchanged (hamr ruling A extended it to `fix`
-      // after run muux1x96). Scout, drafter, replan keep the transport route below.
-      if (r.error && r.error.startsWith('truncated:') && (phase.startsWith('step:') || phase === 'fix')) {
+      // after run muux1x96). hamr 2026-10-16 (run mv9gm796) extended it to the REPLAN call: the
+      // replan drafter opts in with `truncatedBounded`. Scout and the first draft keep the
+      // transport route below (provider-red).
+      if (r.error && r.error.startsWith('truncated:') && (phase.startsWith('step:') || phase === 'fix' || truncatedBounded)) {
         attemptBounded = { iteration: roundIteration, cause: 'truncated', reason: TRUNCATED_REASON };
         emit('attempt-bounded', { phase, iteration: roundIteration, rounds: roundsThisAttempt, cap: attemptRounds, reason: TRUNCATED_REASON, stopReason: r.stopReason ?? null });
         return r;
@@ -3008,9 +3014,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * the hard line) — a drafter built once at full budget would let the replan
    * draft spend against money the steps had already consumed.
    * @param {string} phase @param {string|null} failure
-   * @param {string} [progress] the meter's read, replan only (A's adaptation channel) */
+   * @param {string} [progress] the meter's read, replan only (A's adaptation channel)
+   * @returns {Promise<{ok: boolean, reds: any[], plan?: any, truncated?: boolean}>} */
   const obtainPlan = async (phase, failure, progress) => {
-    const drafter = await mkWorker({ granted: [], phase: 'plan', attemptRounds: 2, attempts: 3, writable: false });
+    const drafter = await mkWorker({ granted: [], phase: 'plan', attemptRounds: 2, attempts: 3, writable: false, truncatedBounded: phase === 'replan' });
+    /** the LAST draftPlan call was a replan answer cut off at max_tokens: a bounded failed attempt,
+     * never provider-red (hamr 2026-10-16); reset at the start of every call */
+    let replanCut = false;
     // The BALANCE, read live at each draft — never a snapshot and never a rate
     // (addendum 2). At draft it is the whole budget (scale); at replan it is what
     // is actually left, which is the adaptation channel.
@@ -3039,7 +3049,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     };
     const draftPlan = async (/** @type {any[]|null} */ reds) => {
       drafter.setIteration(reds ? 'redraft' : 'draft');
+      replanCut = false;
       const r = await drafter.ask(planPrompt(job, scoutBlob, reds, maxStepRounds, failure, scopeMenu, materials, starting, checkFacts, doorWords?.text ?? null, readShim), []);
+      if (phase === 'replan' && typeof r.error === 'string' && r.error.startsWith('truncated:')) {
+        replanCut = true;
+        return '';
+      }
       return extractArtifact(r.text).code ?? '';
     };
     // Scrubbed HERE, once, before any consumer reads them — the judge() precedent
@@ -3056,10 +3071,17 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       return { ...v, reds: v.reds.map((r) => (typeof r.detail === 'string' ? { ...r, detail: scrub(r.detail) } : r)) };
     };
     let text = await draftPlan(null);
-    let pv = validate(text);
+    // A cut-off replan answer is treated like a BAD one: its half text is never validated (judging
+    // half an artifact would mint a plan-red the drafter never earned), it becomes one plain-words
+    // red fed to the redraft, and a cut REDRAFT (whatever the first answer was) is the bounded
+    // failed attempt the caller escalates in words.
+    let pv = replanCut
+      ? { ok: false, reds: [{ code: 'parse-error', path: '$', detail: REPLAN_CUT_RED }], plan: null }
+      : validate(text);
     emit('plan-validate', { ok: pv.ok, reds: pv.reds, phase: `${phase}-1` });
     if (!pv.ok) {
       text = await draftPlan(pv.reds);
+      if (replanCut) return { ok: false, reds: [], truncated: true };
       pv = validate(text);
       emit('plan-validate', { ok: pv.ok, reds: pv.reds, phase: `${phase}-2` });
     }
@@ -3659,6 +3681,16 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         planExecuted();
         return relay(e, 'replan');
       }
+      if (pv.truncated) {
+        // a bounded failed attempt in plain words, filed as plan-red (a judged no, not a casualty)
+        // with the code-owned sentence on the escalation; the panel reads `cause` to say it
+        emit('escalation', {
+          category: 'plan-red', cause: 'truncated', decisionReady: true, phase: 'replan',
+          decision: REPLAN_CUT_WORDS, options: ['change the job and run it again', 'abandon the run'], detail: TRUNCATED_REASON,
+        });
+        planExecuted();
+        return 'plan-red';
+      }
       if (!pv.ok) {
         for (const r of pv.reds) emit('plan-red', r);
         planExecuted();

package/src/providerrows.js

@@ -9,7 +9,7 @@
 //
 // This module is also THE one owner of "model -> key + shape + URL": Chat's Model menu,
 // the author doors and the run doors all resolve through `findRow` / `keyNameFor` /
-// `applyConfiguredKey` / `modelChoiceFor` below — no second lookup exists. Key VALUES
+// `keyValueOf` / `modelChoiceFor` below — no second lookup exists. Key VALUES
 // never pass through here — only names.
 import { readConfig } from './config.js';
 import { filledKeyNames } from './keysfile.js';
@@ -388,8 +388,8 @@ export function judgeRowFor(rows, judge, workerProvider, workerRow) {
  * 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/src/reviewdoor.js

@@ -50,6 +50,43 @@ export function doorRecordOf(events) {
   return events.findLast?.((e) => e?.type === REVIEW_DOOR) ?? 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) {
+  return Array.isArray(events) && events.some((e) => e?.type === 'door-decision' && e.decision === 'accept' && e.honoured === true);
+}
+
+/**
+ * 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, triggerRec) {
+  return !!triggerRec && typeof triggerRec === 'object' && !doorAccepted(events);
+}
+
+/**
+ * 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, opts = {}) {
+  const door = doorRecordOf(events);
+  if (!door || !doorAgeGate(door, opts.now ? { now: opts.now } : {}).ok) return false;
+  const at = events.lastIndexOf(door);
+  return !events.slice(at + 1).some((e) => e?.type === 'door-decision' && e.honoured === true && (e.decision === 'accept' || e.decision === 'rerun'));
+}
+
 /**
  * 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/src/runlist.js

@@ -128,6 +128,41 @@ export function appendRunEvent(event, opts = {}) {
   try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
 }
 
+/**
+ * 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, opts = {}) {
+  const at = new Date((opts.now ?? Date.now)()).toISOString();
+  const path = runlistPath(opts.home);
+  mkdirSync(runlistHome(opts.home), { recursive: true, mode: 0o700 });
+  appendFileSync(path, `${JSON.stringify({ runid, type: 'needs-removed', at })}\n`);
+  try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
+  return at;
+}
+
+/**
+ * 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 = {}) {
+  /** @type {Map<string, number>} */
+  const out = new Map();
+  const path = runlistPath(opts.home);
+  if (!existsSync(path)) return out;
+  for (const r of parseJsonl(path).records) {
+    if (!r || r.type !== 'needs-removed' || typeof r.runid !== 'string') continue;
+    const t = typeof r.at === 'string' ? Date.parse(r.at) : NaN;
+    if (Number.isFinite(t) && t >= (out.get(r.runid) ?? -Infinity)) out.set(r.runid, t);
+  }
+  return out;
+}
+
 /**
  * @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/src/schedulewords.js

@@ -0,0 +1,296 @@
+// T Part 3 (PANEL-BUILD.md T addendum, C.3 / C.6): the WORDS of a schedule. ONE owner of these strings. Pure
+// functions: typed facts in, a fixed sentence out. No model text ever reaches a sentence (the only slot-fills are
+// numbers, a file or folder name and the person's own path). `home` is injected (never a default inside a test).
+// Rewritten from fwdloop src/summary-words.js (`scheduledWords`, `slotWords`, `nextTimeWords`, `nextInWords`,
+// `scheduledNextFor`, `catchUpWords`), minus `endedWords` and every ask (bareloop has neither:
+// its ENDED block is `endedFor` in src/panel/server.js).
+import { basename } from 'node:path';
+import { panelMoney2 } from './panel/authorroutes.js';
+
+/** @typedef {import('./trigger.js').Trigger} Trigger */
+
+const DAY_PLURAL = { mon: 'Mondays', tue: 'Tuesdays', wed: 'Wednesdays', thu: 'Thursdays', fri: 'Fridays', sat: 'Saturdays', sun: 'Sundays' };
+const DAY_SHORT = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTH_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** @param {number} n */
+const two = (n) => String(n).padStart(2, '0');
+/** @param {{hour: number, minute: number}} s */
+const hhmm = (s) => `${two(s.hour)}:${two(s.minute)}`;
+
+/** A path with the home folder shown as `~`. @param {string} p @param {string|undefined} home */
+function tilde(p, home) {
+  if (home && (p === home || p.startsWith(`${home}/`))) return `~${p.slice(home.length)}`;
+  return p;
+}
+
+/**
+ * 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 = Object.freeze({
+  byHand: 'By hand',
+  cancelSchedule: 'Cancel schedule',
+  cancelWords: 'Cancel schedule',
+  // the Run tab's buttons (never relabelled in place: a different state is a different button)
+  scheduleRun: 'Schedule run',
+  cancelModify: 'Cancel / modify schedule',
+  // the one main button of the schedule card
+  signSchedule: 'Sign schedule',
+  nothingChanged: 'Nothing changed yet. This card only sets or adjusts the schedule; it never runs the job.',
+  confirmPrefix: 'Confirm: ',
+  // the When field and the blocks
+  whenLabel: 'When',
+  nowPrefix: 'Now: ',
+  scheduledLabel: 'SCHEDULE',
+  nextLabel: 'NEXT',
+  options: Object.freeze({
+    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>',
+  }),
+  // RULED 2026-10-15: the Needs-you pill of a schedule that gave up (hamr may reword)
+  gaveUpPill: 'Check',
+  // RULED 2026-10-15 (aligned with fwdloop M9 am7): the SCHEDULE row's second line when the last fire started nothing
+  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.',
+});
+
+/**
+ * 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, home) {
+  if (!t) return null;
+  if (t.kind === 'daily') return `Every day at ${hhmm(t)}`;
+  if (t.kind === 'weekdays') return `Weekdays at ${hhmm(t)}`;
+  if (t.kind === 'weekly') return `${DAY_PLURAL[/** @type {keyof typeof DAY_PLURAL} */ (t.day)] ?? t.day} at ${hhmm(t)}`;
+  if (t.kind === 'file-updated') return `When ${basename(t.path)} is updated`;
+  const folder = tilde(/** @type {{folder: string}} */ (t).folder, home);
+  return `When a new file arrives in ${folder.endsWith('/') ? folder : `${folder}/`}`;
+}
+
+/** "Mon 13 Oct, 09:00" — local time, fixed English names (never the machine's locale). @param {number} ms */
+export function slotWords(ms) {
+  const d = new Date(ms);
+  return `${DAY_SHORT[d.getDay()]} ${d.getDate()} ${MONTH_SHORT[d.getMonth()]}, ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+
+/**
+ * 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, now) {
+  const d = new Date(ms);
+  const day = (/** @type {Date} */ x) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime();
+  const apart = Math.round((day(d) - day(new Date(now))) / 86_400_000);
+  if (apart === 0) return `today ${two(d.getHours())}:${two(d.getMinutes())}`;
+  if (apart === 1) return `tomorrow ${two(d.getHours())}:${two(d.getMinutes())}`;
+  return slotWords(ms);
+}
+
+/** "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, now) {
+  const mins = Math.max(1, Math.floor((ms - now) / 60_000));
+  if (mins < 60) return `next in ${mins}m`;
+  const hours = Math.floor(mins / 60);
+  return hours < 48 ? `next in ${hours}h` : `next in ${Math.floor(hours / 24)}d`;
+}
+
+/**
+ * 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) {
+  const { trigger, armed, nextSlotMs, lastOutcome, waitingRunNo, now, retryInMs = null, gaveUp = null } = f;
+  /** @param {string} text @param {boolean} [red] */
+  const say = (text, red = false) => ({ text, red });
+  if (waitingRunNo !== null) return say(`Run ${waitingRunNo} is waiting for your Accept. The next scheduled run does not wait for it.`);
+  if (gaveUp && typeof gaveUp === 'object') return say(gaveUpNextWords(gaveUp.why), true);
+  const last = lastOutcome && typeof lastOutcome === 'object' ? lastOutcome : null;
+  const sameMonth = last !== null && sameMonthAs(last.at, now);
+  if (last !== null && last.kind === 'monthly-exhausted' && sameMonth && typeof last.leftUsd === 'number' && typeof last.needUsd === 'number') {
+    const left = last.atLeast === true ? `at most ${panelMoney2(last.leftUsd)} left` : `${panelMoney2(last.leftUsd)} left`;
+    return say(`Paused: not enough money left this month (${left}, a run needs up to ${panelMoney2(last.needUsd)}). Raise the monthly limit in Settings, or it starts again on the 1st.`, true);
+  }
+  const lead = last !== null && last.kind === 'refused' && typeof last.why === 'string' && last.why !== '' ? `The last try did not start: ${last.why} ${retryWords(retryInMs)}` : '';
+  const red = lead !== '';
+  if (!armed) return say(`${lead}Not armed yet: the panel arms it on its next check.`, red);
+  if (trigger.kind === 'file-updated') return say(`${lead}Watching for it. A run starts when its contents change.`, red);
+  if (trigger.kind === 'new-file') return say(`${lead}Watching for it. A run starts for each new file.`, red);
+  if (nextSlotMs === null) return say(`${lead}Not armed yet: the panel arms it on its next check.`, red);
+  return say(`${lead}Next run ${slotWords(nextSlotMs)}.`, red);
+}
+
+/** 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, nowMs) {
+  if (typeof atMs !== 'number' || !Number.isFinite(atMs)) return false;
+  const a = new Date(atMs); const n = new Date(nowMs);
+  return a.getFullYear() === n.getFullYear() && a.getMonth() === n.getMonth();
+}
+
+/** 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) {
+  const w = typeof why === 'string' ? why.trim().replace(/\.$/, '') : '';
+  return `Stopped trying after 60 minutes: ${w}. Fix it, then Cancel / modify schedule to start again.`;
+}
+
+/** The give-up date on the Needs-you card, local `MM/DD HH:MM`. @param {number} ms */
+export function gaveUpDateWords(ms) {
+  const d = new Date(ms);
+  return `${two(d.getMonth() + 1)}/${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+
+/** 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) {
+  if (typeof ms !== 'number' || !(ms > 0)) return '';
+  const m = Math.ceil(ms / 60_000);
+  return `Trying again in ${m} minute${m === 1 ? '' : 's'}. `;
+}
+
+/** The fixed catch-up sentence from a run's `trigger.json`. @param {any} rec */
+export function catchUpWords(rec) {
+  return rec && typeof rec === 'object' && rec.catchUp === true ? '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, tries, max) {
+  return tries < max ? `${why} It will be tried again.` : `${why} It was tried ${max} times and is given up on.`;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------------
+// RULED 2026-10-15 (aligned with fwdloop M9 am7): the schedule on the Run, Job and Audit tabs. ONE owner of these sentences.
+
+/** "10/15 13:40" — local time. @param {number} ms */
+export const dateTimeWords = (ms) => gaveUpDateWords(ms);
+
+/** @param {string} s */
+export const lowerFirst = (s) => (s === '' ? s : s[0].toLowerCase() + s.slice(1));
+
+/** "Thu 10/16 08:15" — local time, fixed English day names. @param {number} ms */
+export function nextSlotShort(ms) {
+  const d = new Date(ms);
+  return `${DAY_SHORT[d.getDay()]} ${two(d.getMonth() + 1)}/${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+
+/** @param {any} rec a run's `trigger.json` @returns {boolean} */
+function isNewFile(rec) {
+  if (rec.triggerKind) return rec.triggerKind === 'new-file';
+  return typeof rec.trigger === 'string' && rec.trigger.startsWith('When a new file arrives');
+}
+
+/**
+ * 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, atMs) {
+  const when = atMs === null ? '' : ` · ${dateTimeWords(atMs)}`;
+  if (!rec || typeof rec !== 'object') return `${SCHEDULE_WORDS.byHand}${when}`;
+  const trig = typeof rec.trigger === 'string' ? rec.trigger : '';
+  let how;
+  if (rec.kind === 'file') {
+    const name = basename(String(rec.file ?? ''));
+    how = isNewFile(rec) ? `By a new file: ${name}` : `By a file update: ${name}`;
+  } else {
+    how = `By the schedule: ${lowerFirst(trig)}`;
+    if (rec.catchUp === true) {
+      const min = typeof rec.lateMs === 'number' && rec.lateMs > 0 ? Math.round(rec.lateMs / 60_000) : null;
+      how += min === null ? ' · catch-up' : ` · catch-up, ${min} min late`;
+    }
+  }
+  return `${how}${when}`;
+}
+
+/**
+ * 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, originNo) {
+  const from = originNo === null ? '' : ` · from run-${originNo}`;
+  if (rec.kind === 'file') return `started by the schedule · ${isNewFile(rec) ? 'new file' : 'file update'} ${basename(String(rec.file ?? ''))}${from}`;
+  const slot = typeof rec.slot === 'number' ? ` · slot ${two(new Date(rec.slot).getHours())}:${two(new Date(rec.slot).getMinutes())}` : '';
+  return `started by the schedule · ${lowerFirst(String(rec.trigger ?? ''))}${slot}${from}${rec.catchUp === true ? ' · catch-up' : ''}`;
+}
+
+/** a refusal's own words without its trailing "Nothing started." @param {unknown} why */
+function reasonOf(why) {
+  return String(why ?? '').replace(/\s*Nothing (started|spent)\.\s*$/, '').trim().replace(/\.$/, '');
+}
+
+/**
+ * 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, short = false) {
+  if (row.kind === 'busy') return short ? 'busy: a run of this job was still working' : 'busy: a run of this job was still working. Nothing started.';
+  if (row.kind === 'monthly-exhausted') {
+    const left = typeof row.leftUsd === 'number' ? `${row.atLeast === true ? 'at most ' : ''}${panelMoney2(row.leftUsd)}` : 'little';
+    const need = typeof row.needUsd === 'number' ? panelMoney2(row.needUsd) : 'more';
+    return short ? `month used up: ${left} left, needs ${need}` : `month used up: ${left} left, needs ${need}. Nothing spent.`;
+  }
+  const r = lowerFirst(reasonOf(row.why));
+  return short ? `refused: ${r}` : `refused: ${r}. Nothing started.`;
+}
+
+/**
+ * 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) {
+  const w = f.trigger ? scheduledWords(f.trigger, f.home) : null;
+  if (w === null) return 'none';
+  const parts = [lowerFirst(w)];
+  if (f.originNo !== null) parts.push(`from run-${f.originNo}`);
+  if (f.model) parts.push(f.model);
+  if (f.destination) parts.push(tilde(f.destination, f.home));
+  return parts.join(' · ');
+}
+
+/** 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) {
+  const m = Math.max(1, Math.ceil(ms / 60_000));
+  return `next: tries again in ${m} min`;
+}
+
+/**
+ * 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) {
+  return { sign: f.running ? '▶' : f.red ? '✗' : '·' };
+}
+
+/** 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) {
+  if (rec.kind === 'file') return `started by the schedule · ${isNewFile(rec) ? 'new file' : 'file update'} ${basename(String(rec.file ?? ''))}`;
+  let late = '';
+  if (rec.catchUp === true) {
+    const min = typeof rec.lateMs === 'number' && rec.lateMs > 0 ? Math.round(rec.lateMs / 60_000) : null;
+    late = min === null ? ' · catch-up' : ` · catch-up, ${min} min late`;
+  }
+  return `started by the schedule · ${lowerFirst(String(rec.trigger ?? ''))}${late}`;
+}
+
+/** Audit schedule section, folded tail: `1 try started nothing` / `N tries started nothing`; '' for none. @param {number} n */
+export function triesTailWords(n) {
+  return n > 0 ? `${n} ${n === 1 ? 'try' : 'tries'} started nothing` : '';
+}

package/src/trigger.js

@@ -0,0 +1,48 @@
+// T Part 3 (docs/product/PANEL-BUILD.md, "T: triggers build spec", C.3): the `trigger` field of a signed spec,
+// as typed data. Pure. Never cron text, never a model's word: the agent does not write this field (assembleSpec
+// refuses a draft carrying it) and the interview never does either. By hand = the key is ABSENT (never null),
+// so a by-hand spec hashes exactly as it did before triggers existed.
+//   {kind:'daily'|'weekdays', hour, minute}
+//   {kind:'weekly', day:'mon'..'sun', hour, minute}
+//   {kind:'new-file', folder}        absolute path
+//   {kind:'file-updated', path}      absolute path
+// Rewritten from fwdloop src/trigger-line.js (its prose-line grammar is replaced: the signed thing is the JSON spec).
+import { isAbsolute } from 'node:path';
+import { validateSchedule } from './triggerclock.js';
+
+/** @typedef {import('./triggerclock.js').Schedule | {kind:'new-file', folder:string} | {kind:'file-updated', path:string}} Trigger */
+
+export const TRIGGER_KINDS = Object.freeze(['daily', 'weekdays', 'weekly', 'new-file', 'file-updated']);
+export const CLOCK_KINDS = Object.freeze(['daily', 'weekdays', 'weekly']);
+export const FILE_KINDS = Object.freeze(['new-file', 'file-updated']);
+
+/** @param {unknown} t @returns {t is {kind:'daily'|'weekdays'|'weekly', hour:number, minute:number}} */
+export const isClockTrigger = (t) => !!t && typeof t === 'object' && CLOCK_KINDS.includes(/** @type {any} */ (t).kind);
+/** @param {unknown} t @returns {t is {kind:'new-file', folder:string} | {kind:'file-updated', path:string}} */
+export const isFileTrigger = (t) => !!t && typeof t === 'object' && FILE_KINDS.includes(/** @type {any} */ (t).kind);
+
+/**
+ * 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) {
+  /** @param {string} say @param {string} [path] @param {'invalid-value'|'unknown-field'} [code] */
+  const no = (say, path = 'trigger', code = 'invalid-value') => ({ ok: /** @type {const} */ (false), say, code, path });
+  if (!t || typeof t !== 'object' || Array.isArray(t)) return no('a trigger is an object like {kind, hour, minute}, not text');
+  const o = /** @type {Record<string, unknown>} */ (t);
+  if (!TRIGGER_KINDS.includes(/** @type {string} */ (o.kind))) return no(`trigger kind "${o.kind}" is not one of ${TRIGGER_KINDS.join(', ')}`, 'trigger.kind');
+  if (CLOCK_KINDS.includes(/** @type {string} */ (o.kind))) {
+    const allowed = o.kind === 'weekly' ? ['kind', 'day', 'hour', 'minute'] : ['kind', 'hour', 'minute'];
+    const extra = Object.keys(o).find((k) => !allowed.includes(k));
+    if (extra !== undefined) return no(`trigger field "${extra}" is not allowed on a ${o.kind} trigger`, `trigger.${extra}`, 'unknown-field');
+    try { return { ok: true, trigger: validateSchedule(o) }; } catch (e) { return no(/** @type {Error} */ (e).message.replace(/^schedule/, 'trigger')); }
+  }
+  const where = o.kind === 'new-file' ? 'folder' : 'path';
+  const extra = Object.keys(o).find((k) => k !== 'kind' && k !== where);
+  if (extra !== undefined) return no(`trigger field "${extra}" is not allowed on a ${o.kind} trigger (it takes a ${where})`, `trigger.${extra}`, 'unknown-field');
+  const p = o[where];
+  // eslint-disable-next-line no-control-regex
+  if (typeof p !== 'string' || p === '' || !isAbsolute(p) || /[\x00-\x1f\x7f]/.test(p)) return no(`the ${where} must be a full path on one line, like /home/you/inbox`, `trigger.${where}`);
+  return { ok: true, trigger: /** @type {Trigger} */ (o.kind === 'new-file' ? { kind: 'new-file', folder: p } : { kind: 'file-updated', path: p }) };
+}