@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/automations/project-files.js

@@ -0,0 +1,43 @@
+import { mergeAppendOnly } from '../merged-streams.js';
+import { automationDefinitionSchema } from './types.js';
+/** Files arrive in precedence order. Unknown top-level keys survive a counterpart write. */
+export function mergeProjectAutomationFiles(filename, files) {
+    if (files.length === 1)
+        return files[0];
+    const ordered = [...files].reverse();
+    const result = Object.assign({}, ...ordered);
+    if (filename === 'automations.json') {
+        const byId = new Map();
+        const tombstones = {};
+        for (const file of ordered) {
+            for (const raw of file.automations) {
+                const parsed = automationDefinitionSchema.safeParse(raw);
+                if (parsed.success) {
+                    byId.set(parsed.data.id, parsed.data);
+                    delete tombstones[parsed.data.id];
+                }
+            }
+            for (const [id, time] of Object.entries((file.tombstones ?? {}))) {
+                byId.delete(id);
+                tombstones[id] = time;
+            }
+        }
+        result.tombstones = tombstones;
+        result.automations = [...byId.values()];
+    }
+    else if (filename === 'automation-state.json') {
+        result.states = Object.assign({}, ...ordered.map(file => file.states));
+    }
+    return result;
+}
+/** Deduplicate by raw identity, then replay chronologically (`mergeAppendOnly`). A page read over two
+ *  logs numbers the merged rows 1..n in that order: the cursor stays positive, and a row appended later
+ *  (newest time, highest raw seq) only extends it. One log alone keeps its stored sequences. */
+export function mergeProjectAutomationLog(filename, sources, page = false) {
+    const field = (row, key) => row[key];
+    const receipts = filename === 'automation-receipts.ndjson';
+    const merged = mergeAppendOnly(sources, row => receipts ? `${field(row, 'receiptId')}:${field(row, 'status')}:${field(row, 'updatedAt')}` : `${field(row, 'automationId')}:${field(row, 'seq')}`, row => String(field(row, receipts ? 'updatedAt' : 'ts')), receipts ? undefined : (a, b) => Number(field(a, 'seq')) - Number(field(b, 'seq')));
+    const project = page && !receipts && sources.slice(1).some(rows => rows.length > 0);
+    return project ? merged.map((row, index) => ({ ...row, seq: index + 1 })) : merged;
+}
+//# sourceMappingURL=project-files.js.map

package/dist/automations/project-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-files.js","sourceRoot":"","sources":["../../src/automations/project-files.ts"],"names":[],"mappings":"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"}

package/dist/automations/prompts.d.ts

@@ -0,0 +1,12 @@
+export declare const CREATE_AUTOMATION_SKILL_NAME = "create-cezarion-automation";
+/** This process's own `automation` command, shell-quoted — the same construction as `artifact publish`. */
+export declare function automationCliCommand(): string;
+/**
+ * The definition reference, as `cez automation schema` prints it and as the skill body embeds it.
+ * One string so the two never disagree; `prompts.test.ts` pins it to the storage schema.
+ */
+export declare const AUTOMATION_SCHEMA_REFERENCE: string;
+/** The part composed into every task's system prompt while automations are on and reachable. */
+export declare function automationsPrompt(command: string): string;
+/** The built-in skill's body — the full playbook a run under `create-cezarion-automation` follows. */
+export declare function createAutomationSkillBody(command: string): string;

package/dist/automations/prompts.js

