objectstack-ai · os-sales · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026
diff --git a/.changeset/automation-resume-stranded-details.md b/.changeset/automation-resume-stranded-details.md
@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": minor
+"@objectstack/runtime": minor
+"@objectstack/client": minor
+---
+
+The automation resume route's `400 FLOW_FAILED` now says whether the run is stranded.
+
+`POST /api/v1/automation/:name/runs/:runId/resume` answers a run that consumed its pause and then failed with `400 FLOW_FAILED`, and until now its `error.details` carried the run's two artefacts only (`errorMessage`, `summary`). The engine's own verdict was dropped at the door: `AutomationResult.status: 'stranded'` — a run that is terminally failed *but* repairable by an explicit operator verb, because the pause a durable decision was waiting on is gone with the failure — reached the wire as the same `400` a plain terminal failure does, so an HTTP-only caller could not tell "beyond reach" from "repair waiting".
+
+- **`@objectstack/spec`** declares `ResumeFailureDetailsSchema` (`@objectstack/spec/api`): `{ runId, status?: 'failed' | 'stranded', repairable }` — the machine-readable shape of a resume failure told to the caller, declared once so every carrier of the family ruling spells the same members.
+- **`@objectstack/runtime`**: the resume door's `400 FLOW_FAILED` details now carry that structure beside `errorMessage` / `summary`. `runId` is the run the resume was addressed to; `status` is the engine's own stamp, forwarded verbatim when it set one and never synthesised (the subflow-child-failed exit stamps none today); `repairable` is `status === 'stranded'` and is **always present on this arm** — present-and-false on a plain terminal failure, deliberately, so an absent member reads as an older server rather than as "not repairable". The code stays `FLOW_FAILED` (no `FLOW_STRANDED` sibling is minted), so a client that treats it as terminal keeps working and one that wants to offer a repair branches on `details.repairable`, never on the message text. The trigger door and `/actions` are unchanged: they never resume, so the member is absent there and absent means "not a resume".
+- **`@objectstack/client`**: `automation.resume` documents the new members.
diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx
@@ -750,6 +750,37 @@ try {
 }
 ```
 
+**The resume door says one thing more.** `client.automation.resume()` rejects
+with the same `400` `FLOW_FAILED` when a run consumed its pause and then failed
+— and there the `details` also carry the engine's verdict, because one of those
+failures is *stranded*: terminal like any failure, but the pause a durable
+decision was waiting on is gone with it and only an explicit operator verb can
+re-arm the run. The shape is `ResumeFailureDetailsSchema` from
+`@objectstack/spec/api`; branch on it, never on the message text:
+
+```typescript
+import { ResumeFailureDetailsSchema } from '@objectstack/spec/api';
+
+try {
+  await client.automation.resume('order_approval', runId, { inputs });
+} catch (err) {
+  if (!isApiError(err) || err.code !== 'FLOW_FAILED') throw err;
+  const verdict = ResumeFailureDetailsSchema.safeParse(err.details);
+  if (verdict.success && verdict.data.repairable) {
+    // verdict.data.status === 'stranded' — verdict.data.runId names the run
+    // an operator can re-arm; offer that instead of closing as terminal.
+  }
+}
+```
+
+`repairable` is always present on the resume door's `400` — `false` on a plain
+terminal failure, deliberately, so an absent member reads as an older server
+rather than as "not repairable". `status` is the engine's own stamp
+(`'stranded'` or `'failed'`), forwarded when the engine set one and never
+invented by the door. The code stays `FLOW_FAILED`: there is no `FLOW_STRANDED`
+sibling, and the trigger door's `400` carries `errorMessage` / `summary` only —
+it never resumes, so "repairable" has no referent there.
+
 ---
 
 ## Configuration

diff --git a/content/docs/automation/flows.mdx b/content/docs/automation/flows.mdx
@@ -688,6 +688,32 @@ POST /api/v1/automation/{flow}/runs/{runId}/resume
   segment](#retry-pause-boundary).
 </Callout>
 
+### A resume that fails downstream says whether the run is stranded
+
+The suspension is consumed *before* the downstream nodes run (that is what buys
+exactly-once across a crash), so a node that throws after the resume leaves a
+run that is terminal **and** whose pause is gone. The engine names that state
+`status: 'stranded'` — distinct from a plain `failed`, because an explicit
+operator verb can still re-arm it — and the resume route forwards the verdict
+in the `400` `FLOW_FAILED` details, beside the author's `errorMessage` and the
+per-node `summary`:
+
+```json
+400  { "error": { "code": "FLOW_FAILED", "message": "Node 'tail' failed: …",
+       "details": { "runId": "run_42", "status": "stranded", "repairable": true,
+                    "errorMessage": "…", "summary": { … } } } }
+```
+
+Branch on `details.repairable`, never on the message: it is `true` exactly when
+`status` is `stranded`, and it is **always present** on this route's `400` —
+`false` on a plain terminal failure, so an absent member reads as an older
+server rather than as "not repairable". `status` is the engine's own stamp,
+forwarded when it set one and never invented by the route. The code does not
+change (there is no `FLOW_STRANDED`), and the trigger route's `400` carries
+`errorMessage` / `summary` only — it never resumes, so the question has no
+referent there. The shape is `ResumeFailureDetailsSchema` in
+`@objectstack/spec/api`.
+
 ### Who may resume — the gate is the suspended node
 
 The resume route is generic, so **the node the run is parked on** decides

diff --git a/content/docs/permissions/system-context.mdx b/content/docs/permissions/system-context.mdx
@@ -160,12 +160,12 @@ The largest single consumer — **17 of the 106 sites**.
 | 49 | Action `requiredPermissions` bypassed | runtime | Get: engine self-invocation runs any action | `action-execution.ts:401` |
 | 50 | `manage_metadata` bypassed on metadata writes | runtime, rest | Get: schema writes without the capability | `domains/meta.ts:471`, `:874`, `rest-server.ts:5520`, `:6977`, `:7225`, `:7656`, `:7849` |
 | 51 | The shared metadata-write verdict itself returns `allowed` | metadata-core | Get: the one function all of row 50's doors consult answers yes before any capability is examined | `meta-write-capability.ts:134` |
-| 52 | Anonymous-deny seam satisfied on the domain dispatchers and the package/federation routes | runtime, rest | Get: passes with no `userId` | `domains/actions.ts:421`, `domains/ai.ts:60`, `domains/automation.ts:989`, `domains/meta.ts:232`, `domains/security.ts:78`, `domains/packages.ts:552`, `external-datasource-routes.ts:302`, `package-routes.ts:97` |
+| 52 | Anonymous-deny seam satisfied on the domain dispatchers and the package/federation routes | runtime, rest | Get: passes with no `userId` | `domains/actions.ts:421`, `domains/ai.ts:60`, `domains/automation.ts:1079`, `domains/meta.ts:232`, `domains/security.ts:78`, `domains/packages.ts:552`, `external-datasource-routes.ts:302`, `package-routes.ts:97` |
 | 53 | MCP principal check satisfied | runtime | Get: MCP surface reachable with no user | `domains/mcp.ts:61` |
 | 54 | Package REST route capability gate bypassed | rest | Get: package read/write over REST without `manage_metadata` / `studio.access` / `setup.access` | `package-routes.ts:102` |
 | 55 | Package domain capability gates bypassed | runtime | Get: package management and package-inventory reads without the capability | `domains/packages.ts:250`, `:283` |
 | 56 | Activation write / authoring refusals do not fire | runtime | Get: activation artifacts writable and authorable without the activation-authoring capability | `activation-gate.ts:177`, `:268` |
-| 57 | Automation run-state read, flow-authoring write and unrelated-screen read all pass | runtime | Get: run state, flow writes and screen reads with no grant | `domains/automation.ts:254`, `:545`, `:635` |
+| 57 | Automation run-state read, flow-authoring write and unrelated-screen read all pass | runtime | Get: run state, flow writes and screen reads with no grant | `domains/automation.ts:255`, `:546`, `:636` |
 | 58 | Audience-binding suggestion recording skipped | plugin-security | Lose: install-time suggestions are not recorded for system callers | `suggested-audience-bindings.ts:703` |
 | 59 | Email-template / webhook provenance stamps skipped | plugin-email, plugin-webhooks | Lose: the row is not marked as an admin customization | `email-template-provenance.ts:77`, `webhook-provenance.ts:68` |
 | 60 | **Automation flow data nodes re-add the `owner_id` stamp** (the one place row 2's gap is compensated inline) | service-automation | Get: a flow-authored INSERT under system elevation still lands owned, when the run resolved a user. Fill-only — flow-authored values win | `runtime-identity.ts:279`, called from `builtin/crud-nodes.ts:319` |

diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx
@@ -30,8 +30,8 @@ GET    /api/automation/:name/runs/:runId       — Get single execution run
 ## TypeScript Usage
 
 ```typescript
