@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/contract/attention.d.ts

@@ -1,21 +1,8 @@
-import type { RunIndexEntry, RunRecord } from './runs.ts';
+import type { WorkerWait } from './delegation.ts';
+import type { RunIndexEntry, RunRecord, RunSummary } from './runs.ts';
 /**
- * The one canonical attention function (cockpit spec, "Design system" → status grammar).
- *
- * Every surface that says "this run wants you" derives it from here: the cockpit's quick-list
- * dot, the table's dot, the thread header, the browser notification — and, since #553/#609, the
- * `cez task` CLI (`status`/`list` rows, and the `wait --until attention` decision). One function
- * means those can never disagree, which is the whole point of naming it in the spec. Before it
- * moved here the CLI kept its own two-line "is this settled" and the two drifted: a root parked
- * on its own workers stopped a CLI attention wait that the cockpit showed as "waiting on
- * 2 workers" (#553), and an operator cleared a run on `hasPendingHumanAsk: false` while the
- * cockpit showed Needs You (#609).
- *
- * Deliberately UI-free and Node-free: no React, no class names, no tokens, no `node:*` (the
- * contract tsconfig makes that structural). It maps a run to a bucket, a tone name and whether
- * the dot pulses; the components decide what those look like, the CLI prints the bucket and
- * the label. That is also what lets the cockpit's notification path call it from outside a
- * component tree.
+ * Canonical Node-free attention classification for browser and CLI. Map run facts to bucket,
+ * tone and pulse without UI state or backend-specific inference.
  */
 /**
  * The attention priority ladder, highest first (spec: permission > error > waiting/review >
@@ -46,7 +33,18 @@ export type AttentionTone = 'success' | 'pending' | 'danger' | 'accent' | 'info'
  * Shape is what separates rungs that share a hue: running vs monitoring, queued vs cancelled.
  */
 export type AttentionShape = 'filled' | 'ring' | 'workers';
