@@ -0,0 +1,19 @@
+---
+'@objectstack/spec': patch
+'@objectstack/plugin-approvals': patch
+---
+
+feat: `ExecutionStatus` gains `missed`, the run status for a scheduled flow's due time that passed while no kernel was ticking
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+`ExecutionStatus` gains a tenth member, `missed`, appended last so every reader that indexes `.options` keeps its positions. It records a scheduled flow's due time that passed while no kernel was ticking, written once by the next kernel that finds the gap, one entry per missed due time. It is terminal: the run never started, is never resumed and is never replayed. It is distinct from `cancelled` (nobody cancelled it) and from `failed` (nothing ran).
+
+No field is added. On an `ExecutionLog`, `startedAt` is the due time and `completedAt` the detection time; `durationMs` and `refusalMessage` are absent and `steps` is empty. On the stored run row, `started_at` and `finished_at` carry the same two instants, and `duration_ms`, `error` and `refusal_message` are absent.
+
+`ListRunsRequestSchema.status` and the REST `?status=` filter read the enum, so both accept `missed`. `AutomationResult.status`, `TriggerFlowResponseSchema.data.status` and `JobExecutionStatus` do not change.
+
+`@objectstack/plugin-approvals`: `RUN_STATUS_LIVENESS` maps `missed` to `terminal`, so an approval pending on a missed run is swept like one pending on any other finished run.
+
+This release only declares the value. The engine writes `missed` rows in a later release.
@@ -860,7 +860,7 @@ const result = AutomationApiErrorCode.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **name** | `string` | ✅ | Flow machine name (snake_case) |
-| **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying' \| 'refused'>` | optional | Filter by execution status |
+| **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying' \| 'refused' \| 'missed'>` | optional | Filter by execution status |
 | **limit** | `integer` | optional (default: `20`) | Maximum number of runs to return |
 | **cursor** | `never` | optional | [REMOVED] `cursor` was removed from GET /api/v1/automation/:name/runs in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — it was VALIDATED at the boundary and then read by nothing: the option reached the service and the engine never looked at it, no emit site has ever written the response half `nextCursor`, and the only ordering this door has is a required but non-unique `startedAt` timestamp that nothing ever minted a resume point from — so a caller looping "until the cursor runs out" re-read the first and only window forever, with no error. Delete the key. `limit` is the real window and STAYS: it is read end to end (boundary to service to store) and bounded to 1..100, so ask for a wider window instead of a next page. Read the response `hasMore` to learn whether the window was short — it is now COMPUTED from the engine rather than the constant `false` it used to be. |
 
 
@@ -104,7 +104,7 @@ const result = CheckpointSchema.parse(data);
 | **id** | `string` | ✅ | Execution instance ID |
 | **flowName** | `string` | ✅ | Machine name of the executed flow |
 | **flowVersion** | `integer` | optional | Version of the flow that was executed |
-| **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying' \| 'refused'>` | ✅ | Current execution status |
+| **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying' \| 'refused' \| 'missed'>` | ✅ | Current execution status |
 | **refusalMessage** | `string` | optional | Rendered `end` node `message` when `status` is `refused` — the per-record text the flow refused with. Absent on every other status. |
 | **trigger** | `{ type: string; recordId?: string; object?: string; userId?: string; … }` | ✅ | What triggered this execution |
 | **steps** | `{ nodeId: string; nodeType: string; nodeLabel?: string; status: Enum<'success' \| 'failure' \| 'skipped'>; … }[]` | ✅ | Ordered list of executed steps |
@@ -177,6 +177,7 @@ const result = CheckpointSchema.parse(data);
 * `timed_out`
 * `retrying`
 * `refused`
+* `missed`
 
 
 ---
 
@@ -529,6 +529,9 @@ export const RUN_STATUS_LIVENESS = {
   // documents it "Terminal, never resumed"; this is that sentence made
   // machine-readable for the one reader that has to act on it.
   refused:   'terminal',
+  // A scheduled due time that passed while no kernel was ticking: recorded
+  // once, never started, never resumed.
+  missed:    'terminal',
 } as const satisfies Record<ExecutionStatus, RunLiveness>;
 
 /**
 
@@ -18,15 +18,16 @@ import {
 
 describe('ExecutionStatus', () => {
   it('should accept all valid statuses', () => {
-    const valid = ['pending', 'running', 'paused', 'completed', 'failed', 'cancelled', 'timed_out', 'retrying', 'refused'];
+    const valid = ['pending', 'running', 'paused', 'completed', 'failed', 'cancelled', 'timed_out', 'retrying', 'refused', 'missed'];
     valid.forEach((v) => {
       expect(() => ExecutionStatus.parse(v)).not.toThrow();
     });
   });
 
-  it('names the refused terminal — appended LAST, so every `.options` index reader keeps its positions', () => {
-    expect(ExecutionStatus.options).toContain('refused');
-    expect(ExecutionStatus.options.at(-1)).toBe('refused');
+  it('names the refused and missed terminals — each appended LAST, so every `.options` index reader keeps its positions', () => {
+    expect(ExecutionStatus.options).toHaveLength(10);
+    expect(ExecutionStatus.options[8]).toBe('refused');
+    expect(ExecutionStatus.options.at(-1)).toBe('missed');
     expect(ExecutionStatus.options.slice(0, 8)).toEqual(
       ['pending', 'running', 'paused', 'completed', 'failed', 'cancelled', 'timed_out', 'retrying'],
     );
@@ -35,6 +36,9 @@ describe('ExecutionStatus', () => {
     expect(ExecutionStatus.safeParse('refused').success).toBe(true);
     expect(ExecutionStatus.safeParse('failed').success).toBe(true);
     expect(ExecutionStatus.safeParse('rejected').success).toBe(false);
+    // `missed` is its own member, not a spelling of `cancelled` or `failed`.
+    expect(ExecutionStatus.safeParse('missed').success).toBe(true);
+    expect(ExecutionStatus.safeParse('skipped').success).toBe(false);
   });
 
   it('should reject invalid statuses', () => {
 
@@ -36,6 +36,21 @@ export const ExecutionStatus = z.enum([
   // refusal text rides beside it on the run row as `refusalMessage`. Appended
   // last so every reader that indexes `.options` keeps its positions.
   'refused',     // Terminal: the flow refused (an `end` node with outcome: 'refused')
+  /**
+   * A scheduled flow's due time that passed while no kernel was ticking,
+   * recorded ONCE by the next kernel that found the gap (one entry per missed
+   * due time). Terminal: the run was never started, is never resumed, and is
+   * never replayed — no catch-up run follows it. DISTINCT from `cancelled`
+   * (nobody cancelled it) and from `failed` (nothing ran, so nothing failed).
+   *
+   * What the entry carries, with no field of its own: on the `ExecutionLog`,
+   * `startedAt` is the due time and `completedAt` the detection time, while
+   * `durationMs` and `refusalMessage` are absent and `steps` is empty; on the
+   * stored run row, `started_at` / `finished_at` carry the same two instants
+   * and `duration_ms`, `error` and `refusal_message` are absent. Appended last,
+   * like `refused`, so every reader that indexes `.options` keeps its positions.
+   */
+  'missed',      // Terminal: a scheduled due time passed while no kernel was ticking; never run
 ]);
 export type ExecutionStatus = z.input<typeof ExecutionStatus>;