-import { AutomationApiErrorCode, AutomationFlowPathParamsSchema, AutomationRunPathParamsSchema, CreateFlowRequestSchema, CreateFlowResponseSchema, DeleteFlowRequestSchema, DeleteFlowResponseSchema, FlowSummarySchema, GetFlowRequestSchema, GetFlowResponseSchema, GetRunRequestSchema, GetRunResponseSchema, ListFlowsRequestSchema, ListFlowsResponseSchema, ListRunsRequestSchema, ListRunsResponseSchema, ToggleFlowRequestSchema, ToggleFlowResponseSchema, TriggerFlowRequestSchema, TriggerFlowResponseSchema, UpdateFlowRequestSchema, UpdateFlowResponseSchema } from '@objectstack/spec/api';
-import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api';
+import { AutomationApiErrorCode, AutomationFlowPathParamsSchema, AutomationRunPathParamsSchema, CreateFlowRequestSchema, CreateFlowResponseSchema, DeleteFlowRequestSchema, DeleteFlowResponseSchema, FlowSummarySchema, GetFlowRequestSchema, GetFlowResponseSchema, GetRunRequestSchema, GetRunResponseSchema, ListFlowsRequestSchema, ListFlowsResponseSchema, ListRunsRequestSchema, ListRunsResponseSchema, ResumeFailureDetailsSchema, ToggleFlowRequestSchema, ToggleFlowResponseSchema, TriggerFlowRequestSchema, TriggerFlowResponseSchema, UpdateFlowRequestSchema, UpdateFlowResponseSchema } from '@objectstack/spec/api';
+import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ResumeFailureDetails, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = AutomationApiErrorCode.parse(data);
@@ -511,6 +511,19 @@ const result = AutomationApiErrorCode.parse(data);
 | **hasMore** | `boolean` | ✅ | Whether more runs are available |
 
 
