fix(api): qualify run recovery and trace duration guidance

Author: waleedlatif1

.agents/skills/v2-api-conventions/SKILL.md

@@ -197,10 +197,11 @@ Audited against the primary specs and against Stripe, GitHub, and Google's AIPs.
 `POST /workflows/{id}/execute` accepts `X-Run-Id` from API-key and OAuth callers; anonymous requests ignore it. It is a **uniqueness claim, not an idempotency key**:
 
 - An available ID is claimed before execution starts.
-- An already claimed ID returns **409** with `error.details.code: "RUN_ID_CONFLICT"`, the run id in `error.details.runId`, and an `X-Run-Id` response header. It never replays the earlier run's result — the client recovers it by polling the runs resource.
+- An already claimed ID returns **409** with `error.details.code: "RUN_ID_CONFLICT"`, the run id in `error.details.runId`, and an `X-Run-Id` response header. It never replays the earlier run's result. Get Workflow Run can retrieve an existing run, but a claim does not guarantee a retrievable run.
 - IDs of runs that started remain reserved after their execution logs are deleted.
+- An ambiguous enqueue can retain the claim indefinitely without creating a retrievable run. A **409** followed by **404** is an unresolved outcome, not proof that execution never started or that the ID will become reusable.
 
-For an uncertain execution outcome, retry with the same run ID or poll Get Workflow Run. A fresh ID or an omitted header can start another execution; never describe either as a safe retry of the original request. Failures before a run starts can release the claim, so phrase the conflict rule as an ID that is already claimed.
+For an uncertain execution outcome, reuse the same run ID if retrying and check Get Workflow Run. Do not promise polling will eventually find a run. If the outcome cannot be verified, do not automatically restart with a fresh ID or an omitted header: either can start another execution. Failures before a run starts can release the claim, so phrase the conflict rule as an ID that is already claimed.
 
 That makes the money path safe against double-execution **for callers that opt in**. What it is not: a Stripe-style `Idempotency-Key` that stores and replays the original status and body. Building that means a request fingerprint, a retention window, an in-flight-vs-completed distinction (the expired IETF draft would have these be 422 and 409 respectively), and somewhere to put a large synchronous execution body. It is a designed piece of work, not an increment — do not half-build it by aliasing the header name, which would invite clients written against Stripe semantics to treat our 409 as a hard failure.
 

apps/docs/openapi-v2-logs.json

@@ -1109,11 +1109,11 @@
           },
           "duration": {
             "type": "number",
-            "description": "Span duration in milliseconds."
+            "description": "Current trace-span duration in milliseconds."
           },
           "durationMs": {
             "type": "number",
-            "description": "Span duration in milliseconds."
+            "description": "Compatibility field for span duration in milliseconds. Read `duration` for current trace spans."
           },
           "startTime": {
             "type": "string",

apps/docs/openapi-v2-workflows.json

@@ -2532,9 +2532,9 @@
             "name": "x-run-id",
             "in": "header",
             "required": false,
-            "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it when retrying an uncertain request. An already claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying the result; use Get Workflow Run to check progress. A fresh ID or an omitted header can start another run.",
+            "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
             "schema": {
-              "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it when retrying an uncertain request. An already claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying the result; use Get Workflow Run to check progress. A fresh ID or an omitted header can start another run.",
+              "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
               "type": "string",
               "minLength": 1,
               "maxLength": 128,

apps/sim/lib/api/contracts/logs.ts

@@ -218,8 +218,13 @@ export const traceSpanSchema: z.ZodType<LogTraceSpan> = z
         id: z.string().describe('Trace-span identifier.'),
         name: z.string().describe('Trace-span name.'),
         type: z.string().describe('Trace-span category.'),
-        duration: z.number().describe('Span duration in milliseconds.').optional(),
-        durationMs: z.number().describe('Span duration in milliseconds.').optional(),
+        duration: z.number().describe('Current trace-span duration in milliseconds.').optional(),
+        durationMs: z
+          .number()
+          .describe(
+            'Compatibility field for span duration in milliseconds. Read `duration` for current trace spans.'
+          )
+          .optional(),
         startTime: z.string().describe('ISO 8601 span start timestamp.').optional(),
         endTime: z.string().describe('ISO 8601 span end timestamp.').optional(),
         status: z.string().describe('Trace-span status.').optional(),

apps/sim/lib/api/contracts/v2/workflows.ts

@@ -69,15 +69,12 @@ export const v2WorkflowRunIdSchema = runIdSchema
   .meta({ examples: ['run_8f14e45f-ceea-467f-a'] })
 
 /**
- * `X-Run-Id` is a **one-shot uniqueness claim, not an idempotency key.** The
- * first request to claim a value starts a run; every later request reusing it
- * is rejected with a `409` carrying `error.details.code: "RUN_ID_CONFLICT"`, and
- * the original result is never
- * replayed. Retry logic written against idempotency-key semantics either
- * double-executes (fresh id per attempt) or hard-fails (same id per attempt).
+ * `X-Run-Id` reserves an execution ID without guaranteeing a retrievable run.
+ * Claims can survive uncertain execution outcomes; a missing run does not make
+ * a claimed ID reusable. Reusing a claimed ID returns a conflict, never a replay.
  */
 const X_RUN_ID_DESCRIPTION =
-  'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it when retrying an uncertain request. An already claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying the result; use Get Workflow Run to check progress. A fresh ID or an omitted header can start another run.'
+  'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.'
 
 const X_SIM_VIA_DESCRIPTION =
   'Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with `409` and `error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED"`.'

packages/sim-cli/src/generated/v2-api.ts

@@ -11418,7 +11418,7 @@ export const V2_OPERATIONS = {
       'x-run-id': {
         kind: 'string',
         describe:
-          'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it when retrying an uncertain request. An already claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying the result; use Get Workflow Run to check progress. A fresh ID or an omitted header can start another run.',
+          'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.',
       },
       'x-sim-via': {
         kind: 'string',