@hasna/loops 0.4.27 → 0.4.28

package/dist/lib/executor.d.ts

@@ -56,6 +56,15 @@ interface MachineCommandPlan {
 }
 /** Exported for tests: resolves the default idle watchdog for agent targets. */
 export declare function defaultAgentIdleTimeoutMs(target: AgentTarget, opts: ExecuteOptions): number | undefined;
+/**
+ * Detects git's "missing but already registered worktree" error: the target
+ * path is recorded in `.git/worktrees/` but its directory was deleted out from
+ * under it, so `git worktree add` refuses. git's own prescribed remedy is
+ * `git worktree prune` (or `add -f`). Left unhandled this terminal-fails worktree
+ * prep on every attempt and the drain dedupes the failed item into a silent
+ * wedge — historically the single biggest burner of the redispatch cap.
+ */
+export declare function isStaleWorktreeRegistration(detail: string | undefined): boolean;
 export declare function preflightTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): PreflightResult;
 export declare function executeTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): Promise<ExecutorResult>;
 export declare function executeLoop(loop: Loop, run: LoopRun, opts?: ExecuteOptions): Promise<ExecutorResult>;

package/dist/lib/migration.d.ts

@@ -1,6 +1,7 @@
 import type { Loop, LoopRun, WorkflowSpec } from "../types.js";
 import type { Store, StoreMigrationChecks } from "./store.js";
 export declare const LOOPS_MIGRATION_SCHEMA = "open-loops.migration/v1";
+export declare const LOOPS_SELF_HOSTED_PUSH_MANIFEST_SCHEMA = "open-loops.self-hosted-push-manifest/v1";
 export type LoopsMigrationResource = "workflow" | "loop" | "run" | "remote";
 export type LoopsMigrationAction = "insert" | "update" | "skip" | "conflict" | "blocked";
 export interface LoopsMigrationBundle {
@@ -67,6 +68,7 @@ export interface LoopsMigrationPlan {
     summary: LoopsMigrationPlanSummary;
     rows: LoopsMigrationPlanRow[];
     warnings: string[];
+    manifest?: SelfHostedPushManifest;
 }
 export interface ApplyLoopsMigrationResult {
     plan: LoopsMigrationPlan;
@@ -83,6 +85,7 @@ export interface SelfHostedPlanOptions {
     fetchImpl?: typeof fetch;
     env?: NodeJS.ProcessEnv;
     includeRuns?: boolean;
+    replace?: boolean;
 }
 export interface RunnerRegistrationOptions {
     apiUrl?: string;
@@ -134,6 +137,69 @@ export interface SelfHostedPushResult {
         orphanRuns: number;
     };
     requests: number;
+    manifest: SelfHostedPushManifest;
+}
+export interface SelfHostedPushManifest {
+    schema: typeof LOOPS_SELF_HOSTED_PUSH_MANIFEST_SCHEMA;
+    generatedAt: string;
+    apiUrl?: string;
+    dryRun: boolean;
+    replace: boolean;
+    includeRuns: boolean;
+    safety: {
+        forcedLoopStatus: "paused";
+        clearedLoopRunPointers: true;
+        forcedWorkflowStatus: "archived";
+        resumesLoops: false;
+    };
+    counts: {
+        source: {
+            workflows: number;
+            loops: number;
+            runs: number;
+        };
+        remoteBefore: {
+            workflows?: number;
+            loops?: number;
+            runs?: number;
+        };
+        remoteAfter?: {
+            workflows?: number;
+            loops?: number;
+            runs?: number;
+        };
+        plan: LoopsMigrationPlanSummary;
+        applied?: {
+            workflows: number;
+            loops: number;
+            runs: number;
+        };
+        skipped?: {
+            runningRuns: number;
+            orphanRuns: number;
+        };
+        requests?: number;
+    };
+    missingIds: {
+        workflows: string[];
+        loops: string[];
+        runs: string[];
+    };
+    existingIds: {
+        workflows: string[];
+        loops: string[];
+        runs: string[];
+    };
+    unsafe: {
+        blocked: LoopsMigrationPlanRow[];
+        conflicts: LoopsMigrationPlanRow[];
+        unsupported: string[];
+        warnings: string[];
+    };
+    rollback: {
+        notes: string[];
+        commands: string[];
+    };
 }
 /**
  * Apply a local->self-hosted backfill through the control plane's id-preserving

package/dist/lib/mode.js

@@ -2,7 +2,7 @@
 // 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",
@@ -112,6 +112,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",
@@ -121,8 +122,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",

package/dist/lib/route/fields.d.ts

@@ -15,6 +15,14 @@ export declare function firstTruthyField(records: Record<string, unknown>[], key
 export declare function automationRecords(data: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>[];
 export declare function tagsFromValue(value: unknown): string[];
 export declare function taskEventTags(records: Record<string, unknown>[]): string[];
+/**
+ * First route-disallowed tag on a task, if any. Exposed so drains can exclude
+ * tasks that can never route (no-auto/blocked/manual/…) from the bounded
+ * candidate window *before* slicing, instead of letting them occupy scan slots
+ * every tick only to be rejected by eligibility — the "skip re-burns the window
+ * forever" half of the merge-lane decay.
+ */
+export declare function taskRouteDisallowedTag(tags: string[]): string | undefined;
 export declare function taskRouteEligibility(data: Record<string, unknown>, metadata: Record<string, unknown>): {
     eligible: boolean;
     reason?: string;

package/dist/lib/storage/index.js

@@ -1569,6 +1569,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"]);
@@ -1711,6 +1712,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,
@@ -1860,6 +1862,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);
 }
@@ -1960,11 +1979,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()) {
@@ -1975,8 +2004,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 [
@@ -2043,6 +2074,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");
+        }
       }
     ];
   }