+---
+
+## ResumeFailureDetails
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **runId** | `string` | ✅ | The run the resume was addressed to - the run that failed, and on the `stranded` arm the run an operator verb can re-arm. Named so a caller acts on an identifier instead of parsing one out of the message |
+| **status** | `Enum<'failed' \| 'stranded'>` | optional | The engine's own lifecycle verdict for the run, forwarded verbatim when the producer stamped one and never synthesised by the door - absent when the engine reported no status (a subflow child that failed terminally, an engine that predates the discriminator). `stranded` is the terminally-failed-but-repairable run of `AutomationResult.status`; `failed` says the run ran and was rejected. These two terminal-failure members of that union are the only ones that can reach a 400 |
+| **repairable** | `boolean` | ✅ | Whether the engine says this run can still be re-armed by an operator verb - `true` exactly when `status` is `stranded`, derived from the engine's discriminator and never from the message text. Always present on this arm: `false` is the honest answer for every other exit, the ones that report no status included, because an absent member would be indistinguishable from a server that predates this field, and promising a repair verb that will refuse is worse than promising nothing |
+
+
 ---
 
 ## ToggleFlowRequest

diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1574 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1575 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -20,7 +20,7 @@ counts are sums of the rows they head. Regenerate with
 | Module | Pages | Schemas | Description |
 | :--- | ---: | ---: | :--- |
 | [AI Protocol](/docs/references/ai) | 11 | 66 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