+/**
+ * One id per rung of the ladder (spec 2026-10-17-unified-waits, "Status and display"), in its
+ * order (hearsay-tools/cezarion#1496). A rung's label is copy and can carry a count; a reader that
+ * decides something reads the id. Rung 8 has an id per PR target (merge since
+ * hearsay-tools/cezarion#1425) and the process rung sits between CI and timer
+ * (hearsay-tools/cezarion#1446). `unseen` is reserved: `isUnseen` never matches.
+ */
+export declare const ATTENTION_RUNGS: readonly ['needs-permission', 'failed', 'needs-you', 'needs-review', 'running', 'usage-limit', 'waiting-on-workers', 'waiting-for-ci', 'waiting-for-merge', 'waiting-for-command', 'monitoring', 'waiting-for-capacity', 'queued', 'done', 'cancelled', 'unseen'];
+export type AttentionRung = (typeof ATTENTION_RUNGS)[number];
 export interface Attention {
+    /** Which rung the run is on: what a reader compares, never `label`. */
+    rung: AttentionRung;
     bucket: AttentionBucket;
     tone: AttentionTone;
     shape: AttentionShape;
@@ -56,26 +54,37 @@ export interface Attention {
     label: string;
 }
 /** What attention derivation actually reads. `Pick`ed rather than the full `RunRecord` so
- *  surfaces that only have a status — the cockpit compare view's `GroupVariant` columns — can use
- *  the same canonical function instead of inventing a second status-to-tone mapping. `activity`
- *  is optional (#490), so status-only callers keep working unchanged. Delegation uses the slim
- *  contract projection: full run records, `ApiRun`s and workspace index rows all carry it. */
-export type AttentionInput = Pick<RunRecord, 'status' | 'activity' | 'autoResumeAt' | 'hasPendingHumanAsk'> & Pick<RunIndexEntry, 'delegation'>;
-/** Dependency wording shared by attention and relationship details (#375). A worker can only
- * wait on requests to its parent; only roots can wait for worker completion. */
-export declare function delegationWaitLabel(delegation: AttentionInput['delegation']): string | undefined;
+ *  surfaces that only have a status can use
+ *  the same canonical function instead of inventing a second status-to-tone mapping. Delegation
+ *  uses the slim contract projection: full run records, `ApiRun`s and workspace index rows all
+ *  carry it. A summary carries `waitingOn`; a full or stream-patched record carries `waits` and no
+ *  `waitingOn`, and `resolveWaitingOn` computes it from them (spec 2026-10-17-unified-waits). */
+export type AttentionInput = Pick<RunRecord, 'status' | 'autoResumeAt' | 'hasPendingPermission'> & Pick<RunIndexEntry, 'delegation'> & Partial<Pick<RunSummary, 'waitingOn' | 'waitWakePending'>> & Partial<Pick<RunRecord, 'waits'>>;
+/** Dependency wording for a worker wait in the legacy `WorkerWait` shape, which the run's
+ * relationship details show (#375). A worker can only wait on requests to its parent; only roots
+ * can wait for worker completion. */
+export declare function workerWaitLabel(role: 'root' | 'worker', wait: Pick<WorkerWait, 'requestIds' | 'outcomes' | 'workerIds'>): string;
 /**
- * `RunRecord` → attention.
- *
- * The chain below *is* the priority order — first match wins, so `error` can never be masked by a
- * lower rung. Tones follow the cockpit mockups (`mockups/tasks-home.html`):
+ * `RunRecord` → attention: the spec's ladder (2026-10-17-unified-waits, "Status and display"),
+ * read from the wait list alone since phase 4b (hearsay-tools/cezarion#1236).
+ * First match wins. Presentation comes from one rung table, with worker wording built separately.
+ */
+export declare function deriveAttention(run: AttentionInput): Attention;
+/**
+ * The task states a project's webhook can send deliveries for (hearsay-tools/cezarion#1356),
+ * named as the cockpit names them. `waiting-other` is every wait kind without an option of its
+ * own, including kinds added later. A change that gives a kind its own option adds that option,
+ * by config migration, to every stored list holding `waiting-other`.
+ */
+export declare const WEBHOOK_TRIGGERS: readonly ['needs-you', 'failed', 'done', 'cancelled', 'running', 'waiting-workers', 'waiting-ci', 'waiting-timer', 'waiting-other'];
+export type WebhookTrigger = (typeof WEBHOOK_TRIGGERS)[number];
+/** What a webhook with no stored `triggers` sends: the states that end a task or need a person. */
+export declare const DEFAULT_WEBHOOK_TRIGGERS: readonly WebhookTrigger[];
+/**
+ * `RunRecord` → the webhook state it is in, or `undefined` for none (hearsay-tools/cezarion#1356).
  *
- *  - `waiting` → amber/pending: the agent stopped and is asking you something.
- *  - `review`/permission → blue `--info`: there is work to look at (was brand teal until #617).
- *  - `running` → the violet family (`--status-running`), pulsing and filled; `monitoring` is the
- *    same hue as a ring, and a parked parent is the same hue as the robot (#617 status key).
- *  - `queued`/`scheduled` → neutral ring, still: parked, not transitioning. `cancelled` shares the
- *    neutral hue but is filled — it has ended.
- *  - `done`/`failed` → the green/red outcome, still.
+ * Read off `deriveAttention`'s rung, so the webhook and the status dot never disagree. A waiting
+ * run on rung 3 reads its top wait: a wait kind the dot has no rung for reads as Needs you there
+ * and as `waiting-other` here, since nobody is asked anything.
  */
-export declare function deriveAttention(run: AttentionInput, hasPendingHumanAsk?: boolean): Attention;
+export declare function deriveWebhookState(run: AttentionInput): WebhookTrigger | undefined;

package/dist/contract/automation-requests.d.ts

@@ -0,0 +1,308 @@
+import { z } from 'zod';
+/**
+ * The editable body of both kinds. Every kind-specific key is optional here because which ones a
+ * body must (or must not) carry depends on the kind, and on `PUT` the kind is the STORED one when
+ * the body omits it — the service's `resolveAutomationKind` owns those rules.
+ */
+export declare const automationEditableSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        github: "github";
+        schedule: "schedule";
+    }>>;
+    events: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "issue.labeled": "issue.labeled";
+        "issue.opened": "issue.opened";
+        "issue.unlabeled": "issue.unlabeled";
+        "pull_request.opened": "pull_request.opened";
+    }>>>;
+    intervalSeconds: z.ZodOptional<z.ZodNumber>;
+    filters: z.ZodOptional<z.ZodObject<{
+        includeExisting: z.ZodOptional<z.ZodBoolean>;
+        requireCurrentLabels: z.ZodOptional<z.ZodBoolean>;
+        authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assignees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        anyLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludeLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        changedLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lookbackDays: z.ZodDefault<z.ZodNumber>;
+        maxRecords: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            daily: "daily";
+            hours: "hours";
+            once: "once";
+            weekdays: "weekdays";
+            weekly: "weekly";
+        }>;
+        hour: z.ZodOptional<z.ZodNumber>;
+        minute: z.ZodOptional<z.ZodNumber>;
+        day: z.ZodOptional<z.ZodNumber>;
+        every: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<6>, z.ZodLiteral<8>, z.ZodLiteral<12>]>>;
+        at: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        latestStartMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    task: z.ZodObject<{
+        prompt: z.ZodString;
+        workflow: z.ZodOptional<z.ZodString>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            runner: z.ZodOptional<z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                cursor: "cursor";
+                omp: "omp";
+                opencode: "opencode";
+                pi: "pi";
+            }>>;
+            agentProfile: z.ZodOptional<z.ZodString>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            bashAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            command: z.ZodOptional<z.ZodString>;
+            onFail: z.ZodOptional<z.ZodObject<{
+                retry: z.ZodString;
+                max: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        runner: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            cursor: "cursor";
+            omp: "omp";
+            opencode: "opencode";
+            pi: "pi";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        worktree: z.ZodOptional<z.ZodBoolean>;
+        autonomous: z.ZodOptional<z.ZodBoolean>;
+        archiveWhenDone: z.ZodOptional<z.ZodBoolean>;
+        autoMergePr: z.ZodOptional<z.ZodBoolean>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        variants: z.ZodOptional<z.ZodLiteral<1>>;
+    }, z.core.$loose>;
+}, z.core.$strict>;
+export type AutomationEditable = z.infer<typeof automationEditableSchema>;
+export declare const automationCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        github: "github";
+        schedule: "schedule";
+    }>>;
+    events: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "issue.labeled": "issue.labeled";
+        "issue.opened": "issue.opened";
+        "issue.unlabeled": "issue.unlabeled";
+        "pull_request.opened": "pull_request.opened";
+    }>>>;
+    intervalSeconds: z.ZodOptional<z.ZodNumber>;
+    filters: z.ZodOptional<z.ZodObject<{
+        includeExisting: z.ZodOptional<z.ZodBoolean>;
+        requireCurrentLabels: z.ZodOptional<z.ZodBoolean>;
+        authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assignees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        anyLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludeLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        changedLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lookbackDays: z.ZodDefault<z.ZodNumber>;
+        maxRecords: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            daily: "daily";
+            hours: "hours";
+            once: "once";
+            weekdays: "weekdays";
+            weekly: "weekly";
+        }>;
+        hour: z.ZodOptional<z.ZodNumber>;
+        minute: z.ZodOptional<z.ZodNumber>;
+        day: z.ZodOptional<z.ZodNumber>;
+        every: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<6>, z.ZodLiteral<8>, z.ZodLiteral<12>]>>;
+        at: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        latestStartMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    task: z.ZodObject<{
+        prompt: z.ZodString;
+        workflow: z.ZodOptional<z.ZodString>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            runner: z.ZodOptional<z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                cursor: "cursor";
+                omp: "omp";
+                opencode: "opencode";
+                pi: "pi";
+            }>>;
+            agentProfile: z.ZodOptional<z.ZodString>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            bashAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            command: z.ZodOptional<z.ZodString>;
+            onFail: z.ZodOptional<z.ZodObject<{
+                retry: z.ZodString;
+                max: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        runner: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            cursor: "cursor";
+            omp: "omp";
+            opencode: "opencode";
+            pi: "pi";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        worktree: z.ZodOptional<z.ZodBoolean>;
+        autonomous: z.ZodOptional<z.ZodBoolean>;
+        archiveWhenDone: z.ZodOptional<z.ZodBoolean>;
+        autoMergePr: z.ZodOptional<z.ZodBoolean>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        variants: z.ZodOptional<z.ZodLiteral<1>>;
+    }, z.core.$loose>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const automationUpdateSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        github: "github";
+        schedule: "schedule";
+    }>>;
+    events: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "issue.labeled": "issue.labeled";
+        "issue.opened": "issue.opened";
+        "issue.unlabeled": "issue.unlabeled";
+        "pull_request.opened": "pull_request.opened";
+    }>>>;
+    intervalSeconds: z.ZodOptional<z.ZodNumber>;
+    filters: z.ZodOptional<z.ZodObject<{
+        includeExisting: z.ZodOptional<z.ZodBoolean>;
+        requireCurrentLabels: z.ZodOptional<z.ZodBoolean>;
+        authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assignees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        anyLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludeLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        changedLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lookbackDays: z.ZodDefault<z.ZodNumber>;
+        maxRecords: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            daily: "daily";
+            hours: "hours";
+            once: "once";
+            weekdays: "weekdays";
+            weekly: "weekly";
+        }>;
+        hour: z.ZodOptional<z.ZodNumber>;
+        minute: z.ZodOptional<z.ZodNumber>;
+        day: z.ZodOptional<z.ZodNumber>;
+        every: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<6>, z.ZodLiteral<8>, z.ZodLiteral<12>]>>;
+        at: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        latestStartMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    task: z.ZodObject<{
+        prompt: z.ZodString;
+        workflow: z.ZodOptional<z.ZodString>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            runner: z.ZodOptional<z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                cursor: "cursor";
+                omp: "omp";
+                opencode: "opencode";
+                pi: "pi";
+            }>>;
+            agentProfile: z.ZodOptional<z.ZodString>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            bashAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            command: z.ZodOptional<z.ZodString>;
+            onFail: z.ZodOptional<z.ZodObject<{
+                retry: z.ZodString;
+                max: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        runner: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            cursor: "cursor";
+            omp: "omp";
+            opencode: "opencode";
+            pi: "pi";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        worktree: z.ZodOptional<z.ZodBoolean>;
+        autonomous: z.ZodOptional<z.ZodBoolean>;
+        archiveWhenDone: z.ZodOptional<z.ZodBoolean>;
+        autoMergePr: z.ZodOptional<z.ZodBoolean>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        variants: z.ZodOptional<z.ZodLiteral<1>>;
+    }, z.core.$loose>;
+    expectedRevision: z.ZodNumber;
+}, z.core.$strict>;
+export declare const automationCheckRequestSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        execute: "execute";
+        preview: "preview";
+    }>;
+}, z.core.$strict>;
+export declare const automationLogQuerySchema: z.ZodObject<{
+    automationId: z.ZodOptional<z.ZodString>;
+    result: z.ZodOptional<z.ZodEnum<{
+        baseline: "baseline";
+        "catch-up": "catch-up";
+        duplicate: "duplicate";
+        error: "error";
+        failed: "failed";
+        launched: "launched";
+        manual: "manual";
+        missed: "missed";
+        "no-match": "no-match";
+        preview: "preview";
+        "rate-limited": "rate-limited";
+        skipped: "skipped";
+    }>>;
+    event: z.ZodOptional<z.ZodEnum<{
+        "issue.labeled": "issue.labeled";
+        "issue.opened": "issue.opened";
+        "issue.unlabeled": "issue.unlabeled";
+        "pull_request.opened": "pull_request.opened";
+    }>>;
+    since: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;

package/dist/contract/automation-schedule.d.ts

@@ -1,24 +1,26 @@
 import { z } from 'zod';
 /**
- * A scheduled automation's trigger (spec `.ai/specs/2026-10-02-scheduled-automations.md`, issue
- * #766; origin: upstream open-mercato/cezar #985) and the pure occurrence math over it, shared
- * by the server's schedule runner and the cockpit's editor preview — one implementation, so what
- * the editor previews is what the timer fires.
- *
- * Four bounded shapes rather than cron: every day at HH:MM, weekdays at HH:MM, one weekday at
- * HH:MM, every N hours from midnight. A cron string is DERIVED for display (`cronOf` /
- * `parseCron`), never stored and never evaluated — the shapes are what the math runs.
+ * Bounded schedule shapes and shared occurrence math for server and editor. Repeating cron
+ * strings are derived display/input forms, never stored or evaluated. once uses its own timezone
+ * and latest-start bound, with no cron form.
  */
-export declare const SCHEDULE_TYPES: readonly ['daily', 'weekdays', 'weekly', 'hours'];
+export declare const SCHEDULE_TYPES: readonly ['daily', 'weekdays', 'weekly', 'hours', 'once'];
 export type ScheduleType = (typeof SCHEDULE_TYPES)[number];
 /** The `every` choices for the `hours` shape — the ones that divide a day evenly. */
 export declare const SCHEDULE_HOURS_OPTIONS: readonly [1, 2, 3, 4, 6, 8, 12];
 export type ScheduleEvery = (typeof SCHEDULE_HOURS_OPTIONS)[number];
 export declare const WEEKDAY_NAMES: readonly ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+/** The shortest late-start window: the runner's grace window, so jitter never misses a once. */
+export declare const ONCE_MIN_LATEST_START_MINUTES = 10;
+export declare const ONCE_MAX_LATEST_START_MINUTES = 43200;
+/** The refusal of a one-time schedule whose time has passed: the server's 400 and the editor's field message. */
+export declare const ONCE_PAST_DUE_MESSAGE = "the due time has passed; choose a later time or use Run now";
+export declare function unknownTimeZoneMessage(zone: string): string;
 export declare const automationScheduleSchema: z.ZodObject<{
     type: z.ZodEnum<{
         daily: "daily";
         hours: "hours";
+        once: "once";
         weekdays: "weekdays";
         weekly: "weekly";
     }>;
@@ -26,6 +28,9 @@ export declare const automationScheduleSchema: z.ZodObject<{
     minute: z.ZodOptional<z.ZodNumber>;
     day: z.ZodOptional<z.ZodNumber>;
     every: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<6>, z.ZodLiteral<8>, z.ZodLiteral<12>]>>;
+    at: z.ZodOptional<z.ZodString>;
+    timeZone: z.ZodOptional<z.ZodString>;
+    latestStartMinutes: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type AutomationSchedule = z.infer<typeof automationScheduleSchema>;
 /** The same shape with every default filled — what the math and the labels read. */
@@ -35,13 +40,34 @@ export interface NormalizedSchedule {
     minute: number;
     day: number;
     every: ScheduleEvery;
+    at?: string;
+    timeZone?: string;
+    latestStartMinutes?: number;
 }
 export declare function normalizeSchedule(schedule: AutomationSchedule): NormalizedSchedule;
+/** A `once` schedule's instant (UTC ms), read in its own zone; `null` for other shapes or a bad zone. */
+export declare function onceInstant(schedule: AutomationSchedule): number | null;
+/** `at`'s calendar fields, or `null` when it is not `YYYY-MM-DDTHH:MM`. */
+export declare function onceWallParts(at: string): {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+} | null;
+/** `at` names a real calendar day and clock time. Shared by the schedule, the CLI and the agent tools. */
+export declare const isRealOnceAt: (at: string) => boolean;
+/**
+ * The last instant a `once` may still start: `latestStartMinutes` after it, never less than the
+ * runner's 10-minute grace window. `null` when there is no limit (or no instant).
+ */
+export declare function onceCutoff(schedule: AutomationSchedule): number | null;
 /** `HH:MM`. */
 export declare function hm(hour: number, minute?: number): string;
-/** The trigger cell's text: `every day at 04:00`, `weekdays at 07:30`, `every 6 hours`, `Tuesdays at 02:00`. */
+/** The trigger cell's text: `every day at 04:00`, `weekdays at 07:30`, `every 6 hours`, `Tuesdays at 02:00`,
+ *  `once on Thu 29 Oct 2026 at 09:00 (Europe/Warsaw)`. */
 export declare function scheduleLabel(schedule: AutomationSchedule): string;
-/** The derived five-field cron string (cron's Sunday is 0). */
+/** The derived five-field cron string (cron's Sunday is 0). A `once` has none: cron has no year. */
 export declare function cronOf(schedule: AutomationSchedule): string;
 /**
  * The inverse of `cronOf` for the four shapes it emits — and ONLY those. Anything else (a
@@ -54,6 +80,9 @@ export declare function parseCron(expression: string): AutomationSchedule | null
  * `limit` so a caller asking for a year of hourly runs gets the first `limit`, not a stall.
  * Each (day, wall time) yields at most one instant, and no instant is yielded twice, which is
  * what makes a DST fall-back hour fire once and a spring-forward gap fire once.
+ *
+ * A `once` yields its single instant when it lies in the range, read in its own zone: `timeZone`
+ * is ignored for it.
  */
 export declare function occurrencesBetween(schedule: AutomationSchedule, fromMs: number, toMs: number, timeZone: string, limit?: number): number[];
 /** The first instant strictly after `afterMs`, or `null` for an unknown zone. */