@@ -3173,7 +3210,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,
@@ -3301,6 +3338,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);
@@ -3310,6 +3348,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
@@ -4021,6 +4099,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");
@@ -5321,6 +5401,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;
     `)
 ]);
 
@@ -6671,11 +6754,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");

package/dist/lib/storage/postgres-loop-storage.d.ts

@@ -101,8 +101,8 @@ export declare class PostgresLoopStorage implements LoopStorageContract {
     listGoalRuns(...args: M<"listGoalRuns">["args"]): Promise<M<"listGoalRuns">["result"]>;
     createWorkflow(...args: M<"createWorkflow">["args"]): Promise<M<"createWorkflow">["result"]>;
     archiveWorkflow(...args: M<"archiveWorkflow">["args"]): Promise<M<"archiveWorkflow">["result"]>;
-    createWorkflowInvocation(): never;
-    upsertWorkflowWorkItem(): never;
+    createWorkflowInvocation(...args: M<"createWorkflowInvocation">["args"]): Promise<M<"createWorkflowInvocation">["result"]>;
+    upsertWorkflowWorkItem(...args: M<"upsertWorkflowWorkItem">["args"]): Promise<M<"upsertWorkflowWorkItem">["result"]>;
     admitWorkflowWorkItem(): never;
     createGoal(): never;
     createGoalPlanNodes(): never;

package/dist/lib/storage/postgres-schema.js

@@ -352,6 +352,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;
     `)
 ]);
 export {

package/dist/lib/storage/postgres.js

@@ -352,6 +352,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;
     `)
 ]);
 

package/dist/lib/storage/sqlite.js

@@ -1569,6 +1569,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"]);
@@ -1711,6 +1712,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,
@@ -1860,6 +1862,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);
 }
@@ -1960,11 +1979,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()) {
@@ -1975,8 +2004,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 [
@@ -2043,6 +2074,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");
+        }
       }
     ];
   }
@@ -3173,7 +3210,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,
@@ -3301,6 +3338,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);
@@ -3310,6 +3348,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
@@ -4021,6 +4099,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");

package/dist/lib/store/index.d.ts

@@ -81,6 +81,7 @@ export interface LoopStore {
     getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
     requeueWorkflowWorkItem(id: string, patch?: {
         reason?: string;
+        resetAttempts?: boolean;
     }): Promise<WorkflowWorkItem>;
     listWorkflowInvocations(opts?: {
         limit?: number;
@@ -174,6 +175,7 @@ export declare class LocalStore implements LoopStore {
     getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
     requeueWorkflowWorkItem(id: string, patch?: {
         reason?: string;
+        resetAttempts?: boolean;
     }): Promise<WorkflowWorkItem>;
     listWorkflowInvocations(opts?: Parameters<Store["listWorkflowInvocations"]>[0]): Promise<WorkflowInvocation[]>;
     getWorkflowInvocation(id: string): Promise<WorkflowInvocation | undefined>;
@@ -242,6 +244,7 @@ export declare class ApiStore implements LoopStore {
     getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
     requeueWorkflowWorkItem(_id: string, _patch?: {
         reason?: string;
+        resetAttempts?: boolean;
     }): Promise<WorkflowWorkItem>;
     listWorkflowInvocations(opts?: Parameters<LoopStore["listWorkflowInvocations"]>[0]): Promise<WorkflowInvocation[]>;
     getWorkflowInvocation(id: string): Promise<WorkflowInvocation | undefined>;