-| [API Protocol](/docs/references/api) | 31 | 436 | REST contracts, endpoints, routing, realtime, batch, discovery. |
+| [API Protocol](/docs/references/api) | 31 | 437 | REST contracts, endpoints, routing, realtime, batch, discovery. |
 | [Automation Protocol](/docs/references/automation) | 13 | 73 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. |
 | [Cloud Protocol](/docs/references/cloud) | 11 | 94 | Environments, packages and versions, marketplace, developer portal, tenancy. |
 | [Data Protocol](/docs/references/data) | 29 | 166 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
@@ -33,7 +33,7 @@ counts are sums of the rows they head. Regenerate with
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 33 | 272 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 153 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **198** | **1574** | 14 protocol modules |
+| **Total** | **198** | **1575** | 14 protocol modules |
 
 ---
 
@@ -61,7 +61,7 @@ Agents, tools, skills, RAG and knowledge sources, model registry, conversations.
 
 ## API Protocol
 
-**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **31 pages, 436 schemas**
+**Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **31 pages, 437 schemas**
 
 REST contracts, endpoints, routing, realtime, batch, discovery.
 
@@ -70,7 +70,7 @@ REST contracts, endpoints, routing, realtime, batch, discovery.
 | [`analytics.zod.ts`](/docs/references/api/analytics) | `AnalyticsEndpoint`, `AnalyticsMetadataResponse`, `AnalyticsQueryRequest`, `AnalyticsResultResponse`, `AnalyticsSqlResponse`, `GetAnalyticsMetaRequest` |
 | [`auth.zod.ts`](/docs/references/api/auth) | `AuthProvider`, `LoginRequest`, `LoginType`, `RefreshTokenRequest`, `RegisterRequest`, `Session`, `SessionResponse`, `SessionUser`, `UserProfileResponse` |
 | [`auth-endpoints.zod.ts`](/docs/references/api/auth-endpoints) | `AuthEndpoint`, `AuthFeaturesConfig`, `AuthProviderInfo`, `DeviceRequestResponse`, `DeviceTokenResponse`, `EmailPasswordConfigPublic`, `GetAuthConfigResponse` |
