toolroll 0.9.51 → 0.9.53

package/dist/flow-schedule.js

@@ -0,0 +1,321 @@
+/**
+ * Schedules (v115: flow-owned; routines became scheduled flows).
+ *
+ * A schedule trigger fires on one of four readable cadences. Its two failure modes are subtle enough to deserve
+ * names: advancing one interval after downtime leaves the next firing in the past — a catch-up burst; advancing to
+ * `now + interval` drifts the cadence forever. The rule is ALIGNED advancement: the next occurrence strictly after
+ * now, anchored to the occurrence that just fired (for `every`) or to the clock itself (for calendar schedules).
+ * Missed slots while nothing was running fire ONCE — the overdue occurrence — and are never backfilled.
+ */
+import { createHash } from "node:crypto";
+import { fileTaskProposal } from "./proposal.js";
+import { reportsCost } from "./provider.js";
+import { legOf, routeDigestOf, routeFromJson, routeProblems } from "./phase-routing.js";
+import { canonicalAcceptance, digestOf, parseAcceptanceCriteria, profileDigestOf, profileFromJson } from "./scope.js";
+import { hasDisguisedText, hasForbiddenControls } from "./decision.js";
+import { BUILT_IN, parseCapabilityKey } from "./store.js";
+export const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+export function validTimezone(value) {
+    if (value.trim() !== value)
+        return false;
+    if (!/^[A-Za-z0-9_+/-]{1,80}$/.test(value))
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: value }).format(0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Bounds a person would pick on purpose: 5 minutes to 7 days. */
+export const MIN_EVERY_MINUTES = 5;
+export const MAX_EVERY_MINUTES = 7 * 24 * 60;
+/**
+ * Existing daily schedules remain UTC. Calendar schedules may name an IANA
+ * timezone, whose wall-clock time stays fixed across daylight saving changes.
+ * No cron expressions in v1 — a schedule the operator cannot read at a
+ * glance is a schedule they cannot honestly approve.
+ */
+export function parseSchedule(text) {
+    if (text.trim() !== text)
+        return null;
+    const every = /^every:([0-9]{1,5})$/.exec(text);
+    if (every !== null) {
+        const minutes = Number(every[1]);
+        if (minutes < MIN_EVERY_MINUTES || minutes > MAX_EVERY_MINUTES)
+            return null;
+        return { kind: "every", minutes };
+    }
+    const calendar = /^(daily|weekdays|weekly:[0-6]):([01][0-9]|2[0-3]):([0-5][0-9])(?:@([A-Za-z0-9_+/-]{1,80}))?$/.exec(text);
+    if (calendar !== null) {
+        const timezone = calendar[4];
+        if (timezone !== undefined && !validTimezone(timezone))
+            return null;
+        const time = { hhmm: `${calendar[2]}:${calendar[3]}`, ...(timezone === undefined ? {} : { timezone }) };
+        return calendar[1] === "daily" ? { kind: "daily", ...time } : calendar[1] === "weekdays" ? { kind: "weekdays", ...time } : { kind: "weekly", day: Number(calendar[1].slice(-1)), ...time };
+    }
+    return null;
+}
+export function scheduleText(schedule) {
+    return schedule.kind === "every" ? `every:${schedule.minutes}` : `${schedule.kind === "weekly" ? `weekly:${schedule.day}` : schedule.kind}:${schedule.hhmm}${schedule.timezone === undefined ? "" : `@${schedule.timezone}`}`;
+}
+/** The schedule, in words an operator agrees to. */
+export function describeSchedule(schedule) {
+    if (schedule.kind !== "every")
+        return `${schedule.kind === "daily" ? "daily" : schedule.kind === "weekdays" ? "weekdays" : `every ${WEEKDAYS[schedule.day]}`} at ${schedule.hhmm} ${schedule.timezone ?? "UTC"}`;
+    const { minutes } = schedule;
+    if (minutes % (24 * 60) === 0)
+        return `every ${minutes / (24 * 60)} day(s)`;
+    if (minutes % 60 === 0)
+        return `every ${minutes / 60} hour(s)`;
+    return `every ${minutes} minutes`;
+}
+/**
+ * The first occurrence after approval: the schedule starts counting from the
+ * yes, because "approved at 14:07, every 60 minutes" firing instantly would
+ * spend before the approver's hand left the keyboard.
+ */
+export function firstFireAt(schedule, now) {
+    if (schedule.kind === "every") {
+        return new Date(now.getTime() + schedule.minutes * 60_000).toISOString();
+    }
+    return nextCalendar(schedule, now);
+}
+/**
+ * Aligned advancement: the smallest cadence occurrence STRICTLY after now.
+ * `anchor` is the occurrence that just fired (or was just skipped) — the
+ * cadence grid grows from it, so a pass that ran late does not tilt every
+ * later firing by its lateness.
+ */
+export function nextFireAt(schedule, anchorIso, now) {
+    if (schedule.kind !== "every")
+        return nextCalendar(schedule, now);
+    const interval = schedule.minutes * 60_000;
+    const anchor = new Date(anchorIso).getTime();
+    const elapsed = now.getTime() - anchor;
+    // Strictly after now: an occurrence landing exactly on now already fired.
+    const steps = Math.max(1, Math.floor(elapsed / interval) + 1);
+    return new Date(anchor + steps * interval).toISOString();
+}
+function nextCalendar(schedule, now) {
+    const format = new Intl.DateTimeFormat("en-US", { timeZone: schedule.timezone ?? "UTC", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+    // Represent wall-clock components as a UTC number solely for arithmetic.
+    const wall = (instant) => {
+        const parts = Object.fromEntries(format.formatToParts(instant).map(part => [part.type, part.value]));
+        return Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute));
+    };
+    const localNow = new Date(wall(now.getTime()));
+    const [hour, minute] = schedule.hhmm.split(":").map(Number);
+    const today = Date.UTC(localNow.getUTCFullYear(), localNow.getUTCMonth(), localNow.getUTCDate(), hour, minute);
+    for (let days = 0; days <= 15; days++) {
+        const target = today + days * 86_400_000;
+        if (schedule.kind === "weekly" && new Date(target).getUTCDay() !== schedule.day)
+            continue;
+        if (schedule.kind === "weekdays" && (new Date(target).getUTCDay() === 0 || new Date(target).getUTCDay() === 6))
+            continue;
+        // Nearby dates expose both offsets around a daylight-saving transition.
+        // A missing clock time skips its slot. An ambiguous time uses the first
+        // occurrence only, even if the scheduler advances during the repeated hour.
+        const offsets = [...new Set([-36, 0, 36].map(hours => { const sample = target + hours * 3_600_000; return wall(sample) - sample; }))];
+        const matches = offsets.map(offset => target - offset).filter(instant => wall(instant) === target);
+        if (matches.length > 0) {
+            const first = Math.min(...matches);
+            if (first > now.getTime())
+                return new Date(first).toISOString();
+        }
+    }
+    throw new Error("No calendar occurrence within the next fifteen days");
+}
+// ------------------------------------------------------------------ standing orders
+/** The rolling window a standing order's cost ceiling counts over: seven days, and every surface says so. */
+export const BUDGET_WINDOW_MS = 7 * 24 * 60 * 60_000;
+/** A firing's task id: the order's stem stamped with its slot (`nightly-deps-20261008-0700`). */
+export function instanceId(stem, slotIso) {
+    return `${stem}-${slotIso.replace(/[-:]/g, "").slice(0, 13).replace("T", "-")}`;
+}
+/**
+ * The exact standing order an approver agreed to, as 128 bits — byte for byte what a routine's digest was, so a
+ * routine's approval moved onto a scheduled flow (v115) still verifies: the project, the terms, the schedule, the
+ * ceiling, and the agents the approval froze. Editing any of them (or moving the flow) strands the approval.
+ */
+export function standingDigestOf(repo, schedule, order, acceptance, profile, route) {
+    return createHash("sha256").update(JSON.stringify({
+        repo,
+        goal: order.goal.trim(),
+        outOfScope: order.outOfScope?.trim() ?? null,
+        touches: [...order.touches].sort(),
+        ...(acceptance.length === 0 ? {} : { acceptance: canonicalAcceptance(acceptance) }),
+        requirements: [...order.requirements].sort(),
+        schedule,
+        singleFlight: order.singleFlight,
+        costCeilingUsd: order.costCeilingUsd,
+        ...(order.budgetPerRunMicrousd == null ? {} : { budgetPerRun: order.budgetPerRunMicrousd }),
+        profileDigest: profileDigestOf(profile),
+        route: routeDigestOf(route),
+    }), "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * Whether a standing order's carried approval still stands, read whole before anything is written: the frozen agents
+ * read back, re-hash with the order's terms, this schedule and project to the digest the approver signed, state no
+ * problem, and build and repair on the approved profile's own agents. `problem` is null when there is no approval.
+ */
+export function standingApproval(order, repo, schedule) {
+    const read = parseAcceptanceCriteria(order.acceptance);
+    const acceptance = read.problems.length === 0 && read.criteria.length > 0 ? read.criteria : null;
+    if (order.approval === null)
+        return { live: false, problem: null, acceptance };
+    const refused = (problem) => ({ live: false, problem, acceptance });
+    if (acceptance === null)
+        return refused("its success checks can't be read");
+    const profile = profileFromJson(order.approval.profileJson), route = routeFromJson(order.approval.routeJson);
+    if (profile === null || route === null)
+        return refused("the agents its approval froze can't be read back");
+    if (standingDigestOf(repo, schedule, order, acceptance, profile, route) !== order.approval.digest)
+        return refused("it changed after it was approved");
+    const problems = routeProblems(route);
+    if (problems.length > 0)
+        return refused(problems.join("; "));
+    const build = legOf(route, "build"), repair = legOf(route, "repair");
+    const repairModel = profile.repairModel === "inherit" ? profile.model : profile.repairModel;
+    if (build.provider !== profile.provider || build.model !== profile.model || repair.provider !== profile.provider || repair.model !== repairModel) {
+        return refused("its approved agents disagree with its approved route");
+    }
+    return { live: true, by: order.approval.by, profile, route, acceptance };
+}
+/** A firing that must not stand: thrown inside the transaction so nothing it wrote survives. */
+export class StandingOrderRefused extends Error {
+}
+/**
+ * File one firing of a standing order (v115, what firing a routine did), inside the caller's transaction. It skips,
+ * saying why, while the last task is unfinished or the rolling 7-day ceiling is reached (an unmeasured paid run fails
+ * closed). Otherwise it files the order's terms unchanged: approved by the carried approval when that still verifies
+ * — on exactly the agents it froze, sealed like any automatic approval under the project's rules — or else as an
+ * ordinary proposal that waits for the project's approval rules like any other.
+ */
+export function fileStandingOrder(store, input, now) {
+    const { order, repo } = input;
+    const blocker = store.standingOrderBlocker(input.trigger, order.routine, now);
+    if (blocker !== null)
+        return { made: "skipped", note: `Skipped: the last one (${blocker.taskId}, ${blocker.state}) hasn't finished.` };
+    const approval = standingApproval(order, repo, input.schedule);
+    if (approval.acceptance === null)
+        return { made: "skipped", note: "Skipped: its success checks can't be read. Set the flow up again." };
+    if (order.costCeilingUsd !== null) {
+        const ceiling = `$${order.costCeilingUsd.toFixed(2)}`;
+        if (approval.live && !reportsCost(legOf(approval.route, "build").provider)) {
+            return { made: "skipped", note: `Skipped: ${legOf(approval.route, "build").provider} doesn't report what it spends, so the ${ceiling} weekly limit can't be kept.` };
+        }
+        const spend = store.standingOrderSpend(input.trigger, order.routine, new Date(now.getTime() - BUDGET_WINDOW_MS).toISOString());
+        if (spend.unmeasuredRuns > 0)
+            return { made: "skipped", note: `Skipped: ${spend.unmeasuredRuns} run(s) in the last 7 days recorded no cost, so the ${ceiling} weekly limit can't be kept.` };
+        if (spend.costUsd >= order.costCeilingUsd)
+            return { made: "skipped", note: `Skipped: $${spend.costUsd.toFixed(2)} of the ${ceiling} weekly limit is spent.` };
+    }
+    let taskId = instanceId(order.stem, input.slot);
+    for (let n = 2; store.getTask(taskId) !== null; n++)
+        taskId = `${instanceId(order.stem, input.slot)}-${n}`;
+    const filedBy = order.filedBy === null ? { name: null, kind: "automation" } : { name: order.filedBy, kind: "person" };
+    if (!approval.live) {
+        const filed = fileTaskProposal(store, {
+            id: taskId, title: input.title, repo, goal: order.goal, outOfScope: order.outOfScope, touches: [...order.touches], acceptance: approval.acceptance,
+            budgetMicrousd: order.budgetPerRunMicrousd, filedVia: `flow:${input.flowId}`, filedBy, planning: "skip", admittedRepos: [repo],
+        }, now);
+        if (!filed.ok)
+            return { made: "skipped", note: `Couldn't file it: ${filed.message}.` };
+        const ref = store.lookupRef(filed.id);
+        if (ref !== null && order.requirements.length > 0)
+            store.setRequirements(ref.id, order.requirements);
+        return { made: "filed", taskId: filed.id, approved: false, note: approval.problem === null ? null : `Its earlier approval no longer applies (${approval.problem}), so this one waits for approval.` };
+    }
+    // The approved road: the frozen agents are the pin, the terms are the scope byte for byte, and the seal must read
+    // back as the frozen route — or nothing of this firing stands.
+    store.createTask({ id: taskId, title: input.title, filedBy }, now);
+    const ref = store.refFor(BUILT_IN, taskId, "ours");
+    store.placeTask(ref.id, repo);
+    store.pinTaskAgent(ref.id, approval.profile.provider, approval.profile.model);
+    if (order.requirements.length > 0)
+        store.setRequirements(ref.id, order.requirements);
+    const draft = { goal: order.goal, outOfScope: order.outOfScope, touches: [...order.touches], acceptance: approval.acceptance, ...(order.budgetPerRunMicrousd == null ? {} : { budgetMicrousd: order.budgetPerRunMicrousd }) };
+    const digest = digestOf(draft, approval.profile, approval.route);
+    store.saveScope({ taskId, ...draft, proposedAt: now.toISOString(), digest, budgetMicrousd: order.budgetPerRunMicrousd ?? null, approvedAt: order.approval.at, approvedBy: approval.by, approvedDigest: digest }, {}, { profile: approval.profile, route: approval.route });
+    const sealed = store.sealScopeApproval(taskId, approval.by ?? "schedule", now, {}, undefined, "automation");
+    const sealedRoute = sealed ? store.sealedRouteOf(taskId) : null;
+    if (!sealed || sealedRoute === null || !sealedRoute.ok || routeDigestOf(sealedRoute.route) !== routeDigestOf(approval.route)) {
+        throw new StandingOrderRefused(!sealed ? "the approval couldn't be sealed" : sealedRoute !== null && !sealedRoute.ok ? sealedRoute.detail : "the sealed agents aren't the approved ones");
+    }
+    return { made: "filed", taskId, approved: true, note: null };
+}
+/** A standing order in the words a person reads before turning its schedule on. */
+export function describeStandingOrder(order, repo, schedule) {
+    const approval = standingApproval(order, repo, schedule);
+    return [
+        `Builds: ${order.goal}`,
+        ...(order.outOfScope === null ? [] : [`Not this: ${order.outOfScope}`]),
+        ...(order.touches.length === 0 ? [] : [`Only touches: ${order.touches.join(", ")}`]),
+        ...(order.requirements.length === 0 ? [] : [`Needs: ${order.requirements.join(", ")}`]),
+        ...(order.budgetPerRunMicrousd === null ? [] : [`Each run: up to $${(order.budgetPerRunMicrousd / 1_000_000).toFixed(2)}`]),
+        ...(order.costCeilingUsd === null ? [] : [`Every 7 days: up to $${order.costCeilingUsd.toFixed(2)}`]),
+        "One at a time: it skips while the last one is unfinished.",
+        approval.live ? `Approved by ${approval.by ?? "an approver"}: each run builds without asking, on the agents approved then.` : approval.problem === null ? "Each run waits for approval under the project's rules." : `Each run waits for approval: its earlier approval no longer applies (${approval.problem}).`,
+    ];
+}
+/** Every problem with a standing order's terms and schedule at once, as `field: problem` lines (none when it can be set up). */
+export function standingTermsProblems(terms, schedule) {
+    const problems = [];
+    // What an approver reads must be what it appears to be (no control, invisible or direction-override text), bounded in bytes too.
+    const unfit = (text, chars, bytes) => text.length > chars || Buffer.byteLength(text, "utf8") > bytes || hasForbiddenControls(text) || hasDisguisedText(text);
+    if (terms.goal.trim() === "" || unfit(terms.goal, 2_000, 8_000))
+        problems.push("goal: required, at most 2000 characters, no control or hidden characters");
+    if (terms.outOfScope !== null && unfit(terms.outOfScope, 2_000, 8_000))
+        problems.push("outOfScope: at most 2000 characters, no control or hidden characters");
+    if (terms.touches.length > 50 || terms.touches.some(one => one.trim() === "" || unfit(one, 200, 800)))
+        problems.push("touches: at most 50 paths, each non-empty and under 200 characters");
+    if (terms.requirements.length > 20 || terms.requirements.some(one => parseCapabilityKey(one) === null || unfit(one, 400, 400)))
+        problems.push("requirements: capability keys, `kind:name`, at most 20");
+    // Each firing copies its success checks forward unchanged and never asks again, so there must be at least one.
+    const read = parseAcceptanceCriteria(terms.acceptance);
+    if (read.problems.length > 0)
+        problems.push(`acceptance: ${read.problems.map(one => one.message).join("; ")}`);
+    else if (read.criteria.length === 0)
+        problems.push("acceptance: a repeating task needs at least one success check");
+    if (parseSchedule(schedule) === null)
+        problems.push(`schedule: \`every:<minutes>\` (${MIN_EVERY_MINUTES}–${MAX_EVERY_MINUTES}), \`daily:<HH:MM>\`, \`weekdays:<HH:MM>\` or \`weekly:<0–6>:<HH:MM>\`, with an optional @IANA/timezone`);
+    if (terms.costCeilingUsd !== null && (!Number.isFinite(terms.costCeilingUsd) || terms.costCeilingUsd <= 0))
+        problems.push("costCeilingUsd: a positive dollar amount, or none for no weekly limit");
+    if (terms.budgetPerRunMicrousd !== null && (!Number.isSafeInteger(terms.budgetPerRunMicrousd) || terms.budgetPerRunMicrousd <= 0))
+        problems.push("budgetPerRunMicrousd: a positive whole micro-dollar amount, or none");
+    return problems;
+}
+/**
+ * A scheduled flow a person set up (a template or a recipe; v115, what filing a routine was): a Build step that follows
+ * the task each firing files, then Done, and a schedule trigger carrying the terms as its standing order — with no
+ * approval, so each firing waits for approval under the project's rules. The schedule starts PAUSED with no time:
+ * nothing repeats until a person turns it on, and it starts counting then. Its tasks are filed as `filedBy`'s (default
+ * `by`; null files them as automation's). Inside the caller's transaction, if any.
+ */
+export function createScheduledFlow(store, input, now) {
+    const problems = standingTermsProblems(input.terms, input.schedule);
+    if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(input.stem))
+        problems.unshift("name: lowercase letters, digits and dashes, at most 41 — it starts each task's id");
+    if (input.name.trim() === "" || input.name.length > 80 || hasForbiddenControls(input.name))
+        problems.unshift("name: required, at most 80 characters");
+    if (problems.length > 0)
+        return { ok: false, message: problems.join("; ") };
+    const { terms } = input;
+    const order = {
+        stem: input.stem, goal: terms.goal, outOfScope: terms.outOfScope, touches: [...terms.touches], requirements: [...terms.requirements], acceptance: [...terms.acceptance],
+        budgetPerRunMicrousd: terms.budgetPerRunMicrousd, costCeilingUsd: terms.costCeilingUsd, singleFlight: true, filedBy: input.filedBy === undefined ? input.by : input.filedBy, routine: null, approval: null,
+    };
+    const zone = (x, color) => ({ x, y: 0, w: 260, h: 300, color });
+    const definition = { version: 1, start: "build", stages: [
+            { id: "build", title: "Build", kind: "task", zone: zone(0, "blue"), instructions: terms.goal, planning: "skip", approver: null, message: null, close: null, script: null, sort: null, next: "done", onFail: null },
+            { id: "done", title: "Done", kind: "done", zone: zone(420, "green"), instructions: null, planning: null, approver: null, message: null, close: null, script: null, sort: null, next: null, onFail: null },
+        ] };
+    return store.transact(() => {
+        const flow = store.createFlow({ repo: input.repo, name: input.name, definitionJson: JSON.stringify(definition), by: input.by }, now);
+        const trigger = store.addFlowTrigger({ flow, kind: "schedule", configJson: JSON.stringify({ kind: "schedule", schedule: input.schedule, title: input.name, description: null, zone: "build", order }), hookHash: null, cursor: null, nextAt: null, by: input.by }, now);
+        store.updateFlowTrigger(trigger, { state: "paused" }, now);
+        return { ok: true, flow, trigger };
+    });
+}

package/dist/flow-share.js

@@ -25,7 +25,7 @@ import { durationMinutes, durationWords, FlowContractError, flowTerms, inStepWor
 import { stageReferenceProblems } from "./contracts/stage-output.js";
 import { readVersioned } from "./contracts/contract.js";
 import { FLOW_ALIASES, FLOW_FILE_FORMAT, FLOW_FILE_VERSION, flowFileSchema, PARAMETER_ID } from "./contracts/flow.js";
-import { parseSchedule } from "./routine.js";
+import { parseSchedule } from "./flow-schedule.js";
 export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
 /** The largest flow file Toolroll reads or fetches. */
 export const FLOW_FILE_MAX_BYTES = 256 * 1024;

package/dist/flow-triggers.d.ts

@@ -20,7 +20,7 @@ export declare const CARDS_PER_CHECK = 10;
  * say, named by its path: no hidden characters and nothing that looks like a key, anywhere in the settings.
  */
 export declare function readTriggerSettings(raw: unknown): ContractResult<TriggerInput>;
-/** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in the routines' own form. */
+/** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in its stored form ("daily:09:00"). */
 export declare function scheduleFromWords(text: string): string | null;
 /** A GitHub repository as owner/name, read from a project's origin remote when it is on GitHub. */
 export declare function githubRepoOf(path: string): string | null;
@@ -92,6 +92,11 @@ export type TriggerMade = {
 export declare function addFlowTriggerTo(store: Store, flow: FlowRow, raw: unknown, actor: string, now: Date, dir: string | null): TriggerMade;
 /** A new secret address for a webhook trigger (the old one stops working at once). */
 export declare function renewFlowHook(store: Store, trigger: FlowTriggerRow, now: Date, dir: string): TriggerMade;
+/**
+ * Pause a trigger, or turn it on again. A schedule that never had a time (a routine moved to a flow while it waited
+ * for approval, v115) starts counting from now, as a new schedule does; one that was due while it was off fires once.
+ */
+export declare function setFlowTriggerOn(store: Store, trigger: FlowTriggerRow, on: boolean, now: Date): void;
 export declare function removeFlowTrigger(store: Store, trigger: FlowTriggerRow, now: Date, dir: string | null): void;
 export type Incoming = {
     key: string;

package/dist/flow-triggers.js

@@ -4,7 +4,7 @@ import { adapterPolicy } from "./server/route-policy.js";
  * them by hand.
  *
  * - button   — a named button with questions; pressing it makes a card from the answers.
- * - schedule — a card on a schedule (the routines' schedule rules: every N minutes, daily, weekly);
+ * - schedule — a card on a schedule (every N minutes, daily, weekdays, weekly), or a standing order's task;
  *              v90: or a project script run on the schedule, each item it prints a card.
  * - github   — new issues (optionally with a label), new pull requests, or failed checks on a branch.
  * - linear   — Linear issues in a team, moving into a state, and/or with a label.
@@ -37,7 +37,7 @@ import { flowCardText, flowDefinitionOf } from "./flow-engine.js";
 import { FlowContractError } from "./flows.js";
 import { parseContract } from "./contracts/contract.js";
 import { FLOW_ALIASES, FLOW_TRIGGER_KINDS, SECRETS_MAX, triggerConfigSchema, triggerInputSchema } from "./contracts/flow.js";
-import { describeSchedule, firstFireAt, nextFireAt, parseSchedule, WEEKDAYS } from "./routine.js";
+import { describeSchedule, fileStandingOrder, firstFireAt, nextFireAt, parseSchedule, StandingOrderRefused, WEEKDAYS } from "./flow-schedule.js";
 import { takeReply } from "./flow-replies.js";
 import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./mailbox.js";
 import { readFlowSecrets } from "./flow-secrets.js";
@@ -84,7 +84,7 @@ export function readTriggerSettings(raw) {
     }
     return read;
 }
-/** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in the routines' own form. */
+/** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in its stored form ("daily:09:00"). */
 export function scheduleFromWords(text) {
     const raw = text.trim().replace(/\s+/g, " ");
     if (parseSchedule(raw) !== null)
@@ -223,7 +223,7 @@ export function validateTriggerConfig(raw, context) {
         }
     }
 }
-/** The computer's time zone, as the routines name one. */
+/** The computer's time zone, as a schedule names one. */
 function localTimeZone() {
     try {
         return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
@@ -253,6 +253,9 @@ export function describeTrigger(config, store) {
         case "schedule": {
             const schedule = parseSchedule(config.schedule);
             const when = schedule === null ? config.schedule : describeSchedule(schedule);
+            // Its limits and terms are said once, in "What each run files" (describeStandingOrder).
+            if (config.order !== undefined)
+                return `${when.charAt(0).toUpperCase()}${when.slice(1)}: files the task “${config.title}”`;
             return config.script !== undefined ? `${when.charAt(0).toUpperCase()}${when.slice(1)}: runs the ${config.script} script, and each item it prints becomes a card` : `${when.charAt(0).toUpperCase()}${when.slice(1)}: “${config.title}”`;
         }
         case "github":
@@ -281,7 +284,7 @@ export function triggerHeadline(config, store) {
         case "schedule": {
             const schedule = parseSchedule(config.schedule);
             const when = schedule === null ? config.schedule : schedule.kind === "every" ? describeSchedule(schedule) : `${schedule.kind === "daily" ? "daily" : schedule.kind === "weekdays" ? "weekdays" : `${WEEKDAYS[schedule.day]}s`} at ${schedule.hhmm}`;
-            return { name: `${when.charAt(0).toUpperCase()}${when.slice(1)}`, detail: config.script !== undefined ? `Runs ${config.script}` : `“${config.title}”` };
+            return { name: `${when.charAt(0).toUpperCase()}${when.slice(1)}`, detail: config.script !== undefined ? `Runs ${config.script}` : config.order !== undefined ? `Files “${config.title}”` : `“${config.title}”` };
         }
         case "github": return { name: config.watch === "checks" ? `Failed checks on ${config.branch}` : config.watch === "pulls" ? `New pull requests${config.label === null ? "" : ` labeled ${config.label}`}` : config.label === null ? "New issues" : `Issues labeled ${config.label}`, detail: `GitHub · ${config.repo}` };
         case "linear": return { name: `Linear${config.team === null ? "" : ` ${config.team}`}${config.state === null ? "" : ` → ${config.state}`}`, detail: config.label === null ? "Linear issues" : `Labeled ${config.label}` };
@@ -449,6 +452,15 @@ export function renewFlowHook(store, trigger, now, dir) {
     const base = readHooksBase(dir);
     return { ok: true, id: trigger.id, said: "New address made; the old one no longer works. Copy it now; it isn't shown again.", reveal: { path: `${HOOK_PATH}${token}`, address: base === null ? null : `${base}${HOOK_PATH}${token}`, secret } };
 }
+/**
+ * Pause a trigger, or turn it on again. A schedule that never had a time (a routine moved to a flow while it waited
+ * for approval, v115) starts counting from now, as a new schedule does; one that was due while it was off fires once.
+ */
+export function setFlowTriggerOn(store, trigger, on, now) {
+    const config = on && trigger.nextAt === null ? triggerConfigOf(trigger) : null;
+    const schedule = config !== null && (config.kind === "schedule" || config.kind === "plane-review") ? parseSchedule(config.schedule) : null;
+    store.updateFlowTrigger(trigger.id, { state: on ? "active" : "paused", ...(schedule === null ? {} : { nextAt: firstFireAt(schedule, now) }) }, now);
+}
 export function removeFlowTrigger(store, trigger, now, dir) {
     store.updateFlowTrigger(trigger.id, { state: "removed", hookHash: null }, now);
     if (dir !== null)
@@ -497,6 +509,46 @@ function makeCard(store, trigger, config, item, by, now) {
         return { made: "added", note: null, card };
     });
 }
+/**
+ * v115: a schedule with a standing order (what a routine was) files its task and the card that follows it, together or
+ * not at all; a slot it skips says why on the trigger. The card starts in the schedule's build step, which follows the
+ * task it was filed with.
+ */
+function fileOrderCard(store, trigger, config, order, item, slot, now) {
+    const flow = store.getFlow(trigger.flow);
+    const definition = flow === null ? null : flowDefinitionOf(flow);
+    if (flow === null || definition === null || flow.state !== "active")
+        return { made: "skipped", note: "the flow isn't active", card: null };
+    const zone = startZone(config, definition);
+    if (definition.stages.find(one => one.id === zone)?.kind !== "task")
+        return { made: "skipped", note: "Skipped: the schedule's first step isn't a build step.", card: null };
+    if (store.flowTriggerSaw(trigger.id, item.key))
+        return { made: "seen", note: null, card: null };
+    const text = flowCardText(item.title, item.description);
+    if ("problem" in text)
+        return { made: "skipped", note: `Skipped: ${text.problem}`, card: null };
+    try {
+        return store.transact(() => {
+            if (store.flowTriggerSaw(trigger.id, item.key))
+                return { made: "seen", note: null, card: null };
+            const fired = fileStandingOrder(store, { flowId: flow.id, repo: flow.repo, trigger: trigger.id, schedule: config.schedule, order, title: text.title, slot }, now);
+            if (fired.made === "skipped") {
+                store.recordFlowTriggerEvent(trigger.id, item.key, null, fired.note, now);
+                return { made: "skipped", note: fired.note, card: null };
+            }
+            const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: zone, by: "Schedule", source: item.source }, now);
+            store.updateFlowCard(card, { task: fired.taskId, primaryTask: fired.taskId, waiting: "Filed as a task" }, now);
+            // The firing keeps its task: one-at-a-time and the weekly limit count it however the card moves later.
+            store.recordFlowTriggerEvent(trigger.id, item.key, card, null, now, fired.taskId);
+            return { made: "added", note: fired.note ?? (fired.approved ? `Filed ${fired.taskId}, approved.` : `Filed ${fired.taskId}; it waits for approval.`), card };
+        });
+    }
+    catch (error) {
+        if (!(error instanceof StandingOrderRefused))
+            throw error;
+        return { made: "skipped", note: `Skipped: ${error.message}. Nothing was filed.`, card: null };
+    }
+}
 const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 function outcomeWords(results, more) {
     const added = results.filter(one => one.made === "added").length;
@@ -589,10 +641,11 @@ function fireSchedule(store, trigger, config, now) {
     const slot = trigger.nextAt;
     const next = nextFireAt(schedule, slot, now);
     // One card at a time: while the last one still waits where it started, the slot is skipped, not piled up.
-    const last = store.lastFlowTriggerCard(trigger.id);
+    const last = config.order === undefined ? store.lastFlowTriggerCard(trigger.id) : null;
     const card = last === null ? null : store.getFlowCard(last);
     const flow = store.getFlow(trigger.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
+    // A standing order says itself when it waits (its last task unfinished); other schedules wait on their last card.
     if (card !== null && definition !== null && card.state === "active" && card.stage === startZone(config, definition) && card.entry === 1) {
         store.recordFlowTriggerEvent(trigger.id, `slot:${slot}`, null, "the last one hadn't been picked up", now);
         store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: "Skipped: the last card hasn't been picked up yet." }, now);
@@ -601,8 +654,9 @@ function fireSchedule(store, trigger, config, now) {
     const day = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: schedule.kind === "every" ? "UTC" : schedule.timezone ?? "UTC" }).format(new Date(slot));
     const fill = (text) => text.replace(/\{\{\s*date\s*\}\}/g, day);
     const title = /\{\{\s*date\s*\}\}/.test(config.title) ? fill(config.title) : `${config.title} — ${day}`;
-    const made = makeCard(store, trigger, config, { key: `slot:${slot}`, title, description: config.description === null ? null : fill(config.description), source: { kind: "schedule", label: "Schedule", url: null } }, "Schedule", now);
-    store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: made.made === "added" ? "Added a card." : made.note ?? "Nothing new." }, now);
+    const item = { key: `slot:${slot}`, title, description: config.description === null ? null : fill(config.description), source: { kind: "schedule", label: "Schedule", url: null } };
+    const made = config.order === undefined ? makeCard(store, trigger, config, item, "Schedule", now) : fileOrderCard(store, trigger, config, config.order, item, slot, now);
+    store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: made.made === "added" ? made.note ?? "Added a card." : made.note ?? "Nothing new." }, now);
     return made.made === "added" ? 1 : 0;
 }
 /** The problem a plane review's event key names, and the day: `plane:<problem>:<YYYY-MM-DD>`. */
@@ -683,10 +737,11 @@ export function runScheduleNow(store, trigger, actor, now) {
         return { ok: false, said: "Only a schedule without a script runs this way." };
     if (trigger.state !== "active")
         return { ok: false, said: "It's paused." };
-    const made = makeCard(store, trigger, config, { key: `now:${now.toISOString()}`, title: config.title.replace(/\{\{\s*date\s*\}\}/g, "today"), description: config.description, source: { kind: "schedule", label: `Run now by ${actor}`, url: null } }, "Schedule", now);
+    const item = { key: `now:${now.toISOString()}`, title: config.title.replace(/\{\{\s*date\s*\}\}/g, "today"), description: config.description, source: { kind: "schedule", label: `Run now by ${actor}`, url: null } };
+    const made = config.order === undefined ? makeCard(store, trigger, config, item, "Schedule", now) : fileOrderCard(store, trigger, config, config.order, item, now.toISOString(), now);
     if (made.made !== "added" || made.card === null)
         return { ok: false, said: made.note ?? "Nothing was added." };
-    store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: "Added a card (run now)." }, now);
+    store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: `${made.note ?? "Added a card."} (run now)` }, now);
     return { ok: true, card: made.card };
 }
 /** A schedule's script (v90): it runs in a clean folder inside the agents' fence; each item it prints is a card, once. */

