bareloop 0.41.0 → 0.43.0

package/types/panel/schedules.d.ts

@@ -0,0 +1,412 @@
+/**
+ * When a process started, in epoch ms, from `/proc/<pid>/stat` field 22 (clock ticks since boot) and `/proc/stat` btime
+ * (whole seconds, so good to about a second). `null` where /proc cannot be read: the caller then trusts `isLiveRunner` alone.
+ * @param {number} pid
+ * @param {(path: string) => string} [read]
+ * @returns {number|null}
+ */
+export function procStartMs(pid: number, read?: (path: string) => string): number | null;
+/**
+ * Is this listed run's runner alive? `runIsAlive` (the pid is alive AND a bareloop runner) plus the PID REUSE GUARD: a
+ * pid whose process started MORE than 5 s after the row was written is a recycled pid, not that run. A resumed run's row
+ * keeps its first leg's time while its pid is the latest leg's, so the guard is skipped for it (the cmdline check stands).
+ * @param {any} row @param {number} nowMs
+ */
+export function runnerAlive(row: any, nowMs: number): boolean;
+/**
+ * @typedef {{runid: string, outcome: string|null, spec: any, records: any[]}} JobRun
+ * @typedef {{job: string, trigger: import('../trigger.js').Trigger, spec: any, specHash: string, workflowKey: string,
+ *   originRunid: string, inputsText: string, destination?: string, signedBy: string, signedAt: string}} Schedule
+ */
+/**
+ * @param {{
+ *   home?: string,
+ *   sessionsRoot?: string,
+ *   now?: () => number,
+ *   jobRuns: (job: string) => JobRun[],
+ *   startFrom: (runid: string) => any,
+ *   jobOfRun: (runid: string) => string|null,
+ *   rowsFor: () => readonly import('../providerrows.js').KeyRow[],
+ *   runRows?: () => any[],
+ *   installRetrySteps?: readonly number[], installGiveUpMs?: number,
+ *   userHome?: string,
+ * }} deps `userHome` = the folder shown as `~` in words (default the OS home). `installRetrySteps` (ms) and `installGiveUpMs` = the install-needed back-off (tests inject them). `runRows` = a test seam for the one run-list read the busy check does. `jobRuns(job)` = the job's listed runs, newest first, each with its signed spec when on disk and its terminal
+ *   outcome off the spine; `startFrom(runid)` = the panel's `getStartFrom`; `jobOfRun` = the listed run's job name.
+ */
+export function createScheduleDoor(deps: {
+    home?: string;
+    sessionsRoot?: string;
+    now?: () => number;
+    jobRuns: (job: string) => JobRun[];
+    startFrom: (runid: string) => any;
+    jobOfRun: (runid: string) => string | null;
+    rowsFor: () => readonly import("../providerrows.js").KeyRow[];
+    runRows?: () => any[];
+    installRetrySteps?: readonly number[];
+    installGiveUpMs?: number;
+    userHome?: string;
+}): {
+    /** The starter is built after the author routes (which need this door), so it is attached here. @param {ReturnType<typeof import('./schedulestart.js').createStarter>} s */
+    attachStarter(s: ReturnType<typeof import("./schedulestart.js").createStarter>): void;
+    busy: (job: string) => boolean;
+    paused: (job: string) => boolean;
+    /**
+     * RULED 2026-10-15 (v1.104): the fires that started NOTHING (busy, month used up, refused) of ALL signings of the job's schedule
+     * (the job's ledger is the job's, so every signing's rows are in it; cancelled-and-set-again rows stay). Newest first. Lines are
+     * `MM/DD HH:MM  <words>`. The caller shows the first 7 and counts them all.
+     * @param {string} job
+     * @returns {{at: number, line: string}[]}
+     */
+    skippedFor(job: string): {
+        at: number;
+        line: string;
+    }[];
+    /**
+     * One fire, in this order (T15): busy, then monthly, then wouldAccept, then the starter (which calls `beforeSpawn`, the
+     * ONE consuming row, only after every "no" is behind it). Each outcome is ONE row in ledger.jsonl, told once per
+     * `key|outcome|why` (read back from disk, so a restart does not repeat it). RULED 2026-10-14: a busy, monthly or refused
+     * fire consumes NOTHING, so the next tick tries again; a spawn error after `beforeSpawn` writes a `released` row (bounded).
+     * @param {string} job
+     * @param {{kind: 'clock', slot: number, catchUp: boolean, missed: number} | {kind: 'file', path: string, sha: string, size?: number}} cause
+     * @param {{beforeSpawn?: () => void, busy?: boolean}} [hooks] `busy` = the scheduler's one read of the run list this tick
+     * @returns {Promise<{outcome: 'busy'|'monthly-exhausted'|'refused'|'started', why?: string, told: boolean, sessionId?: string}>}
+     */
+    fire(job: string, cause: {
+        kind: "clock";
+        slot: number;
+        catchUp: boolean;
+        missed: number;
+    } | {
+        kind: "file";
+        path: string;
+        sha: string;
+        size?: number;
+    }, hooks?: {
+        beforeSpawn?: () => void;
+        busy?: boolean;
+    }): Promise<{
+        outcome: "busy" | "monthly-exhausted" | "refused" | "started";
+        why?: string;
+        told: boolean;
+        sessionId?: string;
+    }>;
+    greenFor: (job: string) => {
+        ok: true;
+        run: JobRun;
+        key: string;
+    } | {
+        ok: false;
+        say: string;
+    };
+    armFor: (job: string, schedule: Schedule, o?: {
+        baseline?: boolean;
+    }) => {
+        armed: boolean;
+        already: boolean;
+    };
+    readSchedule: (job: string) => Schedule | null;
+    ledgerOf: (job: string) => string;
+    /**
+     * A failure the scheduler met on a job (a folder that went away, a file refused), written as ONE `refused` row per
+     * `tag`, read back from disk so a restart does not repeat it (T13). Returns whether it wrote.
+     * @param {string} job @param {string} sig @param {string} tag @param {string} why
+     */
+    tellOnce(job: string, sig: string, tag: string, why: string): boolean;
+    /** Click 1. All $0 checks; signs and writes nothing; returns `{words, hash, monthlyNote}`. @param {any} body */
+    prepare(body: any): {
+        status: number;
+        body: {
+            ok: boolean;
+        };
+    } | {
+        status: number;
+        body: {
+            ok: boolean;
+            job: any;
+            words: string | null;
+            hash: string;
+            monthlyNote: string | null;
+            cancel: boolean;
+        };
+    };
+    /** Click 2, carrying the hash it was shown. $0: no drafter, no run. @param {any} body */
+    set(body: any): {
+        status: number;
+        body: {
+            ok: boolean;
+        };
+    } | {
+        status: number;
+        body: {
+            ok: boolean;
+            refused: string;
+            say: "What you were shown is not what is on the card now. Nothing was signed. Look again, then sign.";
+            job?: undefined;
+            cancelled?: undefined;
+            words?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            ok: boolean;
+            job: any;
+            cancelled: boolean;
+            words: "Cancel schedule";
+            refused?: undefined;
+            say?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            say?: string | undefined;
+            ok: boolean;
+            job: any;
+            words: string | null;
+            hash: string;
+            armed: boolean;
+            refused?: undefined;
+            cancelled?: undefined;
+        };
+    };
+    /** Cancel a job's schedule, never refused. @param {string} job @returns {boolean} there was one */
+    cancel(job: string): boolean;
+    /** Every job with a schedule.json: `{job, dir, schedule}`. One readdir; nothing else read when there is none. */
+    scan(): {
+        job: string;
+        dir: string;
+        schedule: Schedule;
+    }[];
+    /**
+     * What a card shows of a job's schedule, as DATA (no words): the trigger, whether it is armed under the CURRENT
+     * signing, the next slot (clock kinds), the last outcome (rows under the current signing only, never a wall-clock
+     * compare, T19), whether the job has a green run, and the refusal sentence when it has none.
+     * @param {string} job
+     */
+    read(job: string): {
+        schedule: null;
+        trigger: null;
+        armed: boolean;
+        armedAt: null;
+        nextSlotMs: null;
+        lastOutcome: null;
+        retryInMs: null;
+        gaveUp: null;
+        job: string;
+        hasGreen: boolean;
+        refusal: string | null;
+    } | {
+        schedule: Schedule;
+        trigger: import("../trigger.js").Trigger;
+        armed: boolean;
+        armedAt: number | null | undefined;
+        nextSlotMs: number | null;
+        lastOutcome: import("../triggerledger.js").LedgerRow | null;
+        retryInMs: number | null;
+        gaveUp: import("../triggerledger.js").LedgerRow | null;
+        job: string;
+        hasGreen: boolean;
+        refusal: string | null;
+    } | null;
+    stateOf: (job: string) => {
+        schedule: null;
+        trigger: null;
+        armed: boolean;
+        armedAt: null;
+        nextSlotMs: null;
+        lastOutcome: null;
+        retryInMs: null;
+        gaveUp: null;
+    } | {
+        schedule: Schedule;
+        trigger: import("../trigger.js").Trigger;
+        armed: boolean;
+        armedAt: number | null | undefined;
+        nextSlotMs: number | null;
+        lastOutcome: import("../triggerledger.js").LedgerRow | null;
+        retryInMs: number | null;
+        gaveUp: import("../triggerledger.js").LedgerRow | null;
+    };
+    userHome: string;
+    /**
+     * What the Run tab shows of a job's schedule (A.12: one read of the schedule files and the ledger; the green gate is
+     * memoised per run-list state, so a poll never re-parses every run). The SERVER decides: `scheduled` shows Cancel /
+     * modify, else `canSchedule` shows Schedule run, else no button. `fromRunid` = the green run the card opens from. `waitingRunNo` = the job's newest run when it waits
+     * for the person's Accept (the next scheduled run does NOT wait for it, T7).
+     * @param {string} job @param {{waitingRunNo?: number|null}} [o]
+     */
+    view(job: string, o?: {
+        waitingRunNo?: number | null;
+    }): {
+        fromRunid?: string | undefined;
+        scheduled: boolean;
+        canSchedule: boolean;
+        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.";
+        }>;
+        text?: undefined;
+        next?: undefined;
+        nextRed?: undefined;
+        lastRow?: undefined;
+        problem?: undefined;
+        nextWords?: undefined;
+        accept?: undefined;
+    } | {
+        scheduled: boolean;
+        canSchedule: boolean;
+        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.";
+        }>;
+        fromRunid: string;
+        text: string | null;
+        next: string;
+        nextRed: boolean;
+        lastRow: import("../triggerledger.js").LedgerRow | null;
+        problem: boolean;
+        nextWords: string;
+        accept: boolean;
+    } | null;
+    /**
+     * The schedule card's data for `start-from?mode=schedule`: the current schedule in the When field's own terms, the
+     * words, the refusal that disables the field (a job with no good run and no schedule), and the edit note.
+     * Cancel is never refused, so a scheduled job is never disabled here.
+     * @param {string} job
+     */
+    cardFor(job: string): {
+        scheduled: boolean;
+        trigger: import("../trigger.js").Trigger | null;
+        now: string | null;
+        refusal: string | null;
+        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.";
+        }>;
+    };
+    /**
+     * RULED 2026-10-15: the jobs whose schedule gave up, for the runs list's Needs you section (the SERVER decides; the page works out nothing):
+     * `[{job, pill: 'Check', words, at: 'MM/DD HH:MM', runId}]`, newest give-up first. `runId` = the job's HEAD run by time. Never ages out.
+     * @param {Map<string, string|null>|Record<string, string|null>} heads
+     */
+    listGaveUp(heads: Map<string, string | null> | Record<string, string | null>): {
+        job: string;
+        pill: "Check";
+        words: string;
+        at: string;
+        runId: string | null;
+    }[];
+    /**
+     * The Scheduled section of the runs list: `[{job, at, in, words, runId}]`, soonest first; a file trigger (no clock
+     * time) after those that have one, by name. `heads` = job -> its HEAD run id by time (summarizeJobs), so the click
+     * opens the job's newest run, never "the first in server order". A job that cannot be read is absent.
+     * @param {Map<string, string|null>|Record<string, string|null>} heads
+     */
+    listScheduled(heads: Map<string, string | null> | Record<string, string | null>): {
+        job: string;
+        at: string | null;
+        in: string | null;
+        words: string | null;
+        runId: string | null;
+    }[];
+};
+/** a spawn error after the consuming row releases it at most this many times; then it stays consumed (bounded rows) */
+export const MAX_RELEASES: 3;
+/** a live pid whose process started more than this after its run row was written is a RECYCLED pid, not that run */
+export const PID_REUSE_SLACK_MS: 5000;
+/** RULED 2026-10-15: waits (ms) between consecutive `install-needed` refusals of a job: Fibonacci 1, 2, 3, 5, 8, 13, 21 minutes. A test injects its own via `deps.installRetrySteps`. */
+export const INSTALL_RETRY_STEPS_MS: readonly number[];
+/** RULED 2026-10-15: the total wait a slot or file gets. A wait that would pass it is not taken: the schedule gives up and pauses (the job waits in Needs you). */
+export const INSTALL_GIVE_UP_MS: number;
+export type JobRun = {
+    runid: string;
+    outcome: string | null;
+    spec: any;
+    records: any[];
+};
+export type Schedule = {
+    job: string;
+    trigger: import("../trigger.js").Trigger;
+    spec: any;
+    specHash: string;
+    workflowKey: string;
+    originRunid: string;
+    inputsText: string;
+    destination?: string;
+    signedBy: string;
+    signedAt: string;
+};

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;