-| [`automation-api.zod.ts`](/docs/references/api/automation-api) | `AutomationApiErrorCode`, `AutomationFlowPathParams`, `AutomationRunPathParams`, `CreateFlowRequest`, `CreateFlowResponse`, `DeleteFlowRequest`, `DeleteFlowResponse`, `FlowSummary`, `GetFlowRequest`, `GetFlowResponse`, `GetRunRequest`, `GetRunResponse`, `ListFlowsRequest`, `ListFlowsResponse`, `ListRunsRequest`, `ListRunsResponse`, `ToggleFlowRequest`, `ToggleFlowResponse`, `TriggerFlowRequest`, `TriggerFlowResponse`, `UpdateFlowRequest`, `UpdateFlowResponse` |
+| [`automation-api.zod.ts`](/docs/references/api/automation-api) | `AutomationApiErrorCode`, `AutomationFlowPathParams`, `AutomationRunPathParams`, `CreateFlowRequest`, `CreateFlowResponse`, `DeleteFlowRequest`, `DeleteFlowResponse`, `FlowSummary`, `GetFlowRequest`, `GetFlowResponse`, `GetRunRequest`, `GetRunResponse`, `ListFlowsRequest`, `ListFlowsResponse`, `ListRunsRequest`, `ListRunsResponse`, `ResumeFailureDetails`, `ToggleFlowRequest`, `ToggleFlowResponse`, `TriggerFlowRequest`, `TriggerFlowResponse`, `UpdateFlowRequest`, `UpdateFlowResponse` |
 | [`batch.zod.ts`](/docs/references/api/batch) | `BatchConfig`, `BatchOperationResult`, `BatchOperationType`, `BatchOptions`, `BatchRecord`, `BatchUpdateRequest`, `BatchUpdateResponse`, `CrossObjectBatchDroppedFields`, `CrossObjectBatchOperation`, `CrossObjectBatchRequest`, `CrossObjectBatchResponse`, `DeleteManyRequest`, `UpdateManyRecord`, `UpdateManyRequest` |
 | [`contract.zod.ts`](/docs/references/api/contract) | `ApiError`, `BaseResponse`, `BatchLoadingStrategy`, `BulkRequest`, `BulkResponse`, `CreateRequest`, `DataLoaderConfig`, `DeleteResponse`, `ExportRequest`, `IdRequest`, `ListRecordResponse`, `ModificationResult`, `QueryOptimizationConfig`, `RecordData`, `SingleRecordResponse`, `UpdateRequest` |
 | [`discovery.zod.ts`](/docs/references/api/discovery) | `ApiRoutes`, `CapabilityDescriptor`, `Discovery`, `DiscoveryEnvironment`, `RouteHealthEntry`, `RouteHealthReport`, `ServiceInfo`, `ServiceSelfInfo`, `ServiceStatus`, `WellKnownCapabilities` |

diff --git a/docs/audits/2026-07-unknown-key-strictness-ledger.counts.md b/docs/audits/2026-07-unknown-key-strictness-ledger.counts.md
@@ -257,7 +257,7 @@ directory rather than per file.
 | Dir | Sites |
 |---|---|
 | `ai/` | 77 |
-| `api/` | 450 |
+| `api/` | 451 |
 | `cloud/` | 83 |
 | `identity/` | 32 |
 | `integration/` | 8 |

diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -4533,9 +4533,27 @@ export class ObjectStackClient {
        *   err.message;                 // the node failure, verbatim
        *   err.details?.errorMessage;   // the flow author's `errorMessage`
        *   err.details?.summary;        // per-node accounting of the failed run
+       *   err.details?.runId;          // the run this resume was addressed to
+       *   err.details?.status;         // 'stranded' | 'failed' — the engine's verdict, when it stamped one
+       *   err.details?.repairable;     // true exactly when `status` is 'stranded'
        * }
        * ```
        *
+       * **Since #15221 the 400 tells a stranded run from a plain failure.**
+       * A resume that consumed the pause and then failed downstream leaves
+       * the run *stranded* — terminal like any failure, but the pause a
+       * durable decision was waiting on is gone with it and only an explicit
+       * operator verb can re-arm it. The engine says so
+       * (`AutomationResult.status: 'stranded'`), and the door forwards that
+       * verdict in `err.details`: branch on `err.details.repairable`, never
+       * on the message text. `repairable` is always present on this 400 —
+       * `false` on a plain terminal failure, deliberately, so an absent
+       * member reads as an older server rather than as "not repairable".
+       * The shape is `ResumeFailureDetailsSchema` (`@objectstack/spec/api`);
+       * the code stays `FLOW_FAILED` (no `FLOW_STRANDED` sibling). The
+       * trigger door's 400 carries `errorMessage` / `summary` only — it never
+       * resumes, so "repairable" has no referent there.
+       *
        * A **stale** suspension (the flow deregistered, or the node edited away
        * under a live pause) rejects with **404** rather than 400: nothing ran,
        * and the pause is gone for good. The refusals that leave the suspension