package/dist/flows-cli.js

@@ -14,8 +14,9 @@ import { addCardToFlow, advanceFlows, crossProjectProblem, decideFlowCard, flowD
 import { chooseFlowCard } from './flow-send.js';
 import { saveScript } from './flow-scripts.js';
 import { exportFlow, fetchFlowFile, FLOW_FILE_MAX_BYTES, FlowFileError, importFlow, parseFlowFile, planFlowImport } from './flow-share.js';
+import { describeStandingOrder } from './flow-schedule.js';
 import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, switchOnStarter } from './flow-starters.js';
-import { addFlowTriggerTo, checkFlowTriggerNow, describeTrigger, removeFlowTrigger, triggerConfigOf, validateTriggerConfig } from './flow-triggers.js';
+import { addFlowTriggerTo, checkFlowTriggerNow, describeTrigger, removeFlowTrigger, setFlowTriggerOn, triggerConfigOf, validateTriggerConfig } from './flow-triggers.js';
 import { deciderOf, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowDigest, flowFromSteps, flowTerms, stepsFor } from './flows.js';
 import { verifyApproverByPassword } from './principal.js';
 import { projectName } from './project.js';
@@ -491,7 +492,7 @@ export async function runFlowsCommand(positional, flags, context) {
     if (action === 'trigger remove')
         removeFlowTrigger(store, trigger, now, context.configDir);
     else
-        store.updateFlowTrigger(trigger.id, { state: action === 'trigger pause' ? 'paused' : 'active' }, now);
+        setFlowTriggerOn(store, trigger, action !== 'trigger pause', now);
     record(flow.repo, 'accepted', `flow #${flow.id} trigger #${trigger.id}`);
     settle(flow.repo);
     const said = action === 'trigger remove' ? 'Trigger removed.' : action === 'trigger pause' ? 'Trigger paused.' : 'Trigger on again.';
@@ -532,7 +533,8 @@ function describeFlow(store, flow) {
         triggers: store.flowTriggers(flow.id).map(trigger => {
             const config = triggerConfigOf(trigger);
             return { id: trigger.id, kind: trigger.kind, state: trigger.state, words: config === null ? 'This trigger can\'t be read.' : describeTrigger(config, store),
-                zone: config?.zone ?? definition?.start ?? null, nextAt: trigger.nextAt, lastAt: trigger.lastAt, lastOutcome: trigger.lastOutcome, failing: trigger.failures > 0 };
+                zone: config?.zone ?? definition?.start ?? null, nextAt: trigger.nextAt, lastAt: trigger.lastAt, lastOutcome: trigger.lastOutcome, failing: trigger.failures > 0,
+                ...(config?.kind === 'schedule' && config.order !== undefined ? { order: describeStandingOrder(config.order, flow.repo, config.schedule) } : {}) };
         }),
         cards: store.flowCards(flow.id, true).slice(0, 10).map(card => cardOf(definition, card)),
     };