@@ -0,0 +1,162 @@
+/**
+ * Short task instructions and the full automation playbook, composed only for reachable
+ * automations. Use the current absolute CLI command; do not substitute another automation
+ * mechanism.
+ */
+import { fileURLToPath } from 'node:url';
+import { RUNNER_IDS } from '../core/agent-runner.js';
+export const CREATE_AUTOMATION_SKILL_NAME = 'create-cezarion-automation';
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+/** This process's own `automation` command, shell-quoted — the same construction as `artifact publish`. */
+export function automationCliCommand() {
+    const source = import.meta.url.endsWith('.ts');
+    const entry = fileURLToPath(new URL(source ? '../index.ts' : '../index.js', import.meta.url));
+    return [process.execPath, ...(source ? ['--import', import.meta.resolve('tsx')] : []), entry].map(quote).join(' ') + ' automation';
+}
+/**
+ * The definition reference, as `cez automation schema` prints it and as the skill body embeds it.
+ * One string so the two never disagree; `prompts.test.ts` pins it to the storage schema.
+ */
+export const AUTOMATION_SCHEMA_REFERENCE = `An automation definition is one JSON object. Two kinds: a GitHub poll ("kind": "github") or a schedule ("kind": "schedule"). The three examples below are valid definitions as written; the keys they use are explained after them.
+
+A GitHub poll:
+
+{
+  "name": "Review every new pull request",
+  "description": "What this automation is for",
+  "kind": "github",
+  "events": ["pull_request.opened"],
+  "intervalSeconds": 300,
+  "filters": { "excludeLabels": ["wontfix"], "lookbackDays": 7, "maxRecords": 25 },
+  "task": {
+    "prompt": "Review pull request #{{github.number}} ({{github.title}}) at {{github.url}}: read the diff, run the tests, and post your findings as a review.",
+    "workflow": "quick-task",
+    "worktree": true,
+    "autonomous": true
+  }
+}
+
+A schedule:
+
+{
+  "name": "Nightly dependency bump",
+  "kind": "schedule",
+  "schedule": { "type": "daily", "hour": 4, "minute": 0 },
+  "task": { "prompt": "Run npm outdated, bump patch and minor versions, run the tests, open a draft PR if anything changed. Today is {{date}}." }
+}
+
+A one-time schedule (replace "at" with a future time):
+
+{
+  "name": "Check the rollout next week",
+  "kind": "schedule",
+  "schedule": { "type": "once", "at": "2030-01-15T09:00", "timeZone": "Europe/Warsaw", "latestStartMinutes": 360 },
+  "task": { "prompt": "Check the error rate of the release deployed last week, compare it with the week before, and report what changed." }
+}
+
+Top-level keys:
+- "name": required, 1-200 characters.
+- "description": optional, up to 2000 characters.
+- "kind": "github" (the default when omitted) or "schedule".
+- "events" (GitHub poll, required): 1-4 of pull_request.opened, issue.opened, issue.labeled, issue.unlabeled.
+- "intervalSeconds" (GitHub poll): how often GitHub is polled, 60-86400 seconds; default 300.
+- "filters" (GitHub poll): may be {}; every key is optional, and a candidate must pass ALL the given filters.
+- "schedule" (schedule, required): "type" is "daily" or "weekdays" (Mon-Fri) at "hour" and "minute"; "weekly" adds "day" (1 = Monday ... 7 = Sunday); "hours" uses "every" (1 | 2 | 3 | 4 | 6 | 8 | 12) from 00:00. These repeating shapes run in the cockpit's own time zone. "once" runs a single time: "at" is the local wall time "YYYY-MM-DDTHH:MM" in "timeZone" (an IANA name such as Europe/Warsaw, required), and the optional "latestStartMinutes" (10-43200) is how late after "at" a start may still launch when Cezarion was not running; without it a late start always launches. Once its task exists, a one-time schedule is archived with the task's id ("archived": { "outcome": "launched", "runId": ... }) and never fires again. "run <id>" (Run now) consumes it the same way. "cancel <id>" archives it without a task ("outcome": "cancelled"). An archived schedule cannot change; "list --archived only" shows them. "at" must be in the future when it is created, moved or enabled.
+- "task": the ordinary task each match or occurrence launches.
+
+"filters" keys:
+- "includeExisting": boolean (default false). When true, include matching events before enablement within lookbackDays. Turning this on for an enabled poll reopens the window on its next check; durable receipts prevent duplicate launches.
+- "requireCurrentLabels": boolean (default false). Opt in to rechecking label filters against the live issue before receipt reservation and task creation; obsolete transitions do not claim a task. Historical event matching is unchanged when omitted.
+- "authors": GitHub logins that opened it. "assignees": current assignees.
+- "allLabels": must carry every one of these labels. "anyLabels": must carry at least one. "excludeLabels": must carry none.
+- "changedLabels": REQUIRED for issue.labeled and issue.unlabeled: the label whose change fires it.
+- "lookbackDays": 1-90 (default 7), how far back one poll looks. "maxRecords": 1-100 (default 25), the most candidates one poll considers.
+
+"task" keys:
+- "prompt": required, the prompt template.
+- "workflow": a workflow name. OR "steps", never both. To run a skill, use one agent step naming it: "steps": [{ "id": "task", "skill": "some-skill", "prompt": "{{task}}" }].
+- "runner": ${RUNNER_IDS.join(' | ')}. "model" and "effort": optional overrides.
+- Legacy "variants" counts above 1 are refused: parallel variants are removed. Use owned workers for explicit comparisons.
+- "worktree": isolate each run in its own git worktree (recommended: true).
+- "autonomous": never park to ask; an automation has no one watching (recommended: true).
+- "archiveWhenDone": boolean (default false). Archive each launched task after Done. Without a PR, archive on Done even when autoMergePr is true.
+- "autoMergePr": boolean (default false). After Done, merge the task's PR only when current-head CI and GitHub rules pass. This may mark a draft ready. With archiveWhenDone, merge before archive. Pending or blocked actions show a reason on the task. These settings apply to future tasks; editing the automation does not change tasks it already launched.
+- "allowWorkers": boolean (default true). Agents in each launched task may start and resume Cezar workers, each a separate paid agent session.
+- "allowMessaging": boolean (default true). Agents in each launched task may message other tasks in this project.
+- "systemPrompt": extra guidance for every launched run.
+
+For a GitHub poll, name, events and task are required; for a schedule, name, kind, schedule and task.
+
+Prompt placeholders, substituted per launch. GitHub poll: {{github.kind}} (issue | pull request), {{github.number}}, {{github.title}}, {{github.url}}, {{github.author}}, {{github.assignees}}, {{github.labels}} and {{github.event}}. Schedule: {{date}}, {{time}}, {{project}} and {{automation}}. Any other placeholder is rejected. The matched item's details (or the scheduled instant) are also appended to every launched task as untrusted context, so the prompt need not repeat them.
+
+A new automation is PAUSED unless created with --enable. Enabling a GitHub poll establishes a current-time baseline by default; filters.includeExisting opts in to older matches within the configured lookback. Test filter previews the selected window without advancing the execution cursor or launching tasks. Enabling a schedule arms its next occurrence.`;
+/** The part composed into every task's system prompt while automations are on and reachable. */
+export function automationsPrompt(command) {
+    return `## Automations
+This cockpit can do recurring work without you doing it once. An automation is either a bounded GitHub poll (a new pull request, a new issue, a label added to or removed from an issue, optionally filtered by author, assignee or labels) or a schedule (every day at a time, weekdays, one weekday a week, every N hours). It launches an ordinary task for every match or occurrence, from a prompt template you write. When the user asks for something to happen "whenever", "every time" or "each time" a pull request or issue appears or is labelled, or "every day at", "on weekdays", "every Friday", "every 6 hours", they are asking for an automation: create one instead of doing the work once, and instead of polling GitHub or sleeping yourself.
+
+The CLI is ${command}. Every command prints one JSON object:
+
+  ${command} schema                                   the definition shape, every key, every bound, the prompt placeholders
+  ${command} create --file <def.json> [--enable]      create one from JSON (paused unless --enable); --json '<json>' or stdin work too
+  ${command} add --name <n> (--cron "0 4 * * *" | --on <event> --every 5m) --prompt <p> [--workflow w] [--runner r] [--model m] [--no-autonomous] [--archive-when-done] [--auto-merge-pr] [--no-workers] [--no-messaging] [--label l] [--author a] [--changed-label l] [--include-existing] [--enable]
+  ${command} check <id> [--execute]                   GitHub poll: preview what the filter matches right now (launches nothing without --execute)
+  ${command} add --name <n> (--at <YYYY-MM-DDTHH:MM> --tz <zone> | --in <30m|6h|7d>) [--latest-start 6h] --prompt <p> [--enable]
+                                                      a one-time schedule: one task at that time, then archived
+  ${command} run <id>                                 schedule: launch it once, now
+  ${command} cancel <id>                              one-time schedule: archive it without a task
+  ${command} list | show <id> | update <id> --file <def.json> | enable <id> | pause <id> | delete <id>
+                                                      (update replaces each key given; "task" merges key by key, null removes one)
+
+When work must start much later (tomorrow, next week) as a new task, create a one-time schedule (add --at or --in) instead of keeping this session waiting on repeated timers; enable it only when the user asked for the work to run later.
+
+Completion controls are off by default. Use --archive-when-done or task.archiveWhenDone only when the user asks to archive completed tasks. Use --auto-merge-pr or task.autoMergePr only when the user asks to merge their PRs. Both act after Done; auto merge may mark a draft ready and still requires current-head CI and GitHub rules. With both on, merge before archive; without a PR, archive on Done. Changes affect future tasks only.
+
+Read the schema first. Create the automation PAUSED. A paused automation is the finished state of this task, not a step awaiting confirmation: enable it only when the user's own request explicitly asks for it to be switched on. An instruction to continue autonomously, not to ask for confirmation, or to make reasonable assumptions is not that request. For a GitHub poll, run a preview check so the user sees what it would match; for a schedule, report its next occurrence. Put the "url" the command prints in your final message. If the command exits non-zero or is refused, stop and report that automations are unavailable on this cockpit, quoting its error: do not write a cron job, a GitHub Action or a polling script as a substitute.`;
+}
+/** The built-in skill's body — the full playbook a run under `create-cezarion-automation` follows. */
+export function createAutomationSkillBody(command) {
+    return `# Create an automation
+
+You turn the user's request into an automation on this cockpit: a bounded poll of this repository's pull requests or issues, or a schedule, that launches an ordinary task for every match or occurrence. You do NOT do the recurring work yourself, and you do not add cron jobs, GitHub Actions, webhooks or polling scripts to the repository: the cockpit already polls and already keeps time.
+
+The CLI is ${command}. Every command prints one JSON object and exits 0 on success.
+
+## 1. Understand the request
+
+Every automation answers two questions. Find both in the user's message before writing anything:
+
+- **Trigger**: a GitHub event (a new pull request \`pull_request.opened\`, a new issue \`issue.opened\`, a label added \`issue.labeled\` or removed \`issue.unlabeled\`) with the filters that narrow it (authors, assignees, labels it must or must not carry; a label event needs \`filters.changedLabels\`), or a schedule (every day at a time, weekdays, one weekday a week, every N hours; \`"kind": "schedule"\`, in the cockpit's own time zone).
+- **Task**: what the launched task must do for each match, as a prompt template. Write it the way you would brief a colleague who sees only that text plus the item's number, title, URL, author and labels: the goal, the checks to run, how to finish (a review comment, a draft PR, a report). Use the placeholders the schema lists.
+
+If the user named a skill, workflow, runner or model for the launched tasks, use it (a skill is one inline step: \`"steps": [{ "id": "task", "skill": "<name>", "prompt": "{{task}}" }]\`). Otherwise leave those keys out so the cockpit's defaults apply. Keep \`"worktree": true\` and \`"autonomous": true\`: an automation runs unattended, so a task that parks to ask a question waits forever. For a poll, pick an interval that matches how urgent a match is (300 seconds is the default; an hourly triage needs 3600). If the request leaves the trigger or the task genuinely open, ask one precise question and stop; do not guess a filter that could launch tasks on the wrong items.
+
+Leave \`task.archiveWhenDone\` and \`task.autoMergePr\` off unless the user asks for the matching completion action. Autonomy and enabling an automation do not enable either control. They act only after Done. Auto merge may mark a draft ready; current-head CI and GitHub rules must pass. With both on, merge before archive; without a PR, archive on Done. Editing these settings affects future tasks only.
+
+## 2. Create it
+
+Run \`${command} schema\` and read it. Write the definition as JSON to a file outside the repository (your temp directory is fine) and create it:
+
+    ${command} create --file <def.json>
+
+It is created PAUSED. The output carries its \`id\` and the cockpit \`url\` where the user can edit it. A paused automation is the finished state of this task, not a step awaiting confirmation: enable it only when the user's own request explicitly asks for it to be switched on. An instruction to continue autonomously, not to ask for confirmation, or to make reasonable assumptions is not that request. Then add \`--enable\`, and never otherwise. If the command exits non-zero, stop and report its \`error\` exactly: do not work around it.
+
+## 3. Preview before anyone enables it
+
+For a GitHub poll:
+
+    ${command} check <id>
+
+This runs the filter against GitHub now and counts the matches without launching anything. Check the labels, author, event and selected history window when an expected match is absent. By default, an enabled poll excludes events before its activation. Set \`filters.includeExisting: true\` only when the user asks to include older matches within the configured lookback; receipts still prevent duplicate launches. Preview ignores the execution cursor and never advances it.
+
+For a schedule there is nothing to preview: report the schedule and its next occurrence. \`${command} run <id>\` launches it once now if the user wants to see the task before the first scheduled one.
+
+## 4. Finish
+
+Your final message names the automation, its id, its cockpit url, whether it is paused or enabled, what the preview matched (or when the schedule next fires), and the exact prompt template it will launch. Keep the definition file out of the repository.
+
+## Reference
+
+${AUTOMATION_SCHEMA_REFERENCE}`;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/automations/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/automations/prompts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,MAAM,CAAC,MAAM,4BAA4B,GAAG,4BAA4B,CAAC;AAEzE,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAEvE,2GAA2G;AAC3G,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9F,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;AACrI,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA0D7B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;mWAc+T,CAAC;AAEpW,gGAAgG;AAChG,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO;;;aAGI,OAAO;;IAEhB,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;;IAEP,OAAO;IACP,OAAO;IACP,OAAO;;;;;;;kuBAOutB,CAAC;AACnuB,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,yBAAyB,CAAC,OAAe;IACvD,OAAO;;;;aAII,OAAO;;;;;;;;;;;;;;;QAeZ,OAAO;;MAET,OAAO;;;;;;;;MAQP,OAAO;;;;6FAIgF,OAAO;;;;;;;;EAQlG,2BAA2B,EAAE,CAAC;AAChC,CAAC"}

package/dist/automations/schedule-runner.d.ts

@@ -0,0 +1,153 @@
+import type { AutomationStore } from './store.ts';
+import { type AutomationDefinition, type AutomationReceipt, type OnceScheduleDefinition, type ScheduleAutomationDefinition } from './types.ts';
+/**
+ * Evaluate due schedules under the project lease. Repeating schedules launch at most the latest
+ * eligible occurrence, then advance; lease contention must not consume or advance it. One-time
+ * schedules use their separate late-start policy.
+ */
+export declare const SCHEDULE_GRACE_MS: number;
+export declare const SCHEDULE_CATCH_UP_MS: number;
+export declare const SCHEDULE_AUTO_PAUSE_AFTER = 3;
+/** `late` and `retry` are a one-time schedule's own: a start after downtime, a failed launch fired again. */
+export type ScheduleTrigger = 'schedule' | 'catch-up' | 'manual' | 'late' | 'retry';
+export interface ScheduleOccurrence {
+    /** The scheduled wall-time instant (UTC ISO); for `manual`, the launch time. */
+    at: string;
+    trigger: ScheduleTrigger;
+}
+export type ScheduleLauncher = (definition: ScheduleAutomationDefinition, occurrence: ScheduleOccurrence, receiptId: string) => Promise<{
+    runId: string;
+}>;
+export interface ScheduleRunnerHandle {
+    projectId: string;
+    store: AutomationStore;
+    /** The zone every schedule is evaluated in — the server's own. */
+    timeZone: string;
+    /** Absent = detection only (tests, or a cockpit that cannot launch): nothing is launched. */
+    launch?: ScheduleLauncher;
+    onChange?: (automationId: string, revision: number) => void;
+    now?: () => number;
+    /**
+     * Reconcile crash-leftover reservations before duplicate detection. Do not settle this process’s
+     * in-flight reservations. A receipt must resolve to its created run or a retryable launch error.
+     */
+    reconcile?: () => Promise<void>;
+    /**
+     * Asked right before a timer fire launches. Throws `AutomationProjectUnavailableError` while the
+     * project cannot launch a task — its run store cannot open (#779) — and the fire then reserves,
+     * advances, logs and counts nothing: the workspace timer retries it at its floor, and the
+     * occurrence fires once the store opens again. Absent: always ready.
+     */
+    ready?: () => Promise<void>;
+}
+export type ScheduleFireOutcome = {
+    result: 'launched' | 'catch-up' | 'manual';
+    runId: string;
+    occurrenceAt: string;
+} | {
+    result: 'skipped' | 'duplicate' | 'lease-held' | 'failed' | 'detection-only';
+    occurrenceAt?: string;
+};
+export declare const SCHEDULE_LEASE_HELD_REASON = "automation lease is held by another process; retrying shortly";
+/** `fire` met a held or non-current lease; the workspace timer re-arms it at the retry floor. */
+export declare class ScheduleLeaseHeldError extends Error {
+    constructor();
+}
+export declare class AutomationProjectUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class ScheduleRunner {
+    private readonly handle;
+    constructor(handle: ScheduleRunnerHandle);
+    private now;
+    /**
+     * When the timer should next fire this definition: the stored `nextRunAt`, or — for a
+     * definition never armed, or whose schedule was edited (the PUT clears `nextRunAt`) — the next
+     * occurrence after now, which is then persisted so every process agrees on it.
+     */
+    dueAt(definition: ScheduleAutomationDefinition): number | null;
+    /** The timer fired (or boot found a past-due occurrence): apply the age rule and launch. */
+    fire(definition: ScheduleAutomationDefinition): Promise<ScheduleFireOutcome>;
+    /** `POST /automations/:id/run`: fire now, by hand, paused or not; `nextRunAt` is untouched. */
+    runNow(definition: ScheduleAutomationDefinition): Promise<ScheduleFireOutcome>;
+    /** Retry a `launch-error` receipt of this kind: the same receipt, fired again by hand. */
+    retry(definition: ScheduleAutomationDefinition, receipt: AutomationReceipt): Promise<ScheduleFireOutcome>;
+    /**
+     * The archive invariant: a `once` with a `launched` receipt is archived. A launch writes the
+     * receipt first and the archive second, so a crash in between leaves the receipt; every later
+     * action on the definition calls this first and writes the missing archive from it. Answers the
+     * archived definition, or `undefined` when the automation has no launched receipt.
+     */
+    healArchive(definition: OnceScheduleDefinition): AutomationDefinition | undefined;
+    /** The receipt key every launch path of a `once` shares; an edit of `at` or `timeZone` moves it. */
+    private onceEventId;
+    /** The timer fired a `once`, or found it due at boot. Called under the lease, current revision. */
+    private fireOnce;
+    /**
+     * Launches a `once` under the lease: through its existing receipt when an earlier launch failed
+     * (one key, at most one task), else a fresh reservation. A launched receipt archives instead.
+     */
+    private runOnce;
+    private rereserve;
+    /** The launch's run, or why it failed. */
+    private tryLaunch;
+    /** Settle `receipt` as launched, with its run. */
+    private launchedReceipt;
+    /** Settle `receipt` as a failed launch. */
+    private launchError;
+    /** Receipt first, archive second: the order the archive invariant relies on. */
+    private launchOnce;
+    /** A one-time log row is a record, not a gate: the stop or archive it follows has already landed. */
+    private logOnce;
+    private stopOnce;
+    /**
+     * Settles every unresolved receipt of a `once` before any decision on it: a `reserved` receipt
+     * no launch here is running is a crash leftover, perhaps another cockpit's after this one booted.
+     * Reconciliation turns it into `launched` (a task claims it; the archive then heals) or
+     * `launch-error` (the schedule is Failed). Answers the archived definition, as `healArchive`.
+     */
+    settleOnce(definition: OnceScheduleDefinition): Promise<AutomationDefinition | undefined>;
+    /**
+     * Run now and Retry act on this process's cached definition, which another cockpit may have
+     * edited or deleted since. Re-read it under the lease: the fresh schedule definition (paused is
+     * fine, those are manual actions), or `undefined` after notifying when it is gone or no longer
+     * a schedule, so the caller launches and writes nothing.
+     */
+    private currentUnderLease;
+    /** Runs `operation` under the project lease; `undefined` when the lease is held or not current. */
+    private underLease;
+    private launch;
+    private launchReserved;
+    private recordFailure;
+    /**
+     * Pauses the CURRENT revision, not the one this fire started with: the definition may have been
+     * edited while the launch ran — here or in another cockpit, hence the re-read — and the failure
+     * count belongs to the automation, not to a revision. Pausing the stale copy would either
+     * conflict or revert the edit. Already paused, deleted or no longer a schedule: nothing to do.
+     */
+    private pause;
+    private advance;
+    /**
+     * The `revision`/`nextRunAt` pair a timer fire writes. An edit that landed meanwhile already
+     * bumped the state's revision (never moved back) and, when it changed the schedule or resumed
+     * the definition, re-armed `nextRunAt` — which then stands. An edit that left `nextRunAt`
+     * alone (a rename) left the schedule alone too, so advancing from the captured one is right.
+     */
+    private advanced;
+    /**
+     * The occurrences in `[due, now]`: the latest one and how many there are. `occurrencesBetween`
+     * stops at its cap EARLIEST-first, so the latest is searched for on its own — in the catch-up
+     * window, else in the week before it (every shape recurs within 7 days; 9 covers a DST week) —
+     * and a count that reached the cap is reported as a lower bound, never as an exact number.
+     */
+    private missed;
+    private logSkipped;
+}
+/**
+ * A `once` that ended without a task: pause the CURRENT revision and record why, in one write.
+ * Already paused, archived or gone: nothing to do (the reason still lands in state). Shared with
+ * receipt reconciliation, which settles a crash-lost launch into Failed the same way.
+ */
+export declare function stopOnceSchedule(store: AutomationStore, id: string, outcome: 'failed' | 'missed', onChange?: (automationId: string, revision: number) => void): void;