@hasna/loops 0.4.27 → 0.4.28

package/dist/serve/index.js

@@ -1571,6 +1571,7 @@ var DEFAULT_RECOVERY_BATCH_LIMIT = 100;
 var DEFAULT_RECOVERY_SCAN_MULTIPLIER = 5;
 var LIVE_EXPIRED_RUN_GRACE_MS = 60000;
 var SCHEMA_USER_VERSION = 8;
+var BREAKING_SCHEMA_FLOOR = 7;
 var TERMINAL_RUN_STATUSES = ["succeeded", "failed", "timed_out", "abandoned", "skipped"];
 var PRUNE_BATCH_SIZE = 400;
 var GENERATED_ROUTE_TEMPLATE_IDS = new Set(["todos-task-worker-verifier", "task-lifecycle", "event-worker-verifier"]);
@@ -1713,6 +1714,7 @@ function rowToWorkflowWorkItem(row) {
     priority: row.priority,
     status: row.status,
     attempts: row.attempts,
+    gateDeaths: row.gate_deaths ?? 0,
     nextAttemptAt: row.next_attempt_at ?? undefined,
     leaseExpiresAt: row.lease_expires_at ?? undefined,
     workflowId: row.workflow_id ?? undefined,
@@ -1862,6 +1864,23 @@ function workItemStatusForLoopRun(status, attempt, maxAttempts) {
   }
   return;
 }
+var WORK_ITEM_TEMPFAIL_EXIT_CODE = 75;
+var GATE_STEP_IDS = new Set(["triage", "planner", "plan"]);
+var GATE_DEATH_MAX_DURATION_MS = 60000;
+var GATE_DEATH_CEILING = 20;
+function classifyNonProductiveStepFailure(steps) {
+  const failing = [...steps].reverse().find((step) => step.status === "failed" || step.status === "timed_out");
+  if (!failing)
+    return;
+  if (failing.exitCode === WORK_ITEM_TEMPFAIL_EXIT_CODE)
+    return "tempfail";
+  if (typeof failing.error === "string" && failing.error.includes("worktree preparation failed"))
+    return "gate-death";
+  const fast = failing.durationMs === undefined || failing.durationMs < GATE_DEATH_MAX_DURATION_MS;
+  if (GATE_STEP_IDS.has(failing.stepId) && fast)
+    return "gate-death";
+  return;
+}
 function scrubbedOrNull(value) {
   return value == null ? null : scrubSecrets(value);
 }
@@ -1962,11 +1981,21 @@ class Store {
         id TEXT PRIMARY KEY,
         applied_at TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS schema_compat (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        min_compatible_user_version INTEGER NOT NULL
+      );
     `);
     const versionRow = this.db.query("PRAGMA user_version").get();
     const userVersion = versionRow?.user_version ?? 0;
     if (userVersion > SCHEMA_USER_VERSION) {
-      throw new Error(`loops database schema version ${userVersion} is newer than this binary supports (${SCHEMA_USER_VERSION}); upgrade open-loops before opening this database`);
+      const floorRow = this.db.query("SELECT min_compatible_user_version FROM schema_compat WHERE id = 1").get();
+      if (!floorRow) {
+        throw new Error(`loops database schema version ${userVersion} is newer than this binary supports (${SCHEMA_USER_VERSION}) and carries no compatibility floor; upgrade open-loops before opening this database`);
+      }
+      if (SCHEMA_USER_VERSION < floorRow.min_compatible_user_version) {
+        throw new Error(`loops database schema version ${userVersion} requires a binary with schema support >= ${floorRow.min_compatible_user_version} (this binary supports ${SCHEMA_USER_VERSION}); upgrade open-loops before opening this database`);
+      }
     }
     const applied = new Set(this.db.query("SELECT id FROM schema_migrations").all().map((row) => row.id));
     for (const migration of this.migrations()) {
@@ -1977,8 +2006,10 @@ class Store {
         this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run(migration.id, nowIso());
       }
     }
-    if (userVersion !== SCHEMA_USER_VERSION)
+    if (userVersion < SCHEMA_USER_VERSION)
       this.db.exec(`PRAGMA user_version = ${SCHEMA_USER_VERSION}`);
+    this.db.query(`INSERT INTO schema_compat (id, min_compatible_user_version) VALUES (1, ?)
+         ON CONFLICT(id) DO UPDATE SET min_compatible_user_version = MAX(min_compatible_user_version, excluded.min_compatible_user_version)`).run(BREAKING_SCHEMA_FLOOR);
   }
   migrations() {
     return [
@@ -2045,6 +2076,12 @@ class Store {
           this.addColumnIfMissing("workflow_work_items", "machine_id", "TEXT");
           this.db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_work_items_machine ON workflow_work_items(machine_id, status)");
         }
+      },
+      {
+        id: "0011_work_item_gate_deaths",
+        apply: () => {
+          this.addColumnIfMissing("workflow_work_items", "gate_deaths", "INTEGER NOT NULL DEFAULT 0");
+        }
       }
     ];
   }
@@ -3175,7 +3212,7 @@ class Store {
   }
   upsertWorkflowWorkItem(input) {
     const now = nowIso();
-    const id = genId();
+    const id = input.id ?? genId();
     const status = input.status ?? "queued";
     this.db.query(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
           subject_ref, project_key, project_group, machine_id, route_scope, priority, status, attempts, next_attempt_at, lease_expires_at,
@@ -3303,6 +3340,7 @@ class Store {
     const placeholders = requeueableStatuses.map(() => "?").join(",");
     const res = this.db.query(`UPDATE workflow_work_items
          SET status='queued', workflow_id=NULL, loop_id=NULL, workflow_run_id=NULL,
+          ${patch.resetAttempts ? "attempts=0, gate_deaths=0," : ""}
           next_attempt_at=NULL, lease_expires_at=NULL, last_reason=?, updated_at=?
          WHERE id=? AND status IN (${placeholders})`).run(reason, now, id, ...requeueableStatuses);
     const item = this.getWorkflowWorkItem(id);
@@ -3312,6 +3350,46 @@ class Store {
       throw new Error(`workflow work item was not requeued: ${id} status=${item.status}`);
     return item;
   }
+  deadLetterWorkflowWorkItem(id, patch = {}) {
+    const now = nowIso();
+    const reason = patch.reason?.trim() || "redispatch cap reached; dead-lettered";
+    this.db.query(`UPDATE workflow_work_items
+         SET status='dead_letter', next_attempt_at=NULL, lease_expires_at=NULL, last_reason=?, updated_at=?
+         WHERE id=? AND status IN ('succeeded','failed','cancelled')`).run(reason, now, id);
+    const item = this.getWorkflowWorkItem(id);
+    if (!item)
+      throw new Error(`workflow work item not found after dead-letter: ${id}`);
+    return item;
+  }
+  demoteNonProductiveWorkItems(workflowRunId, finishedAt) {
+    const kind = classifyNonProductiveStepFailure(this.listWorkflowStepRuns(workflowRunId));
+    if (!kind) {
+      this.db.query("UPDATE workflow_work_items SET gate_deaths=0, updated_at=? WHERE workflow_run_id=? AND status='failed' AND gate_deaths > 0").run(finishedAt, workflowRunId);
+      return;
+    }
+    if (kind === "tempfail") {
+      this.db.query(`UPDATE workflow_work_items
+           SET status='queued', attempts=CASE WHEN attempts > 0 THEN attempts - 1 ELSE 0 END,
+            gate_deaths=0,
+            workflow_id=NULL, loop_id=NULL, workflow_run_id=NULL,
+            next_attempt_at=NULL, lease_expires_at=NULL,
+            last_reason='worker exited 75 (tempfail): requeued for retry; attempt refunded (does not count toward redispatch cap)',
+            updated_at=?
+           WHERE workflow_run_id=? AND status='failed'`).run(finishedAt, workflowRunId);
+      return;
+    }
+    this.db.query(`UPDATE workflow_work_items
+         SET attempts=CASE WHEN attempts > 0 THEN attempts - 1 ELSE 0 END,
+          gate_deaths=gate_deaths + 1,
+          status=CASE WHEN gate_deaths + 1 >= ${GATE_DEATH_CEILING} THEN 'dead_letter' ELSE status END,
+          last_reason=CASE
+            WHEN gate_deaths + 1 >= ${GATE_DEATH_CEILING}
+              THEN 'gate-death ceiling reached (' || (gate_deaths + 1) || '/${GATE_DEATH_CEILING} consecutive runs died at worktree prep / triage / planner without reaching the worker): dead-lettered \u2014 the infrastructure fault needs an operator; ''loops routes requeue'' resets and retries'
+            ELSE 'gate death before real work (worktree prep / triage / planner): attempt refunded (does not count toward redispatch cap); consecutive gate deaths: ' || (gate_deaths + 1) || '/${GATE_DEATH_CEILING}'
+          END,
+          updated_at=?
+         WHERE workflow_run_id=? AND status='failed'`).run(finishedAt, workflowRunId);
+  }
   admitWorkflowWorkItem(id, patch) {
     const now = nowIso();
     const res = this.db.query(`UPDATE workflow_work_items
@@ -4023,6 +4101,8 @@ class Store {
       if (changed) {
         const itemStatus = status === "succeeded" ? "succeeded" : status === "cancelled" ? "cancelled" : "failed";
         this.setWorkflowWorkItemsForWorkflowRun(workflowRunId, itemStatus, error, finishedAt);
+        if (itemStatus === "failed")
+          this.demoteNonProductiveWorkItems(workflowRunId, finishedAt);
         this.maybeArchiveTerminalGeneratedRouteWorkflow(workflowRunId, finishedAt);
       }
       this.db.exec("COMMIT");
@@ -4972,7 +5052,7 @@ class Store {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.27",
+  version: "0.4.28",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5082,6 +5162,7 @@ var package_default = {
     bun: ">=1.0.0"
   },
   dependencies: {
+    "@hasna/contracts": "^0.5.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -5091,8 +5172,7 @@ var package_default = {
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49",
-    "@hasna/contracts": "^0.4.2"
+    "@hasna/machines": "0.0.49"
   },
   devDependencies: {
     "@types/bun": "latest",
@@ -5412,6 +5492,14 @@ var loops_default = {
               type: "integer"
             }
           },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
           {
             name: "includeArchived",
             in: "query",
@@ -5687,6 +5775,22 @@ var loops_default = {
             schema: {
               type: "integer"
             }
+          },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
+          {
+            name: "showOutput",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
           }
         ],
         responses: {
@@ -5743,6 +5847,14 @@ var loops_default = {
             schema: {
               type: "string"
             }
+          },
+          {
+            name: "showOutput",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
           }
         ],
         responses: {
@@ -5763,7 +5875,7 @@ var loops_default = {
       post: {
         operationId: "importRows",
         summary: "Bulk id-preserving import (self-hosted backfill)",
-        description: "Upsert full workflow/loop/run rows by id (idempotent; ON CONFLICT(id) DO UPDATE). Preserves id, status, archived state, and timestamps. Applied FK-safe: workflows, then loops, then runs. Volatile running runs are skipped and reported.",
+        description: "Upsert full workflow/loop/run rows by id (idempotent; ON CONFLICT(id) DO UPDATE). Preserves ids, definitions, and timestamps while applying safe defaults: imported workflows are archived, imported loops are paused, and nextRunAt/retryScheduledFor are cleared by default so backfills never schedule immediately. Set preserveWorkflowActivation=true or preserveLoopScheduling=true only for intentional activation. Applied FK-safe: workflows, then loops, then runs. Volatile running runs are skipped and reported.",
         requestBody: {
           required: true,
           content: {
@@ -5788,51 +5900,141 @@ var loops_default = {
         }
       }
     },
-    "/v1/receipts": {
+    "/v1/workflows": {
       get: {
-        operationId: "listRunReceipts",
-        summary: "List run receipts",
+        operationId: "listWorkflows",
+        summary: "List workflow specs",
         parameters: [
           {
-            name: "loopId",
+            name: "status",
             in: "query",
             required: false,
             schema: {
-              type: "string"
+              type: "string",
+              enum: [
+                "active",
+                "archived"
+              ]
             }
           },
           {
-            name: "repo",
+            name: "limit",
             in: "query",
             required: false,
             schema: {
-              type: "string"
+              type: "integer"
             }
           },
           {
-            name: "taskId",
+            name: "offset",
             in: "query",
             required: false,
             schema: {
-              type: "string"
+              type: "integer"
             }
-          },
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow specs",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "createWorkflow",
+        summary: "Create a workflow spec",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/CreateWorkflowInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "workflow",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/workflows/count": {
+      get: {
+        operationId: "countWorkflows",
+        summary: "Count workflow specs",
+        parameters: [
           {
-            name: "knowledgeId",
+            name: "status",
             in: "query",
             required: false,
             schema: {
               type: "string"
             }
-          },
+          }
+        ],
+        responses: {
+          "200": {
+            description: "count",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/CountResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/workflows/{id}": {
+      get: {
+        operationId: "getWorkflow",
+        summary: "Get a workflow spec by id",
+        parameters: [
           {
-            name: "status",
-            in: "query",
-            required: false,
+            name: "id",
+            in: "path",
+            required: true,
             schema: {
               type: "string"
             }
-          },
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/invocations": {
+      get: {
+        operationId: "listWorkflowInvocations",
+        summary: "List workflow route invocations",
+        parameters: [
           {
             name: "limit",
             in: "query",
@@ -5844,11 +6046,11 @@ var loops_default = {
         ],
         responses: {
           "200": {
-            description: "run receipts",
+            description: "workflow invocations",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/RunReceiptListResponse"
+                  $ref: "#/components/schemas/WorkflowInvocationListResponse"
                 }
               }
             }
@@ -5856,25 +6058,25 @@ var loops_default = {
         }
       },
       post: {
-        operationId: "writeRunReceipt",
-        summary: "Write a run receipt",
+        operationId: "createWorkflowInvocation",
+        summary: "Create an id-preserving workflow route invocation",
         requestBody: {
           required: true,
           content: {
             "application/json": {
               schema: {
-                $ref: "#/components/schemas/WriteRunReceiptInput"
+                $ref: "#/components/schemas/CreateWorkflowInvocationInput"
               }
             }
           }
         },
         responses: {
           "201": {
-            description: "run receipt",
+            description: "workflow invocation",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/RunReceiptResponse"
+                  $ref: "#/components/schemas/WorkflowInvocationResponse"
                 }
               }
             }
@@ -5882,51 +6084,215 @@ var loops_default = {
         }
       }
     },
-    "/v1/receipts/{runId}": {
+    "/v1/work-items": {
       get: {
-        operationId: "getRunReceipt",
-        summary: "Get a run receipt by run id",
+        operationId: "listWorkflowWorkItems",
+        summary: "List workflow route work items",
         parameters: [
           {
-            name: "runId",
-            in: "path",
-            required: true,
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "routeKey",
+            in: "query",
+            required: false,
             schema: {
               type: "string"
             }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
           }
         ],
         responses: {
           "200": {
-            description: "run receipt",
+            description: "workflow work items",
             content: {
               "application/json": {
                 schema: {
-                  $ref: "#/components/schemas/RunReceiptResponse"
+                  $ref: "#/components/schemas/WorkflowWorkItemListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "upsertWorkflowWorkItem",
+        summary: "Upsert an id-preserving workflow route work item",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/UpsertWorkflowWorkItemInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "workflow work item",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowWorkItemResponse"
                 }
               }
             }
           }
         }
       }
-    }
-  },
-  components: {
-    schemas: {
-      Foundation: {
-        type: "object",
-        properties: {
-          status: {
-            type: "string"
+    },
+    "/v1/receipts": {
+      get: {
+        operationId: "listRunReceipts",
+        summary: "List run receipts",
+        parameters: [
+          {
+            name: "loopId",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
           },
-          version: {
-            type: "string"
+          {
+            name: "repo",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
           },
-          mode: {
-            type: "string"
+          {
+            name: "taskId",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
           },
-          service: {
-            type: "string"
+          {
+            name: "knowledgeId",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "run receipts",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RunReceiptListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "writeRunReceipt",
+        summary: "Write a run receipt",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/WriteRunReceiptInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "run receipt",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RunReceiptResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/receipts/{runId}": {
+      get: {
+        operationId: "getRunReceipt",
+        summary: "Get a run receipt by run id",
+        parameters: [
+          {
+            name: "runId",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "run receipt",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/RunReceiptResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  components: {
+    schemas: {
+      Foundation: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string"
+          },
+          version: {
+            type: "string"
+          },
+          mode: {
+            type: "string"
+          },
+          service: {
+            type: "string"
           },
           detail: {
             type: "string"
@@ -6390,6 +6756,352 @@ var loops_default = {
           "receipts"
         ]
       },
+      Workflow: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string",
+            nullable: true
+          },
+          version: {
+            type: "integer"
+          },
+          status: {
+            type: "string"
+          },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
+            }
+          },
+          goal: {
+            type: "object",
+            additionalProperties: true
+          },
+          createdAt: {
+            type: "string"
+          },
+          updatedAt: {
+            type: "string"
+          }
+        },
+        required: [
+          "id",
+          "name",
+          "version",
+          "status",
+          "steps"
+        ]
+      },
+      CreateWorkflowInput: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string"
+          },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
+            }
+          },
+          goal: {
+            type: "object",
+            additionalProperties: true
+          }
+        },
+        required: [
+          "name",
+          "steps"
+        ]
+      },
+      WorkflowResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workflow: {
+            $ref: "#/components/schemas/Workflow"
+          }
+        },
+        required: [
+          "ok",
+          "workflow"
+        ]
+      },
+      WorkflowListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workflows: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/Workflow"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "workflows"
+        ]
+      },
+      CreateWorkflowInvocationInput: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          workflowId: {
+            type: "string"
+          },
+          templateId: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "object",
+            additionalProperties: true
+          },
+          subjectRef: {
+            type: "object",
+            additionalProperties: true
+          },
+          intent: {
+            type: "string"
+          },
+          scope: {
+            type: "object",
+            additionalProperties: true
+          },
+          outputPolicy: {
+            type: "object",
+            additionalProperties: true
+          }
+        },
+        required: [
+          "sourceRef",
+          "subjectRef",
+          "intent"
+        ]
+      },
+      WorkflowInvocation: {
+        allOf: [
+          {
+            $ref: "#/components/schemas/CreateWorkflowInvocationInput"
+          },
+          {
+            type: "object",
+            properties: {
+              id: {
+                type: "string"
+              },
+              createdAt: {
+                type: "string"
+              },
+              updatedAt: {
+                type: "string"
+              }
+            },
+            required: [
+              "id",
+              "createdAt",
+              "updatedAt"
+            ]
+          }
+        ]
+      },
+      WorkflowInvocationResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          invocation: {
+            $ref: "#/components/schemas/WorkflowInvocation"
+          }
+        },
+        required: [
+          "ok",
+          "invocation"
+        ]
+      },
+      WorkflowInvocationListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          invocations: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/WorkflowInvocation"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "invocations"
+        ]
+      },
+      WorkflowWorkItem: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          id: {
+            type: "string"
+          },
+          routeKey: {
+            type: "string"
+          },
+          idempotencyKey: {
+            type: "string"
+          },
+          invocationId: {
+            type: "string"
+          },
+          sourceType: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "string"
+          },
+          subjectRef: {
+            type: "string"
+          },
+          status: {
+            type: "string"
+          },
+          priority: {
+            type: "integer"
+          },
+          createdAt: {
+            type: "string"
+          },
+          updatedAt: {
+            type: "string"
+          }
+        },
+        required: [
+          "id",
+          "routeKey",
+          "idempotencyKey",
+          "invocationId",
+          "sourceType",
+          "sourceRef",
+          "subjectRef",
+          "status",
+          "priority"
+        ]
+      },
+      UpsertWorkflowWorkItemInput: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          routeKey: {
+            type: "string"
+          },
+          idempotencyKey: {
+            type: "string"
+          },
+          invocationId: {
+            type: "string"
+          },
+          sourceType: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "string"
+          },
+          subjectRef: {
+            type: "string"
+          },
+          projectKey: {
+            type: "string"
+          },
+          projectGroup: {
+            type: "string"
+          },
+          machineId: {
+            type: "string"
+          },
+          routeScope: {
+            type: "string"
+          },
+          priority: {
+            type: "integer"
+          },
+          status: {
+            type: "string",
+            enum: [
+              "queued",
+              "deferred"
+            ]
+          },
+          nextAttemptAt: {
+            type: "string"
+          },
+          lastReason: {
+            type: "string"
+          }
+        },
+        required: [
+          "routeKey",
+          "idempotencyKey",
+          "invocationId",
+          "sourceType",
+          "sourceRef",
+          "subjectRef"
+        ]
+      },
+      WorkflowWorkItemResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workItem: {
+            $ref: "#/components/schemas/WorkflowWorkItem"
+          }
+        },
+        required: [
+          "ok",
+          "workItem"
+        ]
+      },
+      WorkflowWorkItemListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workItems: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/WorkflowWorkItem"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "workItems"
+        ]
+      },
       ImportInput: {
         type: "object",
         description: "Batches of full rows to upsert by id. Any array may be omitted.",
@@ -6417,7 +7129,15 @@ var loops_default = {
           },
           replace: {
             type: "boolean",
-            description: "Update existing rows whose id matches (default false: existing rows are left unchanged)."
+            description: "Update existing rows whose id matches. Default safe imports may still archive/pause same-id workflows/loops when preserve flags are false."
+          },
+          preserveLoopScheduling: {
+            type: "boolean",
+            description: "Default false. When false, imported loops are written paused with nextRunAt and retryScheduledFor cleared so backfills never schedule immediately."
+          },
+          preserveWorkflowActivation: {
+            type: "boolean",
+            description: "Default false. When false, imported workflows are written archived, including same-id active rows, so backfills cannot activate workflow execution unless explicitly requested."
           }
         }
       },
@@ -6652,6 +7372,21 @@ async function handleV1Request(ctx) {
     return errorResponse(error);
   }
 }
+function safeImportedWorkflow(workflow, opts) {
+  if (opts.preserveWorkflowActivation)
+    return workflow;
+  return { ...workflow, status: "archived" };
+}
+function safeImportedLoop(loop, opts) {
+  if (opts.preserveLoopScheduling)
+    return loop;
+  return {
+    ...loop,
+    status: "paused",
+    nextRunAt: undefined,
+    retryScheduledFor: undefined
+  };
+}
 async function handleImportRequest(ctx, segments) {
   if (segments.length !== 0 || ctx.request.method !== "POST")
     return fail("not_found", 404);
@@ -6661,14 +7396,20 @@ async function handleImportRequest(ctx, segments) {
   const workflows = Array.isArray(body.workflows) ? body.workflows : [];
   const loops = Array.isArray(body.loops) ? body.loops : [];
   const runs = Array.isArray(body.runs) ? body.runs : [];
+  const preserveWorkflowActivation = body.preserveWorkflowActivation === true;
+  const preserveLoopScheduling = body.preserveLoopScheduling === true;
   const imported = { workflows: 0, loops: 0, runs: 0 };
   let skippedRunning = 0;
   for (const workflow of workflows) {
-    await storage.upsertMigrationWorkflow(workflow, { replace });
+    await storage.upsertMigrationWorkflow(safeImportedWorkflow(workflow, { preserveWorkflowActivation }), {
+      replace: replace || !preserveWorkflowActivation
+    });
     imported.workflows += 1;
   }
   for (const loop of loops) {
-    await storage.upsertMigrationLoop(loop, { replace });
+    await storage.upsertMigrationLoop(safeImportedLoop(loop, { preserveLoopScheduling }), {
+      replace: replace || !preserveLoopScheduling
+    });
     imported.loops += 1;
   }
   for (const run of runs) {
@@ -6827,6 +7568,10 @@ async function handleWorkItemsRequest(ctx, segments) {
     });
     return ok({ workItems: items.map(publicWorkflowWorkItem) });
   }
+  if (segments.length === 0 && ctx.request.method === "POST") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    return ok({ workItem: publicWorkflowWorkItem(await storage.upsertWorkflowWorkItem(body)) }, { status: 201 });
+  }
   const id = segments[0];
   if (!id)
     return fail("not_found", 404);
@@ -6844,6 +7589,10 @@ async function handleInvocationsRequest(ctx, segments) {
     const invocations = await storage.listWorkflowInvocations({ limit: optionalLimit(ctx.url.searchParams.get("limit")) });
     return ok({ invocations: invocations.map(publicWorkflowInvocation) });
   }
+  if (segments.length === 0 && ctx.request.method === "POST") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    return ok({ invocation: publicWorkflowInvocation(await storage.createWorkflowInvocation(body)) }, { status: 201 });
+  }
   const id = segments[0];
   if (!id)
     return fail("not_found", 404);
@@ -7680,6 +8429,9 @@ CREATE INDEX IF NOT EXISTS idx_run_receipts_knowledge_ids ON run_receipts USING
   migration("0006_work_item_machine_id", `
 ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS machine_id TEXT;
 CREATE INDEX IF NOT EXISTS idx_workflow_work_items_machine ON workflow_work_items(machine_id, status);
+    `),
+  migration("0007_work_item_gate_deaths", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS gate_deaths INTEGER NOT NULL DEFAULT 0;
     `)
 ]);
 
@@ -8972,11 +9724,118 @@ class PostgresLoopStorage {
       throw new Error(`workflow not found after archive: ${existing.id}`);
     return archived;
   }
-  createWorkflowInvocation() {
-    throw new NotImplementedError("createWorkflowInvocation");
+  async createWorkflowInvocation(...args) {
+    const [input] = args;
+    const now = nowIso();
+    const sourceDedupeKey = input.sourceRef.dedupeKey ?? undefined;
+    if (sourceDedupeKey) {
+      const existing = await this.client.get("SELECT * FROM workflow_invocations WHERE source_kind = $1 AND source_dedupe_key = $2 LIMIT 1", [input.sourceRef.kind, sourceDedupeKey]);
+      if (existing)
+        return rowToWorkflowInvocation(existing);
+    }
+    const id = input.id ?? genId();
+    await this.client.execute(`INSERT INTO workflow_invocations (id, workflow_id, template_id, source_kind, source_id, source_dedupe_key,
+        source_json, subject_kind, subject_id, subject_path, subject_url, subject_json, intent, scope_json,
+        output_policy_json, created_at, updated_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8,$9,$10,$11,$12::jsonb,$13,$14::jsonb,$15::jsonb,$16,$17)`, [
+      id,
+      input.workflowId ?? null,
+      input.templateId ?? null,
+      input.sourceRef.kind,
+      input.sourceRef.id ?? null,
+      sourceDedupeKey ?? null,
+      JSON.stringify(input.sourceRef),
+      input.subjectRef.kind,
+      input.subjectRef.id ?? null,
+      input.subjectRef.path ?? null,
+      input.subjectRef.url ?? null,
+      JSON.stringify(input.subjectRef),
+      input.intent,
+      input.scope ? JSON.stringify(input.scope) : null,
+      input.outputPolicy ? JSON.stringify(input.outputPolicy) : null,
+      now,
+      now
+    ]);
+    const row = await this.client.get("SELECT * FROM workflow_invocations WHERE id = $1", [id]);
+    if (!row)
+      throw new Error(`workflow invocation not found after create: ${id}`);
+    return rowToWorkflowInvocation(row);
   }
-  upsertWorkflowWorkItem() {
-    throw new NotImplementedError("upsertWorkflowWorkItem");
+  async upsertWorkflowWorkItem(...args) {
+    const [input] = args;
+    const now = nowIso();
+    const id = input.id ?? genId();
+    const status = input.status ?? "queued";
+    await this.client.execute(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
+        subject_ref, project_key, project_group, machine_id, route_scope, priority, status, attempts, next_attempt_at,
+        lease_expires_at, workflow_id, loop_id, workflow_run_id, last_reason, created_at, updated_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,0,$14,NULL,NULL,NULL,NULL,$15,$16,$17)
+       ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
+        invocation_id=excluded.invocation_id,
+        source_type=excluded.source_type,
+        source_ref=excluded.source_ref,
+        subject_ref=excluded.subject_ref,
+        project_key=excluded.project_key,
+        project_group=excluded.project_group,
+        machine_id=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled') THEN workflow_work_items.machine_id
+          ELSE excluded.machine_id
+        END,
+        route_scope=excluded.route_scope,
+        priority=excluded.priority,
+        status=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled')
+            THEN workflow_work_items.status
+          ELSE excluded.status
+        END,
+        workflow_id=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled') THEN workflow_work_items.workflow_id
+          ELSE NULL
+        END,
+        loop_id=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled') THEN workflow_work_items.loop_id
+          ELSE NULL
+        END,
+        workflow_run_id=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled') THEN workflow_work_items.workflow_run_id
+          ELSE NULL
+        END,
+        lease_expires_at=CASE
+          WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled') THEN workflow_work_items.lease_expires_at
+          ELSE NULL
+        END,
+        next_attempt_at=excluded.next_attempt_at,
+        last_reason=CASE
+          WHEN workflow_work_items.attempts > 0
+            AND workflow_work_items.status IN ('queued', 'deferred')
+            AND workflow_work_items.last_reason IS NOT NULL
+            AND excluded.last_reason IS NOT NULL
+            THEN workflow_work_items.last_reason || '; ' || excluded.last_reason
+          ELSE COALESCE(excluded.last_reason, workflow_work_items.last_reason)
+        END,
+        updated_at=excluded.updated_at`, [
+      id,
+      input.routeKey,
+      input.idempotencyKey,
+      input.invocationId,
+      input.sourceType,
+      input.sourceRef,
+      input.subjectRef,
+      input.projectKey ?? null,
+      input.projectGroup ?? null,
+      input.machineId ?? null,
+      input.routeScope ?? null,
+      input.priority ?? 0,
+      status,
+      input.nextAttemptAt ?? null,
+      input.lastReason ?? null,
+      now,
+      now
+    ]);
+    const row = await this.client.get("SELECT * FROM workflow_work_items WHERE route_key = $1 AND idempotency_key = $2 LIMIT 1", [input.routeKey, input.idempotencyKey]);
+    if (!row)
+      throw new Error(`workflow work item not found after upsert: ${input.routeKey}/${input.idempotencyKey}`);
+    return rowToWorkflowWorkItem(row);
   }
   admitWorkflowWorkItem() {
     throw new NotImplementedError("admitWorkflowWorkItem");