@@ -552,7 +554,9 @@ function showLines(flow) {
             ...(zone.ifFails === null ? [] : [`     ${zone.kind === 'approval' ? 'sent back' : zone.kind === 'sort' ? 'not sure' : zone.kind === 'wait' ? 'no reply' : zone.kind === 'choose' ? 'a reply' : 'if it fails'} → ${title(zone.ifFails)}`]),
         ]),
         '', 'Triggers',
-        ...(flow.triggers.length === 0 ? ['  none — add one with toolroll flows trigger add'] : flow.triggers.map(one => `  #${one.id} ${one.state === 'active' ? '' : `(${one.state}) `}${one.words} → ${title(one.zone)}${one.lastOutcome === null ? '' : ` · last: ${one.lastOutcome}`}`)),
+        ...(flow.triggers.length === 0 ? ['  none — add one with toolroll flows trigger add'] : flow.triggers.flatMap(one => [`  #${one.id} ${one.state === 'active' ? '' : `(${one.state}) `}${one.words} → ${title(one.zone)}${one.lastOutcome === null ? '' : ` · last: ${one.lastOutcome}`}`,
+            ...(one.order === undefined ? [] : one.order.map(line => `     ${line}`)),
+            ...(one.order !== undefined && one.state === 'paused' ? [`     Off: toolroll flows trigger resume ${flow.id} ${one.id} turns it on.`] : [])])),
         '', 'Recent cards',
         ...(flow.cards.length === 0 ? ['  none'] : flow.cards.map(one => `  #${one.id} ${one.title} · ${one.state === 'active' ? one.zoneTitle : one.state}${one.waiting === null ? '' : ` · ${one.waiting}`}`)),
     ];

package/dist/flows-ui.js

@@ -1,4 +1,5 @@
 import { draftFor, flowDefinitionOf } from "./flow-engine.js";
+import { describeStandingOrder } from "./flow-schedule.js";
 import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, planeStatusLink, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
 import { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS } from "./flows.js";
 import { flowInsights, troubleWords } from "./flow-insights.js";
@@ -190,6 +191,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             hook: config !== null && takesDeliveries(config) ? { ready: hookReady(trigger, setup.dir), needsSecret: config.kind === "linear" } : null,
             checkable: ((config?.kind === "github" || config?.kind === "linear") && config.delivery === "poll") || config?.kind === "email" || (config?.kind === "schedule" && config.script !== undefined) || config?.kind === "plane-review",
             shared: config?.kind === "button" && trigger.hookHash !== null,
+            ...(config?.kind === "schedule" && config.order !== undefined ? { order: describeStandingOrder(config.order, flow.repo, config.schedule) } : {}),
         };
     });
     return {

package/dist/flows.js

@@ -45,7 +45,7 @@
  * - done      — the end.
  *
  * The engine is deterministic and model-free: it runs in the worker's pass
- * beside routines, and no card ever skips an approval the task itself needs.
+ * beside builds, and no card ever skips an approval the task itself needs.
  */
 import { TEXT_LIMITS } from "./text-limits.js";
 import { createHash } from "